FAQ for Container Registry

Frequently asked questions for IBM Cloud® Container Registry.

For frequently asked questions about Vulnerability Advisor, see FAQ for Vulnerability Advisor.

Where is the reference documentation for Container Registry?

The reference documentation for IBM Cloud Container Registry is available in the IBM Cloud documentation. For more information, see About Container Registry and Container Registry CLI.

How do I set up the Container Registry CLI?

To set up the IBM Cloud Container Registry command-line interface (CLI), use the following steps:

Ensure that the IBM Cloud CLI is installed. To verify that it is installed, run the ibmcloud help command.
Install the container-registry CLI plug-in by running the command ibmcloud plugin install container-registry.
Log in to IBM Cloud with the ibmcloud login command.
Verify the installation by checking the current version of the container-registry CLI plug-in with the command ibmcloud plugin list.

Now you can use the IBM Cloud Container Registry CLI to manage your registry and its resources for your IBM Cloud account.

For more information, see Setting up the Container Registry CLI and namespace and Getting started with Container Registry.

Why isn't `ibmcloud cr` a known command?

If you receive a message that says that ibmcloud cr isn't a registered command, the container-registry CLI plug-in either isn't installed or it's not up to date. See Why do Container Registry (ibmcloud cr) commands fail with a message that they're not registered? for assistance.

If you have issues with an unregistered command, it is likely that you don't have the most recent version of the plug-in. For more information about how to update the Container Registry CLI, see Updating the container-registry CLI plug-in.

How do I configure my firewall to allow connections to Container Registry?

You can use a Layer 7 firewall with the domains that are listed in Accessing Container Registry through a firewall or use a virtual private network (VPN).

What is the name of my namespace?

To find out the names of your namespaces, run the ibmcloud cr namespace-list command.

You can also use the API to list your namespaces by using the GET /api/v1/namespaces method.

For more information about namespaces, see Registry namespace. To plan your namespaces, see Planning namespaces.

How many namespaces can you have?

You can have 100 registry namespaces in each region.

Can I rename a namespace?

You can't rename a namespaceA collection of repositories that store images in a registry. A namespace is associated with an IBM Cloud account, which can include multiple namespaces.. If you want to change the name of the namespace, you must create a namespace with the new name and transfer its data. To transfer its data, you can copy the contents of the existing namespace into the namespace that you created.

If you don't want to transfer data manually, you can create a script for this action by using the ibmcloud cr image-tag command. For example, you can use the following script, where OLD_NAMESPACE is the existing namespace and NEW_NAMESPACE is the namespace that you created:

IMAGES=$(icr images --restrict OLD_NAMESPACE --format "{{ .Repository }}:{{ .Tag }}")

for i in $IMAGES ; do
   new=$(echo $i | sed "s|/OLD_NAMESPACE/|/NEW_NAMESPACE/|1")
   ibmcloud cr image-tag $i $new
done

Why don't I have authorization to create a namespace?

The error message You are not authorized to access the specified resource. indicates that you lack the necessary user permissions for working with namespaces.

See Why aren't I authorized to access a specified resource in Container Registry? for assistance.

Why am I unable to create a namespace?

If you're having problems when you try to add a namespace in Container Registry, it could be one of the following causes:

Invalid characters are included in the namespace.
The namespace is already in use.
You're reusing a namespace that was deleted recently.
You don't have the correct permissions to create a namespace.

See Why can't I add a namespace in Container Registry? for assistance.

How do I obtain image pull credentials for Container Registry?

For long-lived credentials, you want an API key that is associated with a service ID or user ID that has IAM reader permission on the namespace that contains the image. A user API key is associated with a user and their access policies. A service ID API key has its own access policies. You can create service ID API keys and user API keys manually in the IBM Cloud console and in the CLI. For more information about API keys, see Understanding API keys.

For security reasons, the API key is only available to be copied or downloaded at the time of creation. If the API key is lost, you must create a new API key.

You can create user API keys and service ID API keys in the IBM Cloud console, the command-line interface (CLI), the API, and in Terraform. For more information about creating API keys, see Managing user API keys and Managing service ID API keys.

For more information about how to access Container Registry, see Accessing Container Registry.

How do I list image names?

To list all the images in your IBM Cloud account, you can run the ibmcloud cr images command, which displays all tagged images in your IBM Cloud account with a truncated digest. If you want to list all your images with the complete digest, including untagged images, run the ibmcloud cr image-digests command. The image name is in either the format repository@digest or repository:tag. The values for repository, digest, and tag are returned when you run the commands.

For more information, see ibmcloud cr image-list (ibmcloud cr images) and ibmcloud cr image-digests (ibmcloud cr digests).

How do you list public images?

To list public images, run the following ibmcloud commands to target the global registry and list the public images that are provided by IBM:

Set the region to global by running the ibmcloud cr region-set command and entering global as the region.

ibmcloud cr region-set global

List the public images by running the ibmcloud cr images command with the --include-ibm option.

ibmcloud cr images --include-ibm

