Adding images to your namespace in Container Registry

Pulling images from another registry

You can pull (download) an image from any private or public registryA storage and distribution service that contains public or private images that are used to create containers. source, and then tag it for later use in IBM Cloud Container Registry.

Before you begin, complete the following tasks.

• Install the CLI to work with images in your namespace.

• Set up your own namespace in IBM Cloud Container Registry.

• Make sure that you can run Docker commands without root permissions. If your Docker client is set up to require root permissions, you must run ibmcloud login, ibmcloud cr login, docker pull, and docker push commands with sudo.

  If you change your permissions to run Docker commands without root privileges, you must run the ibmcloud login command again.

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.

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 Container Registry and your pods fail with an ImagePullBackOff status, see Why do images fail to pull from registry with ImagePullBackOff or authorization errors? for assistance.

Pushing Docker images to your namespace

You can push (upload) an image to your namespace in IBM Cloud Container Registry to store and share your image with other users.

Before you begin, complete the following tasks.

• Install the CLI to work with images in your namespace.

• Set up your own namespace in IBM Cloud Container Registry.

• Pull or build an image on your local computer and tag the image with your namespace information.

• Make sure that you can run Docker commands without root permissions. If your Docker client is set up to require root permissions, you must run ibmcloud login, ibmcloud cr login, docker pull, and docker push commands with sudo.

  If you change your permissions to run Docker commands without root privileges, you must run the ibmcloud login command again.

IBM Cloud Container Registry supports other clients as well as Docker. To log in by using other clients, see Accessing your namespaces interactively.

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
   

   You must log in if you pull an image from your private IBM Cloud Container Registry.

   If you have a problem when you try to log in, see Why can't I log in to Container Registry? for assistance.

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.

After you push your image to IBM Cloud Container Registry, you can do one of the following tasks.

• Manage security with Vulnerability Advisor to find information about potential security issues and vulnerabilities.
• Create a cluster and use this image to deploy a container to the cluster in IBM Cloud Kubernetes Service.

Copying images between registries

You can pull an image from a registry in one region and push it to a registry in another region so that you can share the image with users in both regions.

Before you begin, complete the following tasks.

• Install the CLI to work with images in your namespace.

• Set up your own namespace in IBM Cloud Container Registry.

• Make sure that you can run Docker commands without root permissions. If your Docker client is set up to require root permissions, you must run ibmcloud login, ibmcloud cr login, docker pull, and docker push commands with sudo.

  If you change your permissions to run Docker commands without root privileges, you must run the ibmcloud login command again.

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.

• Manage image security with Vulnerability Advisor to find information about potential security issues and vulnerabilities.
• Create a cluster and use this image to deploy a container to the cluster in IBM Cloud Kubernetes Service.

Creating images that refer to a source image

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

In the region that you're logged in to, create an image in IBM Cloud Container Registry 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.

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 IBM Cloud Container Registry 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
   

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.

   ibmcloud cr image-tag [SOURCE_IMAGE] [TARGET_IMAGE]
   

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
   

Building Docker images to use them with your namespace

You can build a Docker image directly in IBM Cloud or create your own Docker image on your local computer and upload (push) it to your namespace in IBM Cloud Container Registry.

Before you begin, complete the following tasks.

• Install the CLI to work with images in your namespace.

• Set up your own namespace in IBM Cloud Container Registry.

• Make sure that you can run Docker commands without root permissions. If your Docker client is set up to require root permissions, you must run ibmcloud login, ibmcloud cr login, docker pull, and docker push commands with sudo.

  If you change your permissions to run Docker commands without root privileges, you must run the ibmcloud login command again.

A Docker image is the basis for every container that you create. An image is created from a Dockerfile, which is a file that contains instructions to build the image. A Dockerfile might reference build artifacts in its instructions that are stored separately, such as an app, the configuration of the app, and its dependencies.

If you want to take advantage of IBM Cloud compute resources and internet connection or Docker is not installed on your workstation, build your image directly in IBM Cloud. If you need to access resources in your build that are on servers that are behind your firewall, build your image locally.

To build your own Docker image, complete the following steps:

1. Create a local directory where you want to store the build context. The build context contains your Dockerfile and related build artifacts, such as the app code. Navigate to this directory in a command-line window.

2. Create a Dockerfile.

   1. Create a Dockerfile in your local directory.

      touch Dockerfile
      

   2. Use a text editor to open the Dockerfile. At a minimum, you must add the base image to build your image from. Replace <source_image> and <tag> with the image repository and tag that you want to use. If you're using an image from another private registry, define the full path to the image in IBM Cloud Container Registry.

      FROM <source_image>:<tag>
      

      For example, to create a Dockerfile that is based on the public IBM WebSphere Application Server Liberty (ibm/liberty) image, use the following command.

      FROM icr.io/ibm/liberty:latest
      LABEL description="This is my test Dockerfile"
      EXPOSE 9080
      

      This example adds a label to the image metadata and exposes port 9080. For more Dockerfile instructions that you can use, see the Dockerfile reference.

3. Decide on a name for your image. The image name must be in the following format, where <my_namespace> is your namespace information, <repo_name> is the name of your repository, and <tag> is the version that you want to use for your image:

   <region>.icr.io/<my_namespace>/<repo_name>:<tag>
   

   To find your namespace, run the ibmcloud cr namespace-list command.

4. Take note of the path to the directory that contains your Dockerfile. If you run the commands in the following steps while your working directory is set to where your build context is stored, you can replace <directory> with a period (.).

5. Build and test your image locally before you push it to IBM Cloud.

   1. Build the image from your Dockerfile on your local computer and tag it with your image name, where <image_name> is the name of your image and <directory> is the path to the directory.

      docker build -t <image_name> <directory>
      

   2. Optional: Test your image on your local computer before you push it to your namespace.

      docker run <image_name>
      

      Replace <image_name> with the name of your image.

   3. After you create your image and tag it for your namespace, you can push your image to your namespace in IBM Cloud Container Registry.

To use Vulnerability Advisor to check the security of your image, see Managing image security with Vulnerability Advisor.

Pushing images by using an API key

Create a service ID that uses an API keyA unique code that is passed to an API to identify the calling application or user. An API key is used to track and control how the API is being used, for example, to prevent malicious use or abuse of the API. to push images to IBM Cloud Container Registry.

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 Container Registry.
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 IBM Cloud Container Registry.
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

You can remove a tag, or tags, from an image in your private IBM Cloud repository, and leave the underlying image and any other tags 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 IBM Cloud repository.

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

1. Log in to IBM Cloud 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 IBM Cloud 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.

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
   

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

Deleting images from your private repository

You can delete unwanted images from your private IBM Cloud repository by using either the IBM Cloud 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.

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.

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 leave the underlying image and any other tags in place, see Removing tags from images in your private repository command.

Listing images in the trash

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 IBM Cloud by running the ibmcloud login command.

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

   ibmcloud cr trash-list
   

3. 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>
   

Restoring images

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> restores the digest and all its tags in the repository that aren't already in the live repository, see Restoring images by digest.
• <repo>:<tag> restores the tag, see Restoring images by tag.

Deleting a private repository and any associated images

You can delete private repositories that are no longer required, and any associated images, by using the IBM Cloud console.

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

Before you begin, you must back up any images that you want to keep.

To delete a private repository by using the IBM Cloud console, complete the following steps:

1. Log in to the IBM Cloud console https://cloud.ibm.com/login with your IBMid.

2. If you have multiple IBM Cloud 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.

6. Click Delete Repository.