Red Hat Container Registry Authentication

Red Hat distributes container images from two locations: registry.access.redhat.com (no authentication needed) and registry.redhat.io (authentication required). Container images from third party vendors are available from registry.connect.redhat.com. This article describes how you can:

• Use registry.access.redhat.com, with no authentication required.
• Learn about how authentication works with registry.redhat.io.
• Create a registry Service Account for use on shared systems.

Red Hat Registries

Red Hat distributes container images through three different container registries:

Although both registry.access.redhat.com and registry.redhat.io hold essentially the same container images, some images require an active Red Hat account and are only available from registry.redhat.io.

Getting a Red Hat Login

To use the registry.redhat.io registry, you have to have a Red Hat login. If you are a customer with entitlements to Red Hat products, you already have an account. This is the same type of account that you use to log into the Red Hat Customer Portal (access.redhat.com) and manage your Red Hat subscriptions.

If you do not have a Red Hat account, you can get a free Red Hat account by signing up for one of the following:

• Red Hat Developer Program: Signing up for a free developer account gives you access to developer tools and programs.
• 30-day Trial Subscription: Signing for a 30-day trial subscription gives you access to selected Red Hat software products.

Once you agree to the terms and get a Red Hat account, you can use that account to log into the new Red Hat registry and get images. Keep in mind that you would still need entitlements from Red Hat to add or update RPM packages while building or updating an image using yum.

Using Authentication

To retrieve content from an authenticated registry, you will need to log into the registry using either your Customer Portal, Red Hat Developer, or Registry Service Account credentials.

Note: for pulling images from a Red Hat OpenShift Container Platform cluster, it's needed to check if the current pull secret is valid. Refer to Manual podman pull fails within OCP 4 nodes to check that the credentials in the pull secret are valid, and if needed, change the global pull secret.

To login to the registry.redhat.io registry, you can use either the podman login, skopeo login, and buildah login commands. You can replace any docker command examples used throughout this article with the podman command. From OpenShift, Satellite, or other shared environments, you must use Service Accounts for authentication.

To use Podman to authenticate to registry.redhat.io:

# podman login registry.redhat.io
Username: myrhusername
Password: ***********

To use Skopeo to authenticate to registry.redhat.io:

# skopeo login registry.redhat.io
Username: myrhusername
Password:  ***********

To use the docker login command to authenticate to registry.redhat.io:

# docker login https://registry.redhat.io
Username: myrhusername
Password:  ***********

You can pull the image from the registry.redhat.io registry as follows:

Using the Skopeo command:

skopeo copy docker://registry.redhat.io/rhel8/pcp containers-storage:registry.redhat.io/rhel8/pcp 

Using the Podman command:

# podman pull registry.redhat.io/rhel8/rsyslog
Username: myrhusername
Password:  xxxxxxxxxxx

When you log into the registry, your credentials are stored in your ${XDG_RUNTIME_DIR}/containers/auth.json file. Those credentials are used automatically the next time you pull from that registry. Here is an example of that file:

   {
           "auths": {
                   "https://registry.redhat.io": {
                           "auth": "c2xmams6c2RmbGtq"
                   }
           }
   }

For other ways to save these credentials, see the config.json description on the docker login page.

For OpenShift 3.x nodes you will have an additional step. After you log in, you will need to copy ~/.docker/config.json to /var/lib/origin/.docker/config.json and restart the node.

# cp ~/.docker/config.json /var/lib/origin/.docker/config.json; systemctl restart atomic-openshift-node

Registry Service Accounts for Shared Environments

To consume container images from registry.redhat.io in shared environments such as OpenShift, it is recommended for an administrator to use a Registry Service Account, also referred to as authentication tokens, in place of an individual's Customer Portal credentials.

Service Accounts are a mechanism provided to a Customer Portal organization, used exclusively for authenticating to and retrieving content from registry.redhat.io. The use of Service Accounts is encouraged to prevent the need to use Customer Portal credentials on shared systems, in contrast to Customer Portal accounts, Registry Service Accounts are resilient to some security controls applied to Customer Portal accounts, such as mandated password resets. Once created, Registry Service Accounts do not expire and are active until removed.