Why are requests to Container Registry timing out while I'm using the IBM Cloud CLI?

The timeout issue when you are using the IBM Cloud CLI with Container Registry might be due to having many images in the account. To resolve this situation, you can use the ibmcloud cr image-list command with the --restrict option to narrow down the scope of the list and improve performance. Alternatively, if vulnerability reports are not needed, use the ibmcloud cr image-list command with the --no-va option. To manage the number of images, consider cleaning up your namespaces. For more information, see Cleaning up your namespaces in Container Registry.

If you're following the getting started instructions, the instructions assume that you're in your own account with permission to do everything. If you're a member of an account that is owned and administered by someone else, you might not have the correct permissions to configure and operate the registry service. Ask your administrator to add you to an existing access policy, or create an access policy that gives you the correct service access role for working with Container Registry. For more information, see Why can't I get started with Container Registry? for assistance.

If Container Registry commands fail with an error that states that they're not registered, install the container-registry CLI plug-in. Additionally, ensure that the ibmcloud CLI plug-in and the container-registry CLI plug-in are both up to date. If you want to use all the available commands and options, you must keep your CLIs current. To check the current version of your CLI plug-ins, run the ibmcloud plugin list command. See Why isn't ibmcloud cr a known command? for assistance.

How do I add multiple tags to a container image?

To add multiple tags to a container image you can use the ibmcloud cr image-tag command, but you need to run the command for each tag that you want to add. For example, if your image is named us.icr.io/birds/bluebird:1 and you want to add the tags latest and peck, you must run the following commands:

ibmcloud cr image-tag us.icr.io/birds/bluebird:1 us.icr.io/birds/bluebird:latest

ibmcloud cr image-tag us.icr.io/birds/bluebird:1 us.icr.io/birds/bluebird:peck

After you run these commands, the image has three tags 1, latest, and peck.

What tools can I use to build and push images?

You can use Docker and non-Docker tools to build and push images to the registry. You can use non-Docker tools that support OCI container imageA container image that is compliant with the OCI Image Format Specification format and protocol. To log in by using other clients, see Accessing your namespaces interactively.

How do I log in to Container Registry with Podman?

To log in to IBM Cloud Container Registry by using Podman, you can use the following command podman login DOMAIN_NAME -u iamapikey -p PASSWORD. Replace DOMAIN_NAME with your domain name, for example icr.io, and replace PASSWORD with your IAM API key.

If you prefer not to use an API key, you can use the following command to log in with a user refresh token ibmcloud cr login --client podman.

For more information, see Using Podman to authenticate with the registry, Using Podman to authenticate with the registry by using trusted profiles, and ibmcloud cr login.

Do images in the trash count toward my quota?

Images that are in the trash don't count toward your quota.

How do I find the image digest?

You can find the long format of the image digest by running one of the following commands. The digest is displayed in the Digest column of the CLI.

When you're using the digest to identify an image, always use the long format.

You can run either of the following commands to get the long form of the image digest:

Run the ibmcloud cr image-digests command:
```
ibmcloud cr image-digests
```
Run the ibmcloud cr image-list command with the --no-trunc option:
```
ibmcloud cr image-list --no-trunc
```
If you run the ibmcloud cr image-list command without the --no-trunc option, you see the truncated format of the digest.

How do I use digests to work with images?

The digest identifies an image by using the sha256 hash of the image manifest.

To find the digests for your images, run the ibmcloud cr image-digests command. You can refer to an image by using a combination of 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.

Why can't I push the image into Container Registry?

You might have issues when you are pulling or pushing images to Container Registry because of various reasons such as exceeding the image storage or pull traffic quota, or invalid credentials. To resolve this issue, log in to IBM Cloud and the IBM Cloud Container Registry CLI, review quota limits and usage, and consider upgrading to a standard plan if you are on a free plan.

See Why can't I push or pull a Docker image when I use Container Registry? for assistance.

How do I list images that are more than a year old?

Linux macOS On Linux® and macOS, if you want to list all images, both tagged and untagged that were created more than a year ago, you can run the following command:

year=$(($(date +%s) - 31556952))
ibmcloud cr digests --format '{{ if (lt .Created '$year')}}{{.Repository}}:{{.Digest}}{{end}}'

How do you use access control?

You can create IBM Cloud Identity and Access Management (IAM) policies to control access to your namespaces in IBM Cloud Container Registry. For more information, see Granting access to IBM Cloud Container Registry resources tutorial and Managing IAM access for Container Registry.

How can I share access to an image?

To access an image, a user must be a member of the IBM Cloud account that owns the images. After the user is added to the account, appropriate IAM policies must be created to assign access.

For more information, see Defining IAM access policies.

Can I share a Container Registry namespace across IBM Cloud accounts?

You can't share a Container Registry (icr.io) namespace across IBM Cloud accounts. A namespace is owned by a single IBM Cloud account and cannot be shared with multiple accounts.

Can I push images on a different account to the one that is running the build pipeline?

