With the release of IBM® z/OS® Container Platform (zOSCP), building and running containers natively on z/OS, by leveraging open-source container tooling, is now possible. In addition, zOSCP provides container orchestration through Kubernetes.

To enable users to containerize their own z/OS UNIX applications, a growing catalog of IBM-built images is available on the IBM® Cloud Container Registry (ICR). For example, IBM z/OS base, IBM Open Enterprise SDK for Go, IBM SDK Java Technology Edition for z/OS (Java 8), IBM z/OS Connect, and IBM Open Enterprise Foundation for z/OS container images are available to use as the starting point for building your own container images.

But where do you host the container images that are pulled down from ICR or the container images you build, so that others in your organization can access them? A container registry is a repository used to store and access container images. By using a private container registry, you control who has access to push (store) or pull (retrieve) container images for your enterprise.

Requirements for a private registry

When deciding to use a private container registry for storing container images, several questions need to be answered. Where do I host the private registry? How do I securely access the private registry? How do I restrict access to the private registry?

Hosting the private container registry in the same z/OS environment where z/OS Container Platform is enabled will simplify the management of your private registry. A logical location is to configure and deploy a registry container image within IBM® z/OS® Container Extensions (zCX). zCX enables you to deploy Linux applications as Docker containers on z/OS.

Securing access to the private container registry involves creating a certificate and configuring the registry to use TLS whenever the private registry is accessed.

And finally, to restrict access to the private container registry, username/password authentication is enabled so that a user must first log into the registry before being able to push or pull container images.

Configuring and running your own private registry

After your z/OS Container Extensions (zCX) instance is available, use an SSH client to access the zCX Docker CLI environment.

The first step is to pull the images that you need to securely configure a private container registry. You will use three container images from docker.io.

Next, you create a persistent volume to store the container images that are pushed to the private container registry, and a persistent volume to store the credentials needed to securely configure the private registry. These persistent volumes allow the registry container image to be stopped, upgraded, and restarted, without losing any of the container images and credentials that were previously available.

You are now ready to create the certificate and private key to establish TLS sessions between the private container registry, and the users accessing the registry. You will use the openssl client that is available in the zCX Docker CLI environment to create a certificate and associated private key that is valid for one year.

When creating the certificate and private key, substitute the fully qualified hostname that you use to access the zCX instance, for example, my-zcx.my-company.com, for my-zcx-hostname. Make sure you use the same fully qualified hostname for both the subjectAltName and Common Name input. This fully qualified hostname needs to resolve to the IP address configured for your zCX instance.

Next, you need to create the username/password credentials that will be used for basic authentication to access the private container registry. To do this, you will use the htpasswd utility within the httpd container image you pulled previously. This utility will create and encrypt the file used to store the username and password. A bash script will be used to run the httpd container image, so that the password is not displayed on the command line nor viewable from the bash history. Substitute the username you want to use for username and specify the password to be assigned for this username.

Now that you have the TLS certificate, private key, and encrypted username/password credentials, you need to copy them to the registry_creds persistent volume. This allows the credentials to be accessible to the registry container image when it is started.  You will temporarily use the busybox container image you pulled previously to mount the persistent volume to the running container image and copy this information to the persistent volume.

Next, you need to build your own registry container image based on the registry container image you pulled previously. This is required because the latest registry container image no longer contains the htpasswd utility. You need to build a registry container image that contains this utility, to perform basic username/password authentication. You will create a Dockerfile first, and then build your own registry container image from that. The apache2-utils package provides this htpasswd utility.

You are now ready to run your private container registry. You need to let the registry container image know what type of authentication you want, and where to locate the authentication credentials.

There is a lot going on in this docker command, so let’s step through each parameter.

-d indicates that the registry container image will run in the background, freeing up your ssh session to perform other operations.

--restart=always notifies the Docker daemon to restart the registry container image indefinitely. This is useful for whenever you take down the zCX instance and restart it because the registry container image will automatically be started once the zCX instance is active.

-v registry_creds:/certs:ro mounts the persistent volume, registry_creds to the /certs mountpoint as read-only when the registry container image is started.

-v registry_data:/var/lib/registry mounts the persistent volume, registry_data to the /var/lib/registry mountpoint when the registry container image is started. This mountpoint is used by the private registry to store all container images pushed to it, so that these container images persist across registry container restarts and upgrades.

-e REGISTRY_HTTP_ADDR=0.0.0.0:443 configures the private registry to listen for requests on port 443, the default.

-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt lets the private registry know that TLS authentication is required and the location of the certificate to use. Note that this certificate resides on the persistent volume you mounted above.

-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key lets the private registry know that TLS authentication is required and the location of the private key to use. Note that this private key resides on the persistent volume you mounted above.

-e REGISTRY_AUTH=htpasswd configures the private registry to use htpasswd as the authentication method.

-e “REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm” defines the authentication realm displayed to users when they are prompted for credentials.

-e REGISTRY_AUTH_HTPASSWD_PATH=/certs/htpasswd specifies the path to the file containing the encrypted username and password for basic authentication. Note that this file resides on the persistent volume you mounted above.

-p 1443:443 exposes the internal port, 443, used by the private registry as port 1443 on the zCX instance. Port 443 is a restricted port on zCX, so it needs to be mapped to a non-restricted port, such as 1443. This port number is required by users when accessing the private registry to pull or push container images.

Congratulations! You now have an active, running private container registry to use for your z/OS Container Platform images. It is now safe to remove the files containing the TLS private key and encrypted username/password file from the zCX instance. Do not remove the TLS certificate file because that will be needed when you start accessing the private registry.

In Figure 1, you now have a private container registry running as a container within zCX on the z/OS system.

Figure 1 – z/OS Container Platform system

In the next article, “Using your private registry for z/OS Container Platform”, from an ssh session on z/OS, you will learn how to use IBM z/OS for Skopeo (Skopeo) to copy container images from IBM Cloud Container Registry to your private container registry, how to use Podman for IBM z/OS (Podman) to pull, build, and push container images back to your private registry, and how to create Kubernetes secrets for accessing container images in your private registry for your deployments.