Managing images

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 a local image to Container Registry or pulling an image stored in Container Registry, see Pushing and pulling images.

Caution: Only use registry commands to work with your stored images. Aside from configuring access control, avoid directly configuring or manipulating objects in Cloud Storage storage buckets used by Container Registry. Some Cloud Storage features such as object-level permissions and retention policies are unsupported. If these features are configured they might be ignored or cause issues.

Before you begin

Make sure that you:

1. Enabled Container Registry in your project.

2. Installed Docker.

3. Configured Docker to authenticate to the registry.

4. Have permissions to access the registry.

Listing images by their storage location

You can list the images in a specific host locations using the Google Cloud console or the command line.

Console

To list the images in one of your host locations:

1. Go to the Container Registry page.

   Open the Container Registry page

2. Use the selector above Name to choose the host location. Options include All locations and the host names that the project currently uses, which can include gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

gcloud

To list the images that are in one of your host locations, use the following command:

gcloud container images list --repository=[HOSTNAME]/[PROJECT-ID]

where:

• [HOSTNAME] is listed under Location in the console. It's one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
• [PROJECT-ID] is your Google Cloud console project ID. If your project ID contains a colon (:), see Domain-scoped projects.

If you have nested registries, list the nested images by specifying the repository level where they are stored:

gcloud container images list --repository=[HOSTNAME]/[PROJECT-ID]/[IMAGE]

where [IMAGE] is the repository under which more images are nested.

Also see the gcloud container images list documentation.

Listing the versions of an image

A registry can contain different versions of an image. These versions have the same image name, and are identified by their digest and tags.

Console

To see an image's digest and tags:

1. Go to the Container Registry page.

   Open the Container Registry page

2. Click on the image name to see versions of that image. The truncated digest is listed under Name and the tags are listed under Tags.

3. To get the full digest, click on the version of the image to see its metadata. The digest is called Image digest.

gcloud

To list an image's truncated digests and tags, run the following command:

gcloud container images list-tags [HOSTNAME]/[PROJECT-ID]/[IMAGE]

where:

• [HOSTNAME] is listed under Location in the console. It's one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
• [PROJECT-ID] is your Google Cloud console project ID. If your project ID has a colon in it (:) see Domain-scoped projects.
• [IMAGE] is the image's name in Container Registry.

To list the full digest the version(s) of a specific image, run the following command:

gcloud container images list-tags --format='get(digest)' [HOSTNAME]/[PROJECT-ID]/[IMAGE]

See the gcloud container images list-tags documentation.

Tagging images

You can add a tag to an image using the Google Cloud console or the command line.

A digest is an automatically-generated unique identifier for an image version. A tag acts as a label that you can apply to a specific version of an image.

You can add more than one tag to an image. Within a repository, each tag for an image must be unique. For example, if you add the tag release-candidate to the ninth version of your image, adding the same tag to the tenth version will move the tag from the ninth version to the tenth version.

If you do not tag an image, the Docker client adds the default tag latest. This means that latest does not indicate the most recent version of an image. Instead it means an image version that you specifically tagged as latest, or the most recent untagged version of an image. Since the meaning of latest is unclear, we recommend avoiding reliance on the latest tag.

Console

To tag an image hosted by Container Registry:

1. Go to the Container Registry page.

   Open the Container Registry page

2. Click on the image name to see version of that image.

3. Under Tags, click the edit icon.

4. Type new tags into the field and then click SAVE.

gcloud

To tag images hosted by Container Registry, use the gcloud container images add-tag command:

gcloud container images add-tag \
[HOSTNAME]/[PROJECT-ID]/[IMAGE]:[TAG] \
[HOSTNAME]/[PROJECT-ID]/[IMAGE]:[NEW_TAG]

or

gcloud container images add-tag \
[HOSTNAME]/[PROJECT-ID]/[IMAGE]@[IMAGE_DIGEST] \
[HOSTNAME]/[PROJECT-ID]/[IMAGE]:[NEW_TAG]

where:

• [HOSTNAME] is listed under Location in the console. It's one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
• [PROJECT-ID] is your Google Cloud console project ID. If your project ID has a colon in it (:) see Domain-scoped projects.
• [IMAGE] is the image's name in Container Registry.
• [TAG] is a tag that's already applied to the image.
• [IMAGE_DIGEST] is the sha256 hash value of the image contents.
• [NEW_TAG] is the new tag that you're adding to the image.

See gcloud container images add-tag for more info about this command.