You can push images to IBM Cloud Container Registry on a different IBM Cloud account than the one that is running the build pipeline by using the following steps.

Create an API key in the target IBM Cloud account with the necessary access policies to allow pushing images to the required namespace.
Store the API key and the target namespace in your build pipeline configuration.
Modify your build pipeline script to use the API key and target namespace when you are pushing images to Container Registry. This action causes your build pipeline to authenticate and to push images to the specified namespace in the target IBM Cloud account.

For more information, see Pushing images by using an API key and Accessing Container Registry.

Do I have any untagged images?

To find out whether you have any untagged images, list your images by running the ibmcloud cr image-digests command. Untagged images have a hyphen (-) in the Tags column.

Do I need untagged images?

If you have active containers that are running untagged images, you must retain the untagged images. If you delete untagged images that are in use, you can cause problems with scaling or automated restarts. Deleting untagged images might cause a problem in the following circumstances:

The image was deployed by using the digest as the reference. For example, IBM Cloud Code Engine does resolve and use an image digest when it is serving applications, see Deploying app workloads from images in a public registry.
The image reference was mutated by a webhook service, such as Portieris.

What are eligible images?

If you're cleaning up images by using retention policies, only eligible images are cleaned up. Images that are always retained are Cloud Native Buildpacks and Google distroless images with the build date set to a specific constant rather than the real build time or with no build timestamp at all, and manifest lists. Images that are always retained are not eligible images.

The images that are not eligible are still displayed, but they do not count toward the total number of images that is set in the retention policy and are not removed.

Images created before 2013-01-19T00:13:39Z are excluded from retention policy evaluation.

For more information, see Planning retention.

What regions are available?

To find out more about the regions that are available for IBM Cloud Container Registry, see Regions.

How do I change the region or registry?

To change the region and the registry, you must log in to IBM Cloud and use the ibmcloud cr region-set REGION command, which sets the container-registry CLI plug-in to target the specified regional registry.

For example, to change the registry to uk.icr.io, which is in the region eu-gb, complete the following steps.

ibmcloud login

Run the ibmcloud cr region-set command to set the region and registry by entering eu-gb as the region:

ibmcloud cr region-set eu-gb

You can also use the name of the registry (for example, uk.icr.io) or the former name of the region (for example, uk-south instead of eu-gb).

You get the following response:

The region is set to 'uk-south', the registry is 'uk.icr.io'.

To find out more about the regions that are available for IBM Cloud Container Registry, see Regions.

How do I get the `docker pull` command to return the most recent version?

To find the most recent image, run the ibmcloud cr image-list command rather than the docker pull command. To make it easier to find the most recent image, define a different sequential tag for your images every time, and do not rely on the latest tag.

See Why can't I pull the newest image by using the latest tag in Container Registry? for assistance.

Why do my pods fail with an `ImagePullBackOff` error?

The error is likely to be caused by one of the following situations:

Your cluster uses an API key that is stored in an image pull secret to authorize the cluster to pull images from IBM Cloud Container Registry.
The image with the specific tag does not exist in the repository.

To fix the error, check for the following potential causes.

Check that you're using the correct name and tag for the image.
Check that your pull traffic and storage quotas are large enough.
Check whether you have an image pull secret in your namespace.

For more information, see Why do images fail to pull from registry with ImagePullBackOff or authorization errors? for assistance.

Why am I getting an exceeded quota error?

You exceeded the image storage or pull traffic quota for your account for the current month. To resolve this issue, you can either review your quota limits and increase them as necessary, or if you're on the Lite plan, upgrade to the standard plan.

For more information, see Why am I getting errors about my quota in Container Registry? and Staying within quota limits.

FAQ for Container Registry

Where is the reference documentation for Container Registry?

How do I set up the Container Registry CLI?

Why isn't ibmcloud cr a known command?

How do I configure my firewall to allow connections to Container Registry?

What is the name of my namespace?

How many namespaces can you have?

Can I rename a namespace?

Why don't I have authorization to create a namespace?

Why am I unable to create a namespace?

How do I obtain image pull credentials for Container Registry?

How do I list image names?

How do you list public images?

Why are requests to Container Registry timing out while I'm using the IBM Cloud CLI?

How do I add multiple tags to a container image?

What tools can I use to build and push images?

How do I log in to Container Registry with Podman?

Do images in the trash count toward my quota?

How do I find the image digest?

How do I use digests to work with images?

Why can't I push the image into Container Registry?

How do I list images that are more than a year old?

How do you use access control?

How can I share access to an image?

Can I share a Container Registry namespace across IBM Cloud accounts?

Can I push images on a different account to the one that is running the build pipeline?

Do I have any untagged images?

Do I need untagged images?

What are eligible images?

What regions are available?

How do I change the region or registry?

How do I get the docker pull command to return the most recent version?

Why do my pods fail with an ImagePullBackOff error?

Why am I getting an exceeded quota error?

Why isn't `ibmcloud cr` a known command?

How do I get the `docker pull` command to return the most recent version?

Why do my pods fail with an `ImagePullBackOff` error?