Using Container Registries

9 Using Container Registries

This chapter describes how to sign in to Oracle Container Registry, create a self-hosted container registry, and add new container registry mirrors.

A container registry is a store of Open Container Initiative images. A container image is a read-only template which is used to create running containers. Container images in the registry can be deployed as required.

By default, Oracle Linux systems are configured with access to three commonly used registries:

container-registry.oracle.com

The Oracle Container Registry is an open standards-based, Oracle-managed container registry service for securely storing and sharing container images. The Oracle Container Registry contains both licensed and open source Oracle software, and the images are built and signed by Oracle. Use of the container images is subject to the terms of their respective licenses. Users can pull container images with the familiar Docker Command Line Interface (CLI) and API.

You can configure the container runtime to only trust images from Oracle Container Registry if they're signed to improve security and mitigate against inadvertently running a compromised image. For more information, see Configuring Podman for Signed Images.

The Oracle Container Registry is at https://container-registry.oracle.com. It provides a web interface to browse and select the images for the software that an organization can use.

To use licensed Oracle software images, first sign in to the Oracle Container Registry web interface and accept the Oracle Standard Terms and Restrictions for the required software images.

You can use one of the Oracle Container Registry mirrors for faster download in different geographical regions.
quay.io

The Quay Container Registry is a popular registry provided by Red Hat. Many open source images are available at this registry.
docker.io

The Docker Hub registry provides many software images, primarily for use with Docker but which are compatible with Podman. The Docker Hub registry provides a web interface for browsing available images at https://hub.docker.com.

Enterprise-ready images from Oracle are also available on the Docker Hub.

Enterprise environments might also consider setting up a local container registry. The local container registry would store images that were converted from customized containers. You can then use these images for future container deployment. Storing images in a local container registry reduces the amount of customized configuration that you might need to perform for mass deployments. A local registry can also cache and host images that are pulled from an upstream registry, which further reduces network overhead and latency when you deploy matching containers across a spread of local systems.

Registry Configuration

To configure default registry settings, edit /etc/containers/registries.conf.

The configuration file is commented to explain the options that are available. The registries that are searched when you try to pull or use an image that isn't available locally are defined in the following configuration block:

[registries.search]
registries = ['container-registry.oracle.com', 'quay.io', 'docker.io']

Registries are searched sequentially in the order that they're defined in this list. If a local registry exists, add it at the beginning of the list to make it the first searched registry.

To use an insecure registry without a valid SSL certificate or that doesn't use SSL, add the registry domain name to the registries list in the [registries.insecure] configuration block.

Configuring Podman for Signed Images

You can configure Podman to only trust images from a remote registry if they're signed and the provided signature can be validated against a locally stored public key. This configuration option can help improve security and can mitigate against inadvertently running a compromised image.

Images are signed in a similar way to packages that are made available on the Oracle Linux yum server. GPG keys are used to sign images provided at the registry. The digital signatures for each image are stored in a signature store that's accessible by using HTTPS. A public GPG key that's used to validate the signature against the image digest must be available on the system where Podman is installed.

The following steps describe how to configure a Podman host to require that images from a remote registry are signed and validated before they can be used locally.

For each registry where you require signature validation, create a YAML format configuration file in /etc/containers/registries.d/ and provide the value for the sigstore for that registry.

For example, for the Oracle Container Registry, create a file /etc/containers/registries.d/oracle.yaml and populate it with the following content:
```
docker:
  container-registry.oracle.com:
    sigstore: https://container-trust.oci.oraclecloud.com/podman
```
See /etc/containers/registries.d/default.yaml for more information and to view a template configuration.
Download and store the public GPG key that must be used to validate signatures for images from the registry. For the Oracle Container Registry, you can download the public GPG key at https://container-trust.oci.oraclecloud.com/podman/GPG-KEY-oracle, for example:
```
sudo mkdir -p /etc/pki/containers
sudo wget -O /etc/pki/containers/GPG-KEY-oracle https://container-trust.oci.oraclecloud.com/podman/GPG-KEY-oracle
```
Edit the container policy configuration to add the location of the public GPG key that must be used to validate the signatures for images that are pulled from a particular registry.

