IBM Cloud Docs
Accessing Container Registry

Accessing Container Registry

To access your IBM Cloud® Container Registry namespaces so that you can push and pull images, use IBM Cloud® Identity and Access Management (IAM).

All accounts require IAM access policies. To set up and manage IAM access policies, see Defining IAM access policies.

Access to IBM Cloud Container Registry is either automated, which typically uses API keys, or interactive, which typically uses bearer tokens.

If you have an IAM access policy, but you are getting Access denied errors, see Why am I getting Access denied errors? for assistance.

If you want to use your container images in Kubernetes deployments, see Using an image pull secret to access images in other IBM Cloud accounts or external private registries from nondefault Kubernetes namespaces.

Accessing your namespaces in automation

You can use service ID API keys to automate the pushing and pulling of container images to and from your namespaces.

API keysA 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. are linked to user IDs or service IDs in your account and you can use them across IBM Cloud®. You can use an API key in the CLI or as part of automation to authenticate as your user or service identity. 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 have several service IDs with different fine grained policies so that your automation is granted specific and limited capabilities.

When you create an IBM Cloud Kubernetes Service or Red Hat® OpenShift® on IBM Cloud® cluster, the cluster is created with an IBM Cloud IAM service ID that is given an IAM Reader service access policy to IBM Cloud Container Registry. The service ID credentials are authenticated in a nonexpiring service ID API key that is stored in image pull secrets in your cluster. The image pull secrets are added to the default Kubernetes namespace and to the list of secrets in the default service account for this Kubernetes namespace. If you require more service ID API keys or the service ID API key is missing, you can create a service ID API key manually.

You can use service ID API keys in the following places:

  • IBM Cloud Kubernetes Service or Red Hat OpenShift on IBM Cloud clusters. When you create IBM Cloud Kubernetes Service and Red Hat OpenShift on IBM Cloud clusters, one service ID is automatically created for each cluster. If you want more than one service ID, you can create them manually.
  • Kubernetes and Red Hat® OpenShift® clusters that aren't on IBM Cloud. You must create your own service ID, API key, and pull secret.
  • Docker CLI and other clients. You must create your own service ID and API key.

Creating a service ID API key manually

Create a service ID API key that you can use to log in to the registry.

To create a service ID API key, complete the following steps:

  1. Create a service ID, see ibmcloud iam service-id-create.

  2. Assign service policies to the service ID to control the level of access that is allowed when the service ID is used to authenticate with IBM Cloud Container Registry, see Managing access to resources.

  3. Create a service ID API key, see Managing service ID API keys and ibmcloud iam service-api-key-create.

Creating a user API key manually

Create a user API key that you can use to log in to the registry.

If you create a user API key, the user's access policies are used.

To create a user API key, see Managing user API keys and ibmcloud iam api-key-create.

Using client software to authenticate in automation

Use an API key to log in to the registry by using common clients.

Clients require an API key and a domain, replace <apikey> with your API key and <registry_domain> with the domain of the registry where your namespaces are set up.

Registry domains
Region <registry_domain>
global icr.io
ap-north jp.icr.io
ap-south au.icr.io
br-sao br.icr.io
ca-tor ca.icr.io
eu-central de.icr.io
eu-es es.icr.io
jp-osa jp2.icr.io
uk-south uk.icr.io
us-south us.icr.io

For more information about how to use IBM Cloud Container Registry in a Continuous Delivery pipeline, see Using a private image registry.

Examples of how to authenticate automatically with the registry are provided for the following clients:

Using Buildah to authenticate with the registry

You can use Buildah to authenticate with the registry so that you can push and pull images to and from the registry.

Use the API key and domain to log in to the registry by running the following Buildah command, replace <apikey> with the API key and <registry_domain> with the domain:

buildah login -u iamapikey -p <apikey> <registry_domain>

Using Docker to authenticate with the registry

You can use Docker to authenticate with the registry so that you can push and pull images to and from the registry.

Use the API key and domain to log in to the registry by running the following Docker command, replace <apikey> with the API key and <registry_domain> with the domain:

docker login -u iamapikey -p <apikey> <registry_domain>

Using Podman to authenticate with the registry

You can use Podman to authenticate with the registry so that you can push and pull images to and from the registry.

Use the API key and domain to log in to the registry by running the following Podman command, replace <apikey> with the API key and <registry_domain> with the domain:

podman login -u iamapikey -p <apikey> <registry_domain>

Using Skopeo to authenticate with the registry

You can use Skopeo to authenticate with the registry so that you can push and pull images to and from the registry.

For example, you can use the following Skopeo command to pull an image from Docker Hub and push it to your namespace. Replace <registry_domain> with the name of your domain, <namespace> with your namespace, and <apikey> with your API key:

skopeo --insecure-policy --override-os linux copy docker://busybox:latest docker://<registry_domain>/<namespace>/busybox:latest --dest-creds iamapikey:<apikey>

Accessing your namespaces interactively

You can use bearer tokens and refresh tokens to push and pull images to and from your namespaces interactively.

Examples of how to access your namespaces interactively are provided for the following clients:

Using Buildah to access your namespace

Log in to the registry by using the Buildah CLI.

You can use the Buildah CLI to log in to the registry by using a bearer token, replace <registry_domain> with the domain:

ibmcloud iam oauth-tokens | sed -ne '/IAM token/s/.* //p' | buildah login -u iambearer --password-stdin <registry_domain>

Using Docker to access your namespace

Log in to the registry by using the Docker CLI.

You can use the Docker CLI to log in to the registry by using a refresh token in the IBM Cloud CLI:

ibmcloud cr login --client docker

You can use the Docker CLI to log in to the registry by using a bearer token:

  1. Generate a bearer token by using ibmcloud iam oauth-tokens.

  2. Log in to the registry by using the docker login command. Replace <bearer_token> with your bearer token and <registry_domain> with the domain:

    docker login -u iambearer --password <bearer_token> <registry_domain>

Using Podman to access your namespace

Log in to the registry and pull an image by using the CLI, where <image_name> is the name of the image.

ibmcloud cr login --client podman

podman pull <image_name>

Using Skopeo to access your namespace

Log in to the registry by using the Skopeo CLI.

You can use the Skopeo CLI to log in to the registry by using a bearer token, replace <registry_domain> with the domain:

ibmcloud iam oauth-tokens | sed -ne '/IAM token/s/.* //p' | skopeo login -u iambearer --password-stdin <registry_domain>

Accessing your namespaces programmatically

Use your own code to access to your namespaces in IBM Cloud Container Registry.

Most users can use the ibmcloud cr login command to simplify docker login, but if you are implementing automation or you are using a different client, you might want to authenticate manually. You must present a username and password. In IBM Cloud Container Registry, the username indicates the type of secret that is presented in the password.

The following usernames are valid:

  • iambearer The password contains an IAM access token. This type of authentication is short lived, but can be derived from all types of IAM identity. For example, from ibmcloud iam oauth-tokens.
  • iamrefresh The password contains an IAM refresh token that is used internally by the registry to generate an IAM access token. This type of authentication is longer lived. This authentication type is used by the ibmcloud cr login command.
  • iamapikey The password is an IAM API key that is used internally by the registry to generate an IAM access token. This type of authentication is the preferred type for automation. You can use a user API key or a service ID API key. For more information, see Accessing your namespaces in automation.