Manage container metadata

This page describes how to containerize, upload to Artifact Registry, and manage metadata about a container image stored in Artifact Registry as an attachment.

Attachments are OCI artifacts and can only be stored in Docker-format repositories.

Before you begin

1. If you don't already have one, create a Docker-format standard repository.
2. (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.

1. Install Oras 1.2 or later. To verify your version, run the oras version command.

2. Configure Oras to authenticate with Artifact Registry.

Create attachments

You can create an attachment by using the gcloud CLI or Oras.

gcloud

Before using any of the command data below, make the following replacements:

• ATTACHMENT: the fully qualified name of the attachment. For example, 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.
• TARGET: 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, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.
• TYPE: the attachment's type attribute. This must comply with OCI specifications for the artifactType property.
• ATTACHMENT_NAMESPACE: a variable specific to attachments that identifies the attachment data source. For example, example.com.
• FILES: a comma-separated list of local files to include in the attachment.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments create ATTACHMENT \
    --target=TARGET \
    --type=TYPE \
    --attachment-namespace=ATTACHMENT_NAMESPACE \
    --files=FILES

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments create ATTACHMENT `
    --target=TARGET `
    --type=TYPE `
    --attachment-namespace=ATTACHMENT_NAMESPACE `
    --files=FILES

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments create ATTACHMENT ^
    --target=TARGET ^
    --type=TYPE ^
    --attachment-namespace=ATTACHMENT_NAMESPACE ^
    --files=FILES

For more information, see the gcloud artifacts attachments create command.

Oras

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:

• ARTIFACT_TYPE: the artifactType of the attachment.

• IMAGE_URI: the URI for the image container the attachment refers to.

• FILE: a local file to include as metadata in the attachment.

• MEDIA_TYPE: the 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 the artifactType 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 the mediaType 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.

Console

1. In the Google Cloud console, open the Repositories page.

   Open the Repositories page

2. Click the repository name to see images in your repository.

3. To see the versions of an image, click the image name.

4. Click the appropriate image version.

5. To see the attachments for that version, click the Attachments tab.

gcloud

Before using any of the command data below, make the following replacements:

• TARGET: 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, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments list \
    --target=TARGET

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments list `
    --target=TARGET

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments list ^
    --target=TARGET

For more information, see the gcloud artifacts attachments list command.

Oras

Before running the command, make the following replacement:

• IMAGE_URI: the URI of the target image referred to by any listed attachments.

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.

gcloud

Before using any of the command data below, make the following replacements:

• ATTACHMENT: the fully qualified name of the attachment. For example, 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.
• DESTINATION: the path in your local file system to download the attachment to.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments download ATTACHMENT \
    --destination=DESTINATION

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments download ATTACHMENT `
    --destination=DESTINATION

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments download ATTACHMENT ^
    --destination=DESTINATION

As an alternative to providing 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.

Oras

Before running the command, make the following replacements:

• DESTINATION: the destination directory for your attachment.

• ATTACHMENT_URI: 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.

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:

Console

1. In the Google Cloud console, open the Repositories page.

   Open the Repositories page

2. Click the repository name to see images in your repository.

3. Click the image name to see versions of that image.

4. Click the version of the image you to see attachments for.

5. Click the Attachments tab to see attachments for that version.

6. Click the digest of the attachment to delete.

7. Click DELETE.

8. In the confirmation dialog, click DELETE.

gcloud

Before using any of the command data below, make the following replacements:

• ATTACHMENT: the fully qualified name of the attachment. For example, 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

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

For more information, see the 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.

Note: Cleanup policies don't apply directly to attachments. However, if a cleanup policy deletes a container image, all attachments which refer to that container image are deleted.