The policy configuration is in JSON format and is at /etc/containers/policy.json. Registry configuration appears under the docker key, which you might need to add under the transports key in the existing configuration. For example, a default policy configuration that has been edited to include an entry for the Oracle Container Registry appears as follows:
```
{
  "default": [
    {
      "type": "insecureAcceptAnything"
    }
  ],
  "transports":
    {
      "docker-daemon":
        {
          "": [{"type":"insecureAcceptAnything"}]
        },
      "docker":
        {
          "container-registry.oracle.com": [
            {
              "type": "signedBy",
              "keyType": "GPGKeys",
              "keyPath": "/etc/pki/containers/GPG-KEY-oracle"
            }
          ]
        }
    }
}
```
See the containers-policy.json(5) manual page for more information about the format of this configuration file.

Validate that the configuration is correct by pulling an image from the remote registry. See Pulling Images From the Oracle Container Registry for an example. Note that if the signature requirement is configured correctly, the output isn't different from an output when you pull an image without signature validation configured. You can test that validation is taking place by setting the GPG keyPath in the policy configuration to use another key. For example, you can configure the path to use the GPG key used to validate RPM packages at /etc/pki/rpm-gpg/RPM-GPG-KEY-oracle. Signature validation failure appears as follows:

Trying to pull container-registry.oracle.com/os/oraclelinux:7-slim...
 Invalid GPG signature: gpgme.Signature{Summary:128, Fingerprint:"357217938FC350A2", 
 Status:gpgme.Error{err:0x9}, Timestamp:time.Time{wall:0x0, ext:63754125715, 
 loc:(*time.Location)(0x558c35f0c0a0)}, ExpTimestamp:time.Time{wall:0x0, ext:62135596800, 
 loc:(*time.Location)(0x558c35f0c0a0)}, WrongKeyUsage:false, PKATrust:0x0, 
 ChainModel:false, Validity:0, ValidityReason:error(nil), PubkeyAlgo:1, HashAlgo:2}
Error: Source image rejected: Invalid GPG signature: gpgme.Signature{Summary:128, 
 Fingerprint:"357217938FC350A2", Status:gpgme.Error{err:0x9}, Timestamp:time.Time{wall:0x0, 
 ext:63754125715, loc:(*time.Location)(0x558c35f0c0a0)}, ExpTimestamp:time.Time{wall:0x0, 
 ext:62135596800, loc:(*time.Location)(0x558c35f0c0a0)}, WrongKeyUsage:false, PKATrust:0x0, 
 ChainModel:false, Validity:0, ValidityReason:error(nil), PubkeyAlgo:1, HashAlgo:2}

Pulling Images From the Oracle Container Registry

If you're pulling a licensed Oracle software image, you must first sign in to the Oracle Container Registry and accept the Oracle Standard Terms and Restrictions. For information about pulling licensed Oracle software from the Oracle Container Registry, see Pulling Licensed Software From the Oracle Container Registry.

To pull an image from the Oracle Container Registry, use the following command:

sudo podman pull container-registry.oracle.com/area/image:tag

Substitute area with the repository location in the Oracle Container Registry, and image with the name of the software image. For example:

sudo podman pull container-registry.oracle.com/os/oraclelinux:7-slim

The area and image are nearly always specified in lowercase. Note that when referencing images, we recommend that you always specify the appropriate tag to use.

Note:

The correct command to pull an image is usually provided on the repository information page in the Oracle Container Registry web interface. Other useful information about the image and how to run it might also be available on the same page.

The Oracle Container Registry contains images for licensed commercial Oracle software products. To pull images for licensed software on the Oracle Container Registry, you must have an Oracle Account. You can create an Oracle Account at https://profile.oracle.com/myprofile/account/create-account.jspx.

Note:

You don't need to sign in to the Oracle Container Registry or accept the Oracle Standard Terms and Restrictions to pull open source Oracle software images.

Pull a licensed software image from the Oracle Container Registry as follows:

In a web browser, sign in to the Oracle Container Registry using an Oracle account at https://container-registry.oracle.com.
Accept the Oracle Standard Terms and Restrictions for the Oracle software images you want to pull. Acceptance of these terms are stored in a database that links the software images to an Oracle Account. Acceptance of the Oracle Standard Terms and Restrictions is valid only for the repositories for which you accept the terms. You might need to repeat this process if you try to pull software from other or newer repositories in the registry. Note that Oracle Standard Terms and Restrictions are subject to change without notice.
Browse or search for Oracle software images.
On the host system, use the podman login command to authenticate against the Oracle Container Registry.
```
sudo podman login container-registry.oracle.com
```
Provide an Oracle account username and password as prompted.
Pull the images that you require by using the podman pull command, for example:
```
sudo podman pull container-registry.oracle.com/java/serverjre
```
For more detailed information about pulling images from the Oracle Container Registry, see Pulling Images From the Oracle Container Registry.

