Pulling images into OpenShift from the Red Hat registry

Updated 21 September 2020

How do you deploy Red Hat containers onto OpenShift? Containers for products like Fuse, AMQ and JBoss EAP?

Red Hat publishes a lot of images for products in its own Docker registry at registry.redhat.io. However, if you’ve worked with the Red Hat registry, you might have noticed that you need a username and password to be able to pull images from it. If you’re just learning OpenShift as a developer, it might not be immediately obvious how to provide that username and password.

And sometimes, it seems that OpenShift deploys stuff fine from the Red Hat registry without needing a password, but… sometimes it complains that you’re unauthorised! Why?

Confused? I hear you. This article is especially for you, my friend.

🔥 Are you running OpenShift 4.5? There’s a special surprise for you at the end of this article.

Getting knocked-back from the registry

Let’s start with a typical scene. A situation like this may have brought you here:

                W0906 17:28:48.315952   15850 dockerimagelookup.go:236]
container image registry lookup failed: registry.redhat.io/fuse7/fuse-java-openshift:1.6:
Get https://registry.redhat.io/v2/fuse7/fuse-java-openshift/manifests/1.6:
unauthorized: Please login to the Red Hat Registry using your Customer Portal credentials.
Further instructions can be found here: https://access.redhat.com/RegistryAuthentication
error: unable to locate any local docker images with name "registry.redhat.io/fuse7/fuse-java-openshift:1.6"

              

It seems that OpenShift doesn’t want to pull an image from the Red Hat registry (registry.redhat.io) because the registry is private, and OpenShift doesn’t know how to authenticate to it.

Seriously, what a drama. 🙄

Drama queen — Please just deploy Fuse already

To move forward, OpenShift needs credentials to authenticate to the registry.

Do I need to provide registry credentials myself, or not?

No, but yes. Here’s what you need to know.

An OpenShift cluster which been installed correctly has credentials for the Red Hat registry installed onto each Node. This allows you to pull images from the Red Hat registry on any Node. This means that you can do things like create a DeploymentConfig, or use oc run to deploy a Docker image directly.

As an example, this is exactly what the template for AMQ Broker does. It deploys the image registry.redhat.io/amq7/amq-broker:7.7). I’ve snipped the relevant parts of the YAML here:

                - apiVersion: v1
  kind: DeploymentConfig
  spec:
    template:
      spec:
        containers:
          image: ${IMAGE}
...
parameters:
- description: Broker Image
  displayName: Image
  name: IMAGE
  required: true
  value: registry.redhat.io/amq7/amq-broker:7.7

              

But image streams and builds don’t work the same way. If you’re deploying from an image stream, or you’re building an image using a private base image (like the Red Hat Fuse or EAP images), the process is a little different. Image streams and builds pull images in a different way. They can’t use the registry credentials that are already on each Node, so they need to have their own credentials provided separately.

Image streams and builds need to have registry credentials provided via a Secret. This Secret must be linked to the Service Account which will pull the images to run or build.

What about image streams in the OpenShift project? They seem to work!

Image streams in the openshift Project are, errrrr, special. They will work magically, because there’s usually a Secret in there on OpenShift 4.x which contains credentials (or see the 3.11 equivalent) to authenticate to the Red Hat Container Registry at registry.redhat.io. Party time. Job done.

But, as a developer, you almost certainly won’t have permissions to modify stuff in the openshift Project, like creating new image streams. This Project is fairly important and typically only administrators can do stuff inside it. So you’ll need to either have a friendly administrator, or work inside your own project.

Creating a secret to authenticate to the Red Hat registry

So let’s create a secret which allows image streams and builds to pull images from the Red Hat registry. These steps will create a secret to allow OpenShift to pull images from the protected Red Hat registry registry.redhat.io, as required for image streams or builds.

Registry credentials usually consist of a username and a password. This can either be your Red Hat username and password, or a specially generated username and token, which is the preferred way. We’ll do this in the steps below:

Grab your Red Hat login details, go to https://access.redhat.com/terms-based-registry and create a new Registry Service Account.

(If you’re not a Red Hat customer, and you’re just learning OpenShift, you can use your free Red Hat Developer account. This allows you to authenticate to the Red Hat Container Registry. Join Red Hat Developer.)

Download the JSON file given on the page, or copy the credentials and create the new secret yourself:

                    oc create secret docker-registry redhat-registry-secret \
  --docker-username="12345678|yourserviceaccountname" \
  --docker-password=xxxxxxxx \
  --docker-server=registry.redhat.io

                  

To make this secret available for builds (e.g. S2I builds, Fuse builds, oc new-build, etc.), link the Secret to the builder Service Account:
```
oc secrets link builder redhat-registry-secret
```
To make the secret available for deployments, link the Secret to the default Service Account, and add for=pull:
```
oc secrets link default redhat-registry-secret --for=pull
```

Recap: setting up authentication to the Red Hat registry

If you just want to deploy Docker images from the Red Hat registry (without using image streams), you shouldn’t need to do anything.

If you want to create image streams or builds which use images from the Red Hat registry, you need to either:

Get your cluster administrator to create an image stream in the openshift project for the Red Hat registry image that you want to use. For example, your administrator can create an image stream for the Red Hat Fuse image using oc import-image:
```
oc import-image fuse-java-openshift:1.7 \
    --from=registry.redhat.io/fuse7/fuse-java-openshift:1.7 \
    -n openshift --confirm
```
✅ This is the ideal option, because you don’t have to worry about providing any credentials yourself. Yay.
OR, if “administrator-says-no”, and you can only work with image streams in your own project, create a Secret containing your credentials for the Red Hat registry, and link it to a Service Account.

Now go and enjoy all those sweet, sweet container images.

Epilogue: for OpenShift 4.5+ clusters

In Steve Jobs style, here’s “one more thing”. If you’re running OpenShift 4.5, the good news is you don’t need to worry about any of this anymore. A new enhancement (see it here) has given OpenShift the ability to use the Node’s registry credentials during a build or image stream import.

This means that from OpenShift 4.5, you no longer need to create your own Secret if you want to create an image stream or run a build with images from registry.redhat.io.

So here’s me doing the same on an OCP 4.5 cluster:

                $ oc get clusterversion
NAME      VERSION   AVAILABLE   PROGRESSING   SINCE   STATUS
version   4.5.7     True        False         31h     Cluster version is 4.5.7

$ oc new-project toms-test
Now using project "toms-test" on server "https://api.sharedocp4upi45.lab.example.com:6443".
...

$ oc import-image amq-broker:7.7 --from=registry.redhat.io/amq7/amq-broker:7.7 --confirm
imagestream.image.openshift.io/amq-broker imported
...
7.7
  tagged from registry.redhat.io/amq7/amq-broker:7.7

  * registry.redhat.io/amq7/amq-broker@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
      1 second ago

              

Asciinema screen cast if you’re interested:

So all of that stuff further above applies to earlier releases of OCP 4.x, and 3.x, but you can forget it if you’re on 4.5 or greater. 💁 Thanks to Ricardo Maraschini for pointing this out.