Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
×

Accessing and Configuring the Red Hat Registry

Authentication Enabled Red Hat Registry

All container images available through the Red Hat Container Catalog are hosted on an image registry, registry.access.redhat.com. With OKD 3.11 Red Hat Container Catalog moved from registry.access.redhat.com to registry.redhat.io.

The new registry, registry.redhat.io, requires authentication for access to images and hosted content on OKD. Following the move to the new registry, the existing registry will be available for a period of time.

OKD pulls images from registry.redhat.io, so you must configure your cluster to use it.

The new registry uses standard OAuth mechanisms for authentication, with the following methods:

  • Authentication token. Tokens, which are generated by administrators, are service accounts that give systems the ability to authenticate against the container image registry. Service accounts are not affected by changes in user accounts, so the token authentication method is reliable and resilient. This is the only supported authentication option for production clusters.

  • Web username and password. This is the standard set of credentials you use to log in to resources such as access.redhat.com. While it is possible to use this authentication method with OKD, it is not supported for production deployments. Restrict this authentication method to stand-alone projects outside OKD.

You can use docker login with your credentials, either username and password or authentication token, to access content on the new registry.

All image streams point to the new registry. Because the new registry requires authentication for access, there is a new secret in the OpenShift namespace called imagestreamsecret.

You must place your credentials in two places:

  • OpenShift namespace. Your credentials must exist in the OpenShift namespace so that the image streams in the OpenShift namespace can import.

  • Your host. Your credentials must exist on your host because Kubernetes uses the credentials from your host when it goes to pull images.

To access the new registry:

  • Verify image import secret, imagestreamsecret, is in your OpenShift namespace. That secret has credentials that allow you to access the new registry.

  • Verify all of your cluster nodes have a /var/lib/origin/.docker/config.json, copied from master, that allows you to access the Red Hat registry.

Creating User accounts

If you are a Red Hat customer with entitlements to Red Hat products, you have an account with applicable user credentials. These are the username and password that you use to log in to the Red Hat Customer Portal.

If you do not have an account, you can acquire one for free by registering for one of the following options:

Creating Service Accounts and Authentication Tokens for the Red Hat Registry

You must create tokens if your organization manages shared accounts. Administrators can create, view, and delete all tokens associated with an organization.

Prerequisites

  • User credentials

Procedure

To create a token in order complete a docker login:

  1. Navigate to registry.redhat.io.

  2. Log in with your Red Hat Network (RHN) username and password.

  3. Accept terms when prompted.

    • If you are not immediately prompted to accept terms, you will be prompted when proceeding with the following steps.

  4. From the Registry Service Accounts page, click Create Service Account

    1. Provide a name for the service account. It will be prepended with a random string.

    2. Enter a description.

    3. Click create.

  5. Navigate back to your Service Accounts.

  6. Click the Service Account you created.

  7. Copy the username, including the prepended string.

  8. Copy the token.

Managing Registry Credentials for Installation and Upgrade

You can also manage registry credentials during installation or upgrade using the Ansible installer.

This will set up the following:

  • imagestreamsecret in your OpenShift namespace.

  • Credentials on all nodes.

Prerequisites

  • User credentials

  • Service account

  • Service account token

Procedure

To manage registry credentials during installation or upgrade using the Ansible installer:

  • During installation or upgrade, specify the oreg_auth_user and oreg_auth_password variables in your installer inventory.

If you have created a token, set oreg_auth_password to the value of the token.

Clusters that require access to additional authenticated registries can configure a list of registries by setting openshift_additional_registry_credentials. Each registry requires a host and password value, you can specify a username by setting user. By default the credentials specified are validated by attempting to inspect the image openshift3/ose-pod on the specified registry.

To specify an alternate image, either:

  • Set test_image.

  • Disable credential validation by setting test_login to False.

If the registry is insecure, set tls_verify to False.

All credentials in this list will have an imagestreamsecret created in the OpenShift namespace and credentials deployed to all nodes.

For example:

openshift_additional_registry_credentials=[{'host':'registry.example.com','user':'name','password':'pass1','test_login':'False'},{'host':'registry2.example.com','password':'token12345','tls_verify':'False','test_image':'mongodb/mongodb'}]

Using Service Accounts with the Red Hat Registry

Once you have created your service accounts and generated tokens for the Red Hat Registry, you can perform additional tasks.

This section provides the manual steps, which can be automatically performed during installation by providing the inventory variables outlined in the Managing Registry Credentials for Installation and Upgrade section.
Prerequisites

  • User credentials

  • Service account

  • Service account token

Procedure

From your Registry Service Accounts page, click on your account name. From there, you can perform the following tasks:

  • From the Token Information tab, you can view your username (the name you provided prepended with a random string) and password (token). From this tab, you can regenerate your token.

  • From the OpenShift Secret tab, you can:

    1. Download the secret by clicking the link in the tab.

    2. Submit the secret to the cluster:

      # oc create -f <account-name>-secret.yml --namespace=openshift

    3. Update your Kubernetes configuration by adding a reference to the secret to your Kubernetes pod configuration with an imagePullSecrets field, for example:

      apiVersion: v1
kind: Pod
metadata:
  name: somepod
  namespace: all
  spec:
    containers:
      - name: web
      image: registry.redhat.io/REPONAME

    imagePullSecrets:
      - name: <numerical-string-account-name>-pull-secret

  • From the Docker Login tab, you can run docker login. For example:

    # docker login -u='<numerical-string|account-name>'
  -p=<token>

    After you successfully log in, copy ~/.docker/config.json to /var/lib/origin/.docker/config.json and restart the node.

    # cp -r ~/.docker /var/lib/origin/
  systemctl restart atomic-openshift-node

  • From the Docker Configuration tab, you can:

    1. Download the credentials configuration by clicking the link in the tab.

    2. Write the configuration to the disk by placing the file in the Docker configuration directory. This will overwrite existing credentials. For example:

      # mv <account-name>-auth.json ~/.docker/config.json