The image is pulled from the Oracle Container Registry and stored locally, ready to be used to deploy containers.
After you have pulled images from the Oracle Container Registry, log out of the registry to prevent unauthorized access and to remove any record of sign in credentials that Podman might store for future operations:
```
sudo podman logout container-registry.oracle.com
```

Using the Oracle Container Registry Mirrors With Podman

The Oracle Container Registry has many mirror servers around the world. You can use a registry mirror in a specific global region to improve download performance of container images.

To list all the available mirrors and the command to use for pulling images from a specific mirror, see the information page for an image by using the Oracle Container Registry web interface. The Tags table at the bottom of the information page includes a Download Mirror drop down list to select a registry mirror. When you select a mirror, the Pull Command column changes to show the command to pull the image from the selected mirror.

For example, the command to pull the Oracle Linux 7 image from the Sydney mirror would be the following:

sudo podman pull container-registry-sydney.oracle.com/os/oraclelinux:7-slim

To download licensed Oracle software images from a registry mirror, you must first accept the Oracle Standard Terms and Restrictions in the Oracle Container Registry web interface, which is at https://container-registry.oracle.com .

To pull licensed Oracle software images, sign in to the Oracle Container Registry mirror before you pull the image, for example:

sudo podman login container-registry-sydney.oracle.com
sudo podman pull container-registry-sydney.oracle.com/java/serverjre
sudo podman logout container-registry-sydney.oracle.com.oracle.com

If you use a mirror regularly, add it to the configuration so that the mirror is used by default for searches and pull requests. See Registry Configuration for more information.

Using the Docker Hub With Podman

The Docker Hub contains Docker images for licensed commercial Oracle software products that you might use in your enterprise. The Docker Hub is at https://hub.docker.com.

You can browse the Docker Hub and to pull some images from the hub anonymously. However, to access most images hosted in the Docker Hub, you must sign in with a valid Docker ID. You can register for a Docker ID at https://hub.docker.com/signup.

The Docker Hub provides a web interface where you can select the Docker Certified images that you want to install. For some images, you would need to click Proceed to Checkout button to either agree to any terms and conditions that might apply or to make payment if required before you can access the image.

At the conclusion of the transaction, the image is stored in the My Content area, which you can revisit later.

Each image provides a description and set up instructions.

The following example illustrates how you can sign in to the Docker Hub, inspect, and pull an image:

sudo podman login
sudo skopeo inspect docker://docker.io/store/oracle/database-enterprise:12.2.0.1
sudo podman pull docker.io/store/oracle/database-enterprise:12.2.0.1-slim

Setting Up a Local Container Registry

This section contains information about setting up a local container registry server, which can be used to host images, and can also be used as a mirror for the Oracle Container Registry.

The registry server is a container application. The host must have an Internet connection to download the registry image either from the Docker Hub or, if support is required, from the Oracle Container Registry.

The registry server requires at least 15 GB of available disk space to store registry data, typically in /var/lib/registry, although you can select another path if you intend to run the registry as a standard user. As a good practice, create a separate file system for the local container registry, preferably a Btrfs formatted file system. By using the Btrfs file system, you can easily scale the registry file system and leverage Btrfs features such as file system snapshots.

Setting Up Transport Layer Security for the Registry

The registry host requires a valid X.509 certificate and private key to enable Transport Layer Security (TLS) with the registry, similar to using TLS for a web server. This section discusses adding the host's X.509 certificate and private key to Podman.

If the host already has an X.509 certificate, you can use the same certificate with Podman.

If the host doesn't have an X.509 certificate, you can create a self-signed, private certificate for testing purposes. For information about creating a self-signed certificate and private key, see Oracle Linux: Managing Certificates and Public Key Infrastructure.

To disable X.509 certificate validation for testing purposes, see Registry Configuration.

Use the X.509 Certificate with Podman as follows:

If the host's X.509 certificate was issued by an intermediate Certificate Authority (CA), combine the host's certificate with the intermediate CA's certificate to create a chained certificate to enable Docker to verify the host's X.509 certificate, for example:
```
sudo cat registry.example.com.crt intermediate-ca.pem > domain.crt
```
Create the /var/lib/registry/conf.d directory to store the certificate and private key.
```
sudo mkdir -p /var/lib/registry/conf.d
```

Copy the certificate and private key to the /var/lib/registry/conf.d directory.

