Attachments are OCI artifacts and can only be stored in Docker-format repositories.
Before you begin
- If you don't already have one, create a Docker-format standard repository.
- (Optional) Configure defaults for Google Cloud CLI commands.
Required roles
To get the permissions that you need to manage attachments, ask your administrator to grant you the following IAM roles on the repository:
-
View and download attachments:
Artifact Registry Reader (
roles/artifactregistry.reader
) -
Create attachments:
Artifact Registry Writer (
roles/artifactregistry.writer
) -
Delete attachments:
Artifact Registry Repository Administrator (
roles/artifactregistry.repoAdmin
)
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Set up Oras (optional)
In addition to using gcloud CLI, you can optionally use Oras to create, list, and download attachments.
Install Oras 1.2 or later. To verify your version, run the
oras version
command.Configure Oras to authenticate with Artifact Registry.
Create attachments
You can create an attachment by using the gcloud CLI or Oras.
Before using any of the command data below, make the following replacements:
: the fully qualified name of the attachment. For example,ATTACHMENT projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment
. Alternatively, provide only the attachment ID and use the--location
and--repository
flags.
: the fully qualified version name or the Artifact Registry URI of the artifact the attachment will refer to. You can use either the digest or the tag. For example,TARGET us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1
.
: the attachment'sTYPE type
attribute. This must comply with OCI specifications for theartifactType
property.
: a variable specific to attachments that identifies the attachment data source. For example,ATTACHMENT_NAMESPACE example.com
.
: a comma-separated list of local files to include in the attachment.FILES
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud artifacts attachments createATTACHMENT \ --target=TARGET \ --attachment-type=TYPE \ --attachment-namespace=ATTACHMENT_NAMESPACE \ --files=FILES
Windows (PowerShell)
gcloud artifacts attachments createATTACHMENT ` --target=TARGET ` --attachment-type=TYPE ` --attachment-namespace=ATTACHMENT_NAMESPACE ` --files=FILES
Windows (cmd.exe)
gcloud artifacts attachments createATTACHMENT ^ --target=TARGET ^ --attachment-type=TYPE ^ --attachment-namespace=ATTACHMENT_NAMESPACE ^ --files=FILES
gcloud artifacts attachments create
command.
When creating an attachment with Oras, Artifact Registry generates a random UUID to use as the attachment name.
Before running the command, make the following replacements:
: theARTIFACT_TYPE artifactType
of the attachment.
: the URI for the image container the attachment refers to.IMAGE_URI
: a local file to include as metadata in the attachment.FILE
: theMEDIA_TYPE mediaType
of the layer.
oras attach --artifact-type ARTIFACT_TYPE IMAGE_URI FILE :MEDIA_TYPE
The following example creates an attachment consisting of a file,
hello-world.txt
, that refers to a container image, my-image
, identified by
its URI and tag:
oras attach --artifact-type doc/example \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 \
hello-world.txt:application/vnd.me.hi
Where:
doc/example
defines theartifactType
property of the attachment.us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1
is the URI including the tag of the container image version the attachment will refer to.hello-world.txt
is the local file that the attachment will hold as its data.application/vnd.me.hi
defines themediaType
of the layer.
For a full guide and more examples, see the oras attach
documentation.
List attachments
A container image can have any number of attachments that refer to it. You can list attachments by using the Google Cloud console, the gcloud CLI, or Oras.
In the Google Cloud console, open the Repositories page.
Click the repository name to see images in your repository.
To see the versions of an image, click the image name.
Click the appropriate image version.
To see the attachments for that version, click the Attachments tab.
Before using any of the command data below, make the following replacements:
: the fully qualified version name or the Artifact Registry URI of the artifact you want to list attachments for. You can use either the digest or the tag. For example,TARGET us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1
.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud artifacts attachments list \ --target=TARGET
Windows (PowerShell)
gcloud artifacts attachments list ` --target=TARGET
Windows (cmd.exe)
gcloud artifacts attachments list ^ --target=TARGET
gcloud artifacts attachments list
command.
Before running the command, make the following replacement:
: the URI of the target image referred to by any listed attachments.IMAGE_URI
oras discover --distribution-spec v1.1-referrers-api IMAGE_URI
The following example lists attachments for a container image, my-image
,
identified by its URI and tag:
oras discover --distribution-spec v1.1-referrers-api \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Where:
v1.1-referrers-api
is the Referrer API used. For more information, see the details in the distribution spec.us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1
is the URI including the tag of the container image version to list attachments for.
For a full guide and more examples, see the oras discover
documentation.
Download attachments
You can download attachments by using the gcloud CLI or Oras.
Before using any of the command data below, make the following replacements:
: the fully qualified name of the attachment. For example,ATTACHMENT projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment
. Alternatively, provide only the attachment ID here and use the--location
and--repository
flags.
: the path in your local file system to download the attachment to.DESTINATION
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud artifacts attachments downloadATTACHMENT \ --destination=DESTINATION
Windows (PowerShell)
gcloud artifacts attachments downloadATTACHMENT ` --destination=DESTINATION
Windows (cmd.exe)
gcloud artifacts attachments downloadATTACHMENT ^ --destination=DESTINATION
ATTACHMENT
, you can provide the
--oci-version-name
flag followed by the attachment's full version name or
Artifact Registry URI. You can use either the digest or the tag. For example,
projects/my-project/locations/us-west1/repositories/my-repo/packages/my-package/versions/sha256:abc123
.For more information, see the
gcloud artifacts attachments download
command.
Before running the command, make the following replacements:
: the destination directory for your attachment.DESTINATION
: the URI of the attachment to download. This is the URI for the image container the attachment refers to, followed by the attachment's unique SHA.ATTACHMENT_URI
oras pull -o DESTINATION ATTACHMENT_URI
The following example downloads an attachment identified by its URI and digest:
oras pull -o . us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx
Where:
-o .
names the current directory as the download destination.us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx
is the image URI including the digest of the attachment to download.
For a full guide and more examples, see the oras pull
documentation.
Delete attachments
You can delete attachments directly by using the Google Cloud console or the gcloud CLI. You can delete attachments indirectly by deleting the container image it refers to.
Delete attachments directly
You can delete attachments directly with one of the following options:
In the Google Cloud console, open the Repositories page.
Click the repository name to see images in your repository.
Click the image name to see versions of that image.
Click the version of the image you to see attachments for.
Click the Attachments tab to see attachments for that version.
Click the digest of the attachment to delete.
Click DELETE.
In the confirmation dialog, click DELETE.
Before using any of the command data below, make the following replacements:
: the fully qualified name of the attachment. For example,ATTACHMENT projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment
. Alternatively, provide only the attachment ID here and use the--location
and--repository
flags.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud artifacts attachments deleteATTACHMENT
Windows (PowerShell)
gcloud artifacts attachments deleteATTACHMENT
Windows (cmd.exe)
gcloud artifacts attachments deleteATTACHMENT
gcloud artifacts attachments list
command.
Delete attachments indirectly
If a container image is deleted, all referring attachments are also deleted. This applies to both the manual deletion of container images and to deletions caused by cleanup policies.