Configuring the OpenShift Container Platform internal registry

OpenShift® Container Platform provides an internal registry that might or might not already be configured for external usage.

To allow the installation script to properly push images to the internal registry, perform the following steps:

• Create a route to expose the registry
• Configure the Docker CLI to trust the registry

Creating a route to expose the registry

Note: You can ignore this step if an existing Route exposes the internal registry and contains registry in the name.

If you are using OpenShift Container Platform 4.2 or 4.3, follow the instructions on Exposing the registry in the OpenShift Container Platform documentation.

If you are using OpenShift Container Platform 3.11, complete the following steps:

1. In the OpenShift Container Platform web console, click your avatar in the upper right corner and then click Copy Login Command.
2. In the terminal of your local machine, paste the copied command that is similar to the following example. You will log in as a cluster administrator and start to use one of the existing projects on the cluster.

   oc login https://<ocp-address>:<ocp-port> --token=<token>
   

3. Determine the project that the internal registry is running on and set the oc client to use that project.

   • On OCP 3.11 - typically the default project
   • On OCP 4.2 or 4.3 - typically the openshift-image-registry project

   oc project <project-name>
   

4. Identify the service name that is exposing the registry internally.

   oc get svc
   

   Example output:

   NAME             TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
   image-registry   ClusterIP   172.30.70.120   <none>        5000/TCP   43d
   

   Note: On OpenShift Container Platform v3.11, you can see a docker-registry and a registry-console service. You must expose the docker-registry service.

5. Create a secured route for the image-registry service that uses reencrypt TLS termination. With re-encryption, the router terminates the TLS connection with a certificate, and then re-encrypts the connection to the internal registry with a different certificate. With this approach, the full path of the connection between the user and the internal registry is encrypted. To provide your own custom domain name, include the --hostname flag.

   oc create route reencrypt --service=image-registry
   

   Note: The installation script requires that this route has registry in its name. If that term is not present, or there are multiple routes that use the term registry, the installation script might fail to load the docker images.

6. Retrieve the hostname and port (HOST/PORT) that were assigned to the image-registry route. This will be needed to configure your docker CLI for secure authentication to this internal docker registry.

   oc get route image-registry
   

   Example output:

   NAME             HOST/PORT                                                                    PATH   SERVICES         PORT       TERMINATION   WILDCARD
   image-registry   image-registry-openshift-image-registry.<cluster_domain>                            image-registry   5000-tcp   reencrypt     None
   

   Note: In the example output above, record image-registry-openshift-image-registry.<cluster_domain> for future use.

Configure the Docker CLI to trust the registry

1. Retrieve the root CA certificate from the created route. This can be done in multiple ways, for example, use the openssl command. Replace the <route_hostname> with the registry hostname that is previously recorded. This command creates a PEM encoded registry_ca.crt file in your current directory.

   openssl s_client -showcerts -connect <route_hostname>:443 < /dev/null |  awk '/BEGIN/ {c=1; print >"registry_ca.crt"; next} /END/ {print >"registry_ca.crt"; exit}; c{print >"registry_ca.crt"}'
   

   Example output:

   depth=1 CN = ingress-operator@1575523653
   verify error:num=19:self signed certificate in certificate chain
   verify return:0
   

   Note: If a verify error is displayed, as seen in the example output above, this might safely be ignored. It is caused by the docker image registry route using a self-signed certificate.

2. Add the CA certificate of your cluster to your local machine's trust store.

   • Linux®

     mkdir -p /etc/docker/certs.d/<route_hostname>
     cp registry_ca.crt /etc/docker/certs.d/<route_hostname>/ca.crt
     service docker restart
     docker login -u $(oc whoami) -p $(oc whoami -t) <route_hostname>
     

   • macOS

     mkdir -p ~/.docker/certs.d/<route_hostname>
     cp registry_ca.crt ~/.docker/certs.d/<route_hostname>/ca.crt
     sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.docker/certs.d/<route_hostname>/ca.crt
     

     On the client computer, restart the docker service by selecting the Restart option in the Docker Desktop application. Then, attempt to log in with the following command:

     docker login -u $(oc whoami) -p $(oc whoami -t) <route_hostname>
     

   • Windows

     1. Select Start > Administrative Tools > Manage Computer Certificates.
     2. Right-click Trusted Root Certification Authorities, and select All tasks > Import.
     3. Navigate to find and select your registry_ca.crt file.
     4. Complete the wizard to configure the certificate. The defaults are often acceptable.
     5. Restart Docker for Windows to apply the changes.