Skip to content

registry_images_.md

Latest commit

 

History

History
421 lines (282 loc) · 26.6 KB

registry_images_.md

File metadata and controls

421 lines (282 loc) · 26.6 KB
Raw
copyright
years
2017, 2026
lastupdated 2026-08-03
keywords Docker, private repository, images, building images, trash, recycle bin, restoring images, namespace, cli, tag, api key, upload images, pull images, push images
subcollection Registry

{{site.data.keyword.attribute-definition-list}}

Adding images to your namespace in {{site.data.keyword.registryshort}}

{: #registry_images_}

You can securely store and share Docker images with other users by adding images to your namespace{: term} in {{site.data.keyword.registrylong}}. {: shortdesc}

Every image that you want to add to your namespace must exist on your local computer first. You can either download (pull) an image from another repository to your local computer, or build your own image from a Dockerfile{: term} by using the Docker build command. To add an image to your namespace, you must upload (push) the local image to your namespace in {{site.data.keyword.registrylong_notm}}.

Do not put personal information in your container images, namespace names, description fields, or in any image configuration data (for example, image names or image labels). {: important}

Pulling images from another registry

{: #registry_images_pulling_reg} {: help} {: support}

You can pull (download) an image from any private or public registry{: term} source to your computer, and then tag it for later use in {{site.data.keyword.registrylong_notm}}.

Pull an image from a private or public registry to your computer.{: caption="Pulling images from another registry" caption-side="bottom"}{: external download="../images/pulling_images_mul.svg"}

Before you begin, complete the following tasks.

  1. Download the image, see Pull an image in the Getting Started documentation.

    If you get an unauthorized: authentication required or a denied: requested access to the resource is denied message, run the ibmcloud cr login command. {: tip}

After you pull an image and tag it for your namespace, you can upload (push) the image from your local computer to your namespace.

If you deploy a workload that pulls an image from {{site.data.keyword.registryshort_notm}} and your pods fail with an ImagePullBackOff status, see Why do images fail to pull from registry with ImagePullBackOff or authorization errors? for assistance. {: tip}

Pushing Docker images to your namespace

{: #registry_images_pushing_namespace} {: help} {: support}

You can push (upload) an image from your computer to your namespace in {{site.data.keyword.registrylong_notm}} to store your image and share it with other users.

Push an image from your computer to {{site.data.keyword.registrylong_notm}}.{: caption="Push images to your namespace" caption-side="bottom"}{: external download="../images/pushing_images_mul.svg"}

Before you begin, complete the following tasks.

{{site.data.keyword.registrylong_notm}} supports other clients as well as Docker. To log in by using other clients, see Accessing your namespaces interactively. {: tip}

To upload (push) an image, complete the following steps:

  1. Log in to the CLI by running the ibmcloud cr login command.

    ibmcloud cr login

    {: pre}

    You must log in if you pull an image from your private {{site.data.keyword.registrylong_notm}}. {: requirement}

    If you have a problem when you try to log in, see Why can't I log in to {{site.data.keyword.registryshort_notm}}? for assistance. {: tip}

  2. To view all namespaces that are available in your account, run the ibmcloud cr namespace-list command.

  3. Upload the image to your namespace.

    If you get an unauthorized: authentication required or a denied: requested access to the resource is denied message, run the ibmcloud cr login command. {: tip}

After you push your image to {{site.data.keyword.registrylong_notm}}, you can do one of the following tasks.

Copying images between registries

{: #registry_images_copying} {: help} {: support}

You can copy images between registries by pulling an image from a registry in one region and pushing it to a registry in another region so that you can share the image with users in both regions.

Copying images between registries.{: caption="Copying images between registries" caption-side="bottom"}{: external download="../images/copying_images_mul.svg"}

Before you begin, complete the following tasks.

To copy an image between two registries, complete the following steps:

  1. Pull an image from a registry.
  2. Push the image to another registry. Make sure that you use the correct domain name for the new region you're targeting.

After you copy your image, you can do one of the following tasks.

Creating images that refer to a source image

{: #registry_images_source} {: help} {: support}

Create an image by using the ibmcloud cr image-tag command.

In the region that you're logged in to, create an image in {{site.data.keyword.registrylong_notm}} that refers to an existing image in the same region. This action is supported for source images that are created by using supported versions of Docker Engine, see Support for Docker.

New images that are created by using this mechanism do not retain signatures. If you require the new image to be signed, do not use this mechanism. {: important}

Before you begin, complete the following tasks.

  • Install the CLI to work with images in your namespace.
  • Ensure that you have access to a private namespace in {{site.data.keyword.registrylong_notm}} that contains a source image to which you want to refer another image.

To create an image from a source image, complete the following steps.

  1. Log in to the CLI by running the ibmcloud cr login command.

    ibmcloud cr login

    {: pre}

  2. Run the following command to add the new reference, where SOURCE_IMAGE is the name of your source image and TARGET_IMAGE is the name of your target image. The source and target images must be in the same region. SOURCE_IMAGE must be in the format repository:tag or repository@digest and TARGET_IMAGE must be in the format repository:tag, for example, us.icr.io/namespace/image:latest.

    To find the names of your images, run ibmcloud cr image-list. Combine the content of the Repository column (repository) and Tag column (tag) separated by a colon (:) to create the image name in the format repository:tag. To identify your image by digest, run the ibmcloud cr image-digests command. Combine the content of the Repository column (repository) and the Digest column (digest) separated by an at (@) symbol to create the image name in the format repository@digest. If the list images command times out, see Why is it timing out when I list images? for assistance. {: tip}

    ibmcloud cr image-tag [SOURCE_IMAGE] [TARGET_IMAGE]

    {: pre}

  3. Verify that the new image was created by running the following command, and check that the image is shown in the list with the same image digest as the source image.

    ibmcloud cr image-list

    {: pre}

Pushing images by using an API key

{: #registry_api_key_push_image} {: help} {: support}

Create a service ID that uses an API key{: term} to push images to {{site.data.keyword.registrylong_notm}}.

Complete the following steps:

  1. Create a service ID, see Creating and working with service IDs.
  2. Create a policy that gives the service ID permission to access the registry, for example, Administrator and Manager roles, see Managing IAM access for {{site.data.keyword.registryshort_notm}}.
  3. Create an API key, see Creating an API key for a service ID.
  4. Use the API key to log in to registry so that you can push images to the registry, see Automating access to {{site.data.keyword.registrylong_notm}}.
  5. Push your images, see Pushing Docker images to your namespace.

You can now use clusters to pull the images, see Building containers from images.

Removing tags from images in your private repository

{: #registry_images_untag} {: help} {: support}

You can remove a tag, or tags, from an image in your private {{site.data.keyword.cloud_notm}} repository, and make sure that the underlying image and any other tags remain in place by using the ibmcloud cr image-untag command.

If multiple tags exist for the same image digest within a repository and you want to remove the underlying image and all its tags, see Deleting images from your private {{site.data.keyword.cloud_notm}} repository. {: tip}

To remove a tag, or tags, by using the CLI, complete the following steps:

  1. Log in to {{site.data.keyword.cloud_notm}} by running the ibmcloud login command.

  2. To remove a tag, run the following command, where IMAGE is the name of the image that you want to remove, in the format repository:tag. If a tag is not specified in the image name, the command fails. You can delete the tags for multiple images by listing each private {{site.data.keyword.cloud_notm}} registry path in the command with a space between each path.

    ibmcloud cr image-untag IMAGE

    To find the names of your images, run ibmcloud cr image-list. Combine the content of the Repository column (repository) and Tag column (tag) separated by a colon (:) to create the image name in the format repository:tag. {: tip}

  3. Verify that the tag was removed by running the following command, and check that the tag does not show in the list.

    ibmcloud cr image-list

    {: pre}

    If the list images command times out, see Why is it timing out when I list images? for assistance. {: tip}

Deleting images from your private repository

{: #registry_images_remove}

You can delete unwanted images from your private {{site.data.keyword.cloud_notm}} repository by using either the {{site.data.keyword.cloud_notm}} console or the CLI.

If you want to delete a private repository and its associated images, see Deleting a private repository and any associated images.

Deleting an image that is being used by an existing deployment might cause scale-up, reschedule, or both, to fail. {: attention}

If you want to restore a deleted image, you can list the contents of the trash by running the ibmcloud cr trash-list command and restore a selected image by running the ibmcloud cr image-restore command. {: tip}

You can't delete images from the trash. Images are stored in the trash for 30 days. You are not billed for any images that are in the trash. {: note}

Where multiple tags exist for the same image digest within a repository, the ibmcloud cr image-rm command removes the underlying image and all its tags. If the same image exists in a different repository or namespace, the copy of the image is not removed. If you want to remove a tag from an image and make sure that the underlying image and any other tags remain in place, see Removing tags from images in your private repository command. {: tip}

Deleting images from your private repository in the CLI

{: #registry_images_remove_cli}

You can delete unwanted images and all their tags from your private {{site.data.keyword.cloud_notm}} repository by using the CLI.

Deleting an image that is being used by an existing deployment might cause scale-up, reschedule, or both, to fail. {: attention}

If you want to restore a deleted image, you can list the contents of the trash by running the ibmcloud cr trash-list command and restore a selected image by running the ibmcloud cr image-restore command. {: tip}

To delete an image by using the CLI, complete the following steps:

  1. Log in to {{site.data.keyword.cloud_notm}} by running the ibmcloud login command.

  2. To delete an image, run the following command, where IMAGE is the name of the image that you want to remove, in the format repository@digest or repository:tag. If a tag is not specified in the image name, the image tagged latest is deleted by default. You can delete multiple images by listing each private {{site.data.keyword.cloud_notm}} registry path in the command with a space between each path.

    ibmcloud cr image-rm IMAGE

    {: pre}

    To find the names of your images, run ibmcloud cr image-list. Combine the content of the Repository column (repository) and Tag column (tag) separated by a colon (:) to create the image name in the format repository:tag. To identify your image by digest, run the ibmcloud cr image-digests command. Combine the content of the Repository column (repository) and the Digest column (digest) separated by an at (@) symbol to create the image name in the format repository@digest. If the list images command times out, see Why is it timing out when I list images? for assistance. {: tip}

  3. Verify that the image was deleted by running the following command, and check that the image does not show in the list.

    ibmcloud cr image-list

    {: pre}

Deleting images from your private repository in the {{site.data.keyword.cloud_notm}} console

{: #registry_images_remove_gui}

You can delete unwanted images and all their tags from your private {{site.data.keyword.cloud_notm}} image repository by using the {{site.data.keyword.cloud_notm}} console.

Deleting an image that is being used by an existing deployment might cause scale-up, reschedule, or both, to fail. {: attention}

If you want to restore a deleted image, you can list the contents of the trash by running the ibmcloud cr trash-list command and restore a selected image by running the ibmcloud cr image-restore command. {: tip}

To delete an image by using the {{site.data.keyword.cloud_notm}} console, complete the following steps:

  1. Log in to the {{site.data.keyword.cloud_notm}} console https://cloud.ibm.com/login{: external} with your IBMid.
  2. If you have multiple {{site.data.keyword.cloud_notm}} accounts, from the account menu, select the account and region that you want to use.
  3. Click the Navigation menu icon, then click Container Registry.
  4. Click Images. A list of your images is displayed.
  5. In the row that contains the image that you want to delete, select the checkbox.
  6. Click Delete Image.

Listing images in the trash

{: #registry_images_list_trash} {: help} {: support}

You can list deleted images that are in the trash and see when they expire.

To find out which images are in the trash, you can use the ibmcloud cr trash-list command. Images are stored in the trash for 30 days.

To list the images in the trash, complete the following steps:

  1. Log in to {{site.data.keyword.cloud_notm}} by running the ibmcloud login command.

  2. List the images in the trash by using one of the following options:

    • List all the images in the trash by running the following command:
    ibmcloud cr trash-list

    {: pre}

    • List only the images in the trash for the namespace that you're interested in by running the following command, where NAMESPACE is your namespace:
    ibmcloud cr trash-list --restrict NAMESPACE

    {: pre}

Restoring images

{: #registry_images_restore}

You can restore images from the trash. Deleted images are stored in the trash for 30 days.

You can restore an image from the trash by running the ibmcloud cr image-restore command. To find out which images are in the trash, run the ibmcloud cr trash-list command.

You can restore images by running the ibmcloud cr image-restore command. You can use the following options:

  • REPO@DIGEST this option restores the digest and all its tags in the repository that aren't already in the live repository. For more information, see Restoring images by digest.
  • REPO:TAG this option restores the tag. For more information, see Restoring images by tag.

Restoring images by digest

{: #registry_images_restore_digest} {: help} {: support}

When you restore an image by digest, the digest is copied from the trash into your live repository, and all the tags for the digest in the repository are restored. The digest continues to show in the trash because a copy is restored.

To restore an image from the trash by using the digest, complete the following steps:

  1. Log in to {{site.data.keyword.cloud_notm}} by running the ibmcloud login command.

  2. List the images in the trash by running the following command:

    ibmcloud cr trash-list

    {: pre}

    A table is displayed that shows the items in the trash. The table shows the digest, the days until expiry, and the tags for that digest.

  3. Note the digest for the image that you want to restore.

  4. Run the following command to restore the image to your repository. Where DNS is the domain name, NAMESPACE is the namespace, REPO is the repository, and DIGEST is the digest of the image that you want to restore.

    ibmcloud cr image-restore DNS/NAMESPACE/REPO@DIGEST

    {: pre}

    If some tags aren't restored, see Why aren't all the tags restored when I restore by digest? for assistance. {: tip}

    In your live repository, you can pull the image by digest. If you run the ibmcloud cr image-digests command, the image shows in the output. {: tip}

Restoring images by tag

{: #registry_images_restore_tag} {: help} {: support}

When you restore an image by tag, only that specific tag is moved out of the trash into your live repository.

To restore an image from the trash by using a tag, complete the following steps:

  1. Log in to {{site.data.keyword.cloud_notm}} by running the ibmcloud login command.

  2. List the images in the trash by running the following command:

    ibmcloud cr trash-list

    {: pre}

    A table is displayed that shows the items in the trash. The table shows the digest, the days until expiry, and the tags for that digest.

  3. For the image that you want to restore, make a note of the digest up to, but not including, the at sign (@). This part of the digest is DNS/NAMESPACE/REPO, where DNS is the domain name, NAMESPACE is the namespace, and REPO is the repository.

  4. For the image that you want to restore, make a note of the tag TAG.

  5. Run the following command to restore the image to your repository, where DNS/NAMESPACE/REPO is the name of the image that you want to restore and TAG is the tag.

    ibmcloud cr image-restore DNS/NAMESPACE/REPO:TAG

    {: pre}

    In your live repository, you can pull the image by tag.

    If you get an error when you're restoring an image that says that the tagged image exists, see Why do I get an error when I'm restoring an image? for assistance. {: tip}

    If you run the ibmcloud cr trash-list command, the digest and any other tags show in the output, but the tag is no longer displayed. {: tip}

Deleting a private repository and any associated images

{: #registry_repo_remove} {: help} {: support}

You can delete private repositories that are no longer required, and any associated images, by using the {{site.data.keyword.cloud_notm}} console.

When you delete a repository, all images in that repository are deleted. This action can't be undone. {: attention}

Before you begin, you must back up any images that you want to keep. {: important}

To delete a private repository by using the {{site.data.keyword.cloud_notm}} console, complete the following steps:

  1. Log in to the {{site.data.keyword.cloud_notm}} console https://cloud.ibm.com/login{: external} with your IBMid.

  2. If you have multiple {{site.data.keyword.cloud_notm}} accounts, from the account menu, select the account and region that you want to use.

  3. Click the Navigation menu icon, then click Container Registry.

  4. Click Repositories. A list of your private repositories is displayed.

  5. In the row that contains the private repository that you want to delete, select the checkbox.

    Ensure that the correct repository is selected because this action can't be undone. {: attention}

  6. Click Delete Repository.