Manage images (original) (raw)

This page explains how to manage container images in a Docker repository. Managing images includes listing images in a repository, adding tags, deleting tags, copying images to a new repository, and deleting images.

For information about pushing and pulling images, seePushing and pulling images.

Before you begin

  1. If the target repository does not exist,create a new repository.
  2. Verify that you have the required permissions for the repository.
  3. (Optional) Configure defaults for gcloud commands.

Required roles

To get the permissions that you need to manage images, ask your administrator to grant you the following IAM roles on the repository:

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.

Listing images

Repository modes: standard, remote

You can list the images using the Google Cloud console or gcloud CLI.

The repository list includes both Artifact Registry and Container Registry repositories. To work with images in a Container Registry repository, see the Container Registry documentation for managing images.

Console

To view images in a repository:

  1. Open the Repositories page in the Google Cloud console.
    Open the Repositories page
  2. Click the repository with the container image.
  3. Click an image to see its versions.

gcloud

To list all images in the default project, repository, and location when the default values are configured:

gcloud artifacts docker images list

To list images in a repository in a specific location, run the command:

gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT/REPOSITORY

To list all digests and tags for a specific image, run the command:

gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE \
--include-tags

Replace the following values:

For example, consider an image with the following characteristics:

The full repository name is:

us-west1-docker.pkg.dev/my-project/my-repo

The full image name is:

us-west1-docker.pkg.dev/my-project/my-repo/my-image

For details about the image name format, see Repository and image names.

Listing files

Repository modes: standard, remote

You can list files in a repository, files in all versions of a specified container image, or files in a specific version of an image.

For all the following commands, you can set a maximum number of files to return by adding the --limit flag to the command.

To list all files in the default project, repository, and location when the default values are configured:

gcloud artifacts files list

To list files in a specified project, repository, and location, run the command:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

To list files for all versions of a specific container image:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

To list files for a specific container image version:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

To list files for a specific tag:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --tag=TAG

Replace the following values:

Examples

Consider the following image information:

The following command lists all files in the repository my-repo in the location us-west1 within the default project:

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

The following command lists files in the version of the image with the digest sha256:88b205d7995332e10e836514fbfd59ecaf8976fc15060cd66e85cdcebe7fb356

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=sha256:88b205d7995332e10e836514fbfd59ecaf8976fc15060cd66e85cdcebe7fb356

The following command lists files in the version of the image with the tag 1.0-dev

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --tag=1.0-dev

Tagging images

You can tag existing images in an Artifact Registry repository or you can tag them before you push them to a repository.

Tagging images in a repository

Repository modes: standard

You can add a tag to an image in an Artifact Registry repository using theGoogle Cloud console or the command line. In a repository, tags are unique to a version of an image. So if you have multiple versions of an image, each tag only applies to one of the versions. If you tag an image with a tag that's already in use, you will move the tag from the original version to the newly tagged version.

Console

To tag an image in a repository:

  1. Open the Repositories page in the Google Cloud console.
    Open the Repositories page
  2. Click the image to view versions of the image.
  3. Select the image version to tag.
  4. In the row of the selected version, click More actions (More actions), and then click Edit tags.
  5. Type new tags into the field and then click SAVE.

gcloud

To tag images in a repository, specify the image version using the image digest or tag, and then specify the tag to add. Run one of the following commands:

gcloud artifacts docker tags add IMAGE-VERSION TAG

Where

For example, consider an image with the following characteristics:

To add the tag release-candidate to the version of the image with the tagiteration6-final, run the following command:

gcloud artifacts docker tags add \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:iteration6-final \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:release-candidate

For details about the image name format, including domain-scoped projects, seeRepository and image names.

Tagging local images

To push any local image to Artifact Registry, you need to first tag it with the repository name and then push the image. For instructions, seePushing and pulling.

Untagging images

Repository modes: standard

You can remove a tag from an image in Artifact Registry using theGoogle Cloud console or the command line.

Console

  1. Open the Repositories page in the Google Cloud console.
    Open the Repositories page
  2. Click the image to view versions of the image.
  3. Select the image version to untag.
  4. In the row of the selected version, click More actions (More actions), and then click Edit tags.
  5. Delete the tag and then click SAVE.

gcloud

To delete a tag and remove it from the image, run the following command:

 gcloud artifacts docker tags delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG

Replace the following:

Deleting images

Repository modes: standard, remote

You can delete an entire container image or delete a specific image version associated with a tag or digest. Removing unused images can help you to reduce storage costs.

You can use cleanup policies to control when and how your artifacts are saved or deleted.

To delete an images from Google Cloud console or the gcloud CLI:

Console

  1. Open the Repositories page in the Google Cloud console.
    Open the Repositories page
  2. Click the image name to see versions of that image.
  3. Select versions that you want to delete.
  4. Click DELETE.
  5. In the confirmation dialog, click DELETE.

gcloud

To delete an image and all its tags, run the command:

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE --delete-tags

To delete a specific image version, use one of the following commands.

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG [--delete-tags]

or

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE@IMAGE-DIGEST [--delete-tags]

Where

What's next