This collection of container images is hosted at the
IBM Cloud Container Registry
(icr.io). An IBM Cloud ID is required to pull images from the registry. Any type of
IBM Cloud ID will work, including "lite" IDs with no associated cost. If you don't
have an ID already, please visit cloud.ibm.com and
create one.
You are welcome to browse the set of available images here without an IBM Cloud ID,
but the ID is required at docker/podman login time.
User credentials
All container image registries require users log in, and as mentioned above, ICR requires
an IBM Cloud ID. IBM Cloud makes extensive use of keys and passphrases for user
authentication. You can manage your identity keys from the IBM Cloud web site using the
Manage pulldown to navigate to the Access (IAM)
interface. From there, choose API keys, and then Create an IBM Cloud API key. You should
see a window for naming and describing your access key.
Once you enter a name and description, the IBM Cloud will generate the key, and give you
5 minutes to download the file (named apikey.json), or cut/paste the text of the key to a
file of your choice. Save this file to a safe place and give it a useful name. Should
you ever lose it, use the API keys interface to delete it and define a new one to remain
secure. This key is alone is what identifies you to ICR.
The contents of the key file looks like this:
{
"name": "Sample IAMAPIKEY",
"description": "A sample IBM Cloud API key",
"createdAt": "2021-02-08T20:01+0000",
"apikey": "B08t7_qWo60P123456789IXybgvgGqAty8ULka8ZnMAT"
}
The apikey text highlighted in blue above is the key string
needed for authenticating to ICR.
The IBMCLOUD Command Line Interfaces
The IBM Cloud has a command line interface (CLI) that provides many of the same functions
that can be found on the web. If you are familiar with the ibmcloud CLI, feel free to use
it. It is not required to use the ICR registry from a container CLI like Docker or Podman,
and we will not be using it in any of our best practices.
Pulling an Image From the ibmz Namespace at ICR
Once you have your IAMAPIKEY credentials created, you're ready to log in to ICR and pull
images. The process is effectively the same as for any other registry. Simply log into the
ICR global region at icr.io, with a user name of iamapikey. When
ICR sees this userid, it will expect to receive an apikey for your IBM cloud userid at the
password prompt. If you have multiple keys generated for your userid, any of them should work.
After logging in to ICR, simply pull the image using the fully qualified path to the
image you want. We recommend using the pull string provided in the details page for the
specific image of interest. Note that while it is possible to pull an image by name and
version (tag), we recommend using the full sha256 hash for the image digest to be sure you
get exactly the image you request.
Here is an example login and pull command:
>
docker login -u iamapikey icr.io
Password: <-Paste the text of your apikey here
Login Succeeded
>
docker pull icr.io/ibmz/kafka@sha256:4419e017475e4082f8a03574f2b74195a689650c3f1ed8962874783e3dd4bf4a
sha256:4419e017475e4082f8a03574f2b74195a689650c3f1ed8962874783e3dd4bf4a: Pulling from ibmz/kafka
d777bd6e5a8d: Already exists
c2fc12e4949d: Already exists
a15ab9f4a460: Already exists
cd76eb949805: Pull complete
Digest: sha256:4419e017475e4082f8a03574f2b74195a689650c3f1ed8962874783e3dd4bf4a
Status: Downloaded newer image for icr.io/ibmz/kafka@sha256:4419e017475e4082f8a03574f2b74195a689650c3f1ed8962874783e3dd4bf4a
icr.io/ibmz/kafka@sha256:4419e017475e4082f8a03574f2b74195a689650c3f1ed8962874783e3dd4bf4a
Once you have the image pulled to your environment, you are free to use it as documented.