sudo cp certfile /var/lib/registry/conf.d/domain.crt
sudo cp keyfile /var/lib/registry/conf.d/domain.key

In the command, certfile is the full path to the host's X.509 certificate or to the chained certificate and keyfile is the full path to the host's private key, for example:

sudo cp /etc/pki/tls/certs/registry.example.com.crt /var/lib/registry/conf.d/domain.crt
sudo cp /etc/pki/tls/private/registry.example.com.key /var/lib/registry/conf.d/domain.key

Ensure the file permissions are correct for the private key.
```
sudo chmod 600 /var/lib/registry/conf.d/domain.key
```

Creating the Registry

This section discusses creating the registry server as a container application. Perform these steps on the registry host.

Create the Podman registry container. For example:

sudo podman run -d -p 5000:5000 --name registry --restart=always \
    -v /var/lib/registry:/registry_data \
    -e REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/registry_data \
    -e REGISTRY_HTTP_TLS_KEY=/registry_data/conf.d/domain.key \
    -e REGISTRY_HTTP_TLS_CERTIFICATE=/registry_data/conf.d/domain.crt \
    -e REGISTRY_AUTH="" \
    container-registry.oracle.com/os/registry:v2.7.1.1

The registry image is pulled from the Oracle Container Registry and the registry container is started.

The --restart=always option starts the registry container when it's started.

By default, the port number used by container services is 5000. If needed, you can use a different port number for a container registry and map that port to 5000, for example portnumber:5000. For more information about mapping ports in Podman, see Configuring Networking for Podman.

If you don't have an Oracle account and don't require support, you can alternately use the publicly available container registry image at docker.io/library/registry:latest.

Setting Up the Registry Port

The registry server runs on port 5000 by default. If you run other services that use the same TCP port, such as the OpenStack Keystone service, you might need to change the configuration to avoid a port conflict. All systems that require access to the registry server must be able to communicate on this port. Ensure that you adjust any firewall rules to prevent port conflict..

If you're running a firewall, ensure the TCP port that you want the container registry to listen on is accessible. If you're running firewalld, add the default rule for the docker-registry service.

sudo firewall-cmd --zone=public --permanent --add-service=docker-registry

If you don't run the registry on the default port, you can specify the port directly, for example:

sudo firewall-cmd --zone=public --permanent --add-port=5001/tcp

Distributing X.509 Certificates

If the registry host uses a self-signed X.509 certificate, you must distribute the certificate to all the hosts in the deployment for which you intend to use the local container registry. For the root user, certificates for each registry are stored in /etc/containers/certs.d/registry_hostname:port/. For standard users, certifcates can be stored in $HOME/.local/share/containers/certs.d/registry_hostname:port/.

Podman, Buildah, and Skopeo commands that interact with registries also usually support a --cert-dir option to specify an alternate location for these certificates.

Perform the following steps on each host that needs to access the local registry. Substitute registry_hostname with the name of the registry host, and port with the port number you selected for your container registry server (5000 by default).

To distribute a self signed X.509 certificate:

Create the appropriate certs.d location for the registry host and your user. For example, for the root user, create a directory at /etc/containers/certs.d/registry_hostname:port.
```
sudo mkdir -p /etc/containers/certs.d/registry_hostname:port
```

Copy the X.509 certificate from the registry host.

sudo scp root@registry_hostname:/var/lib/registry/conf.d/domain.crt \
/etc/containers/certs.d/registry_hostname:port/ca.crt

Importing Images Into a Registry

When you have set up a container registry server, you can import images into the registry so that they can be used to deploy containers. You can pull images from a registry, such as the Oracle Container Registry, and then commit them to a local registry. You can also create custom images based on upstream images.

Pull an image from a registry.

For example, to pull an image from the Oracle Container Registry, type:
```
sudo podman pull container-registry.oracle.com/os/oraclelinux:7-slim
```
Tag the image so that it points to the local registry. For example:
```
sudo podman tag container-registry.oracle.com/os/oraclelinux:7-slim localhost:portnumber/ol7image:v1
```
In this example, localhost is the hostname of the local registry, and portnumber, which, by default, is 5000, is the port number that the registry listens on. If you're working on a Podman installation on a different host to the registry, you must change the hostname to point to the correct host. Note the repository and tag name, ol7image:v1 in the example, must all be in lowercase to be a valid tag.

Push the image to the local registry, for example:

sudo podman push localhost:portnumber/ol7image:v1

See Building Images With Buildah for more information about how you can create images. When you have committed a customized image, you can tag it and push it to the local registry.