Tagging local images for hosting on Container Registry

To push any local image to Container Registry, you need to first tag it with the registry name and then push the image. For instructions, see Pushing an image to a registry.

Untagging images

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

Console

1. Go to the Container Registry page.

   Open the Container Registry page

2. Click on the image name to see version of that image.

3. Under Tags, click the edit icon.

4. Delete the tag and then click SAVE.

gcloud

To remove a tag from an image use the following command:

gcloud container images untag [HOSTNAME]/[PROJECT-ID]/[IMAGE]:[TAG]

where:

• [HOSTNAME] is listed under Location in the console. It's one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
• [PROJECT-ID] is your Google Cloud console project ID. If your project ID has a colon in it (:) see Domain-scoped projects.
• [IMAGE] is the image's name in Container Registry.

• [TAG] is the tag you want to remove.

  See gcloud container images untag for more info about this command.

Copying images to a new registry

You can copy an image from one repository into another using the command line. You must have access to both repositories.

To copy an image from one repository into another, use the gcloud container images add-tag command, and identify the image to be moved by its tag:

gcloud container images add-tag \
[SOURCE_HOSTNAME]/[SOURCE_PROJECT-ID]/[SOURCE_IMAGE]:[SOURCE_TAG] \
[DESTINATION_HOSTNAME]/[DESTINATION_PROJECT-ID]/[DESTINATION_IMAGE]:[DESTINATION_TAG]

or its digest:

gcloud container images add-tag \
[SOURCE_HOSTNAME]/[SOURCE_PROJECT-ID]/[SOURCE_IMAGE]@[IMAGE_DIGEST] \
[DESTINATION_HOSTNAME]/[DESTINATION_PROJECT-ID]/[DESTINATION_IMAGE]:[DESTINATION_TAG]

where, for both the source and destination:

• [HOSTNAME] is the location where the image is hosted, and is one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
• [PROJECT-ID] is the Google Cloud console project ID. If your project ID has a colon in it (:) see Domain-scoped projects.
• [IMAGE] is the image's name in Container Registry.
• [IMAGE_DIGEST] is the sha256 hash value of the image contents.
• [TAG] is the tag that identifies the source image to move, or the tag to apply to the image in the destination repository.

For example, if you wanted to copy the image my-image into another project's repository and into the European host, but you want to keep the image name and tag the same, you would use:

gcloud container images add-tag \
gcr.io/[PROJECT-ID]/my-image:tag1 \
eu.gcr.io/[OTHER-PROJECT-ID]/my-image:tag1

where [PROJECT-ID] and [OTHER-PROJECT-ID] are your Google Cloud console project IDs of the project you are copying from, and the project you are copying to. You must have access to the repositories in both of these projects. If either of the project IDs has a colon in it (:) see Domain-scoped projects.

See gcloud container images add-tag for more info about this command.

Deleting images

You can delete an image using the Google Cloud console or the command line. Once you've deleted an image, you cannot undo this action.

Other tools are available to help you manage unused images. For example the gcr-cleaner tool finds and deletes old images based on different criteria. Removing unused images can help you to reduce storage costs. The gcr-cleaner tool is not an official Google product.

Note: Do not apply Cloud Storage retention policies to storage buckets used by Container Registry. These policies do not work for managing images in Container Registry storage buckets.

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

Console

1. Go to the Container Registry page.

   Open the Container Registry page

2. Click on the image name to see version(s) of that image.

3. In the registry, check the box next to the version(s) of the image that you want to delete.

4. Click DELETE on the top of the page.

5. In the Delete repository items pop-up, click DELETE.

gcloud

Run one of the following commands:

• An image identified by its digest:

  gcloud container images delete [HOSTNAME]/[PROJECT-ID]/[IMAGE]@[IMAGE_DIGEST]
  

• An image identified by its tag, and it has multiple tags:

  gcloud container images delete [HOSTNAME]/[PROJECT-ID]/[IMAGE]:[TAG] --force-delete-tags
  

where:

• [HOSTNAME] is listed under Location in the console. It's one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
• [PROJECT-ID] is your Google Cloud console project ID. If your project ID has a colon in it (:) see Domain-scoped projects.
• [IMAGE] is the image's name in Container Registry.
• [IMAGE_DIGEST] is the sha256 hash value of the image contents.
• [TAG] is the tag of the image you want to remove.

See the gcloud container images delete for more information about this command.

What's next

• Learn about configuring access control.
• Read more about Container Registry's components and features.