The management of Service Accounts is available via the Registry Service Account management application. You have the freedom to decide how many Service Accounts are created and how they are used on your systems, as a guideline, you may opt to use one Service Account per shared system (such as an OpenShift Container Platform cluster).

Managing Registry Service Accounts

Within the application for Service Account Management, there is a simple approach to split authorization for management of tokens. The ability to create, modify, or remove Service Accounts is defined by whether a Customer Portal login has the Organization Administrator role assigned.

Customer Portal Organization Administrators can:

• View all Registry Service Accounts created for an organization.
• Create Registry Service Accounts.
• Modify or remove any Registry Service Accounts.

Customer Portal Users (non-organization Admins) can:

• View all Registry Service Accounts for an organization.
• Create Registry Service Accounts.
• Only modify or remove Registry Service Accounts they have created.

Regardless of which user creates a Service Account, the account can be viewed by other Customer Portal users within the same organization. There is no functionality to conceal a Service Account and its associated credentials from being viewed by others within the organization.

Creating Registry Service Accounts

Navigate to the Registry Service Account Management Application, and log in if necessary.

1. From the Registry Service Accounts page, click New Service Account button.
2. Provide a name for the Service Account. It will be prepended with a fixed, random string.
   • Enter a description.
   • Click create.
3. Navigate back to your Service Accounts.
4. Click the Service Account you created.
   • Note the username, including the prepended string (i.e. XXXXXXX|username). This is the username which should be used to login to registry.redhat.io.
   • Note the password. This is the password which should be used to login to registry.redhat.io.

There are tabs available within the Token Information page which offer guidance on how to use the authentication token for various scenarios. For example, the Docker Login tab demonstrates how the token can be used with the docker CLI.

Modifying Authentication Tokens

As with Service Account creation, accounts can be modified or deleted as part of the functionality provided by the management application. These can each be invoked from the Registry Service Accounts page using the pop-up menu to the right of each authentication token. The description for each function is described as follows:

• Regenerate token: Allows an authorized user to reset the password associated with the Service Account, the username for the Service Account does not change.
• Update Description: Allows an authorized user to update the description for the Service Account.
• Delete Account: Allows an authorized user to remove the Service Account.

Warning: The regeneration or removal of Service Accounts will impact any systems which may be using the token to authenticate and retrieve content from registry.redhat.io.

Allowing Pods to Reference Images from Other Secured Registries

The .dockercfg file (or $HOME/.docker/config.json for newer Docker clients) is a Docker credentials file that stores your information if you have previously logged into a secured or insecure registry.

To pull a secured container image that is not from OpenShift Container Platform’s internal registry, you must create a pull secret from your Docker credentials and add it to your service account.

If you already have a .dockercfg file for the secured registry, you can create a secret from that file by running:

$ oc create secret generic <pull_secret_name> \
    --from-file=.dockercfg=<path/to/.dockercfg> \
    --type=kubernetes.io/dockercfg

Or if you have a $HOME/.docker/config.json file:

$ oc create secret generic <pull_secret_name> \
    --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
    --type=kubernetes.io/dockerconfigjson

If you do not already have a Docker credentials file for the secured registry, you can create a secret by running:

$ oc create secret docker-registry <pull_secret_name> \
    --docker-server=<registry_server> \
    --docker-username=<user_name> \
    --docker-password=<password> \
    --docker-email=<email>

To use a secret for pulling images for pods, you must add the secret to your service account. The name of the service account in this example should match the name of the service account the pod uses; default is the default service account:

$ oc secrets link default <pull_secret_name> --for=pull

To use a secret for pushing and pulling build images, the secret must be mountable inside of a pod. You can do this by running:

$ oc secrets link builder <pull_secret_name>

For builds, you must also reference the secret as the pull secret from within your build configuration.

Learning More About Red Hat Registry

Here are a few other resources to help you get started with registry.redhat.io:

• Troubleshooting: If you are in a security-hardened environment, you may need to make internal changes to whitelist registry.redhat.io on proxies. You can follow the Troubleshooting Authentication Issues with registry.redhat.io article to verify connectivity with registry.redhat.io.
• Where to get further help: If you need further help, open a support ticket for your product through the Red Hat Customer Portal.