Chapter 10. Open Container Initiative support

Container registries were originally designed to support container images in the Docker image format. To promote the use of additional runtimes apart from Docker, the Open Container Initiative (OCI) was created to provide a standardization surrounding container runtimes and image formats. Most container registries support the OCI standardization as it is based on the Docker image manifest V2, Schema 2 format.

In addition to container images, a variety of artifacts have emerged that support not just individual applications, but also the Kubernetes platform as a whole. These range from Open Policy Agent (OPA) policies for security and governance to Helm charts and Operators that aid in application deployment.

Red Hat Quay is a private container registry that not only stores container images, but also supports an entire ecosystem of tooling to aid in the management of containers. Red Hat Quay strives to be as compatible as possible with the OCI 1.0 Image and Distribution specifications, and supports common media types like Helm charts (as long as they pushed with a version of Helm that supports OCI) and a variety of arbitrary media types within the manifest or layer components of container images. Support for such novel media types differs from previous iterations of Red Hat Quay, when the registry was more strict about accepted media types. Because Red Hat Quay now works with a wider array of media types, including those that were previously outside the scope of its support, it is now more versatile accommodating not only standard container image formats but also emerging or unconventional types.

In addition to its expanded support for novel media types, Red Hat Quay ensures compatibility with Docker images, including V2_2 and V2_1 formats. This compatibility with Docker V2_2 and V2_1 images demonstrates Red Hat Quay’s' commitment to providing a seamless experience for Docker users. Moreover, Red Hat Quay continues to extend its support for Docker V1 pulls, catering to users who might still rely on this earlier version of Docker images.

Support for OCI artifacts are enabled by default. Prior to this, OCI media types were enabled under the under the FEATURE_GENERAL_OCI_SUPPORT configuration field.

Note

Because all OCI media types are now enabled by default, use of FEATURE_GENERAL_OCI_SUPPORT, ALLOWED_OCI_ARTIFACT_TYPES, and IGNORE_UNKNOWN_MEDIATYPES is no longer required.

Additionally, the FEATURE_HELM_OCI_SUPPORT configuration field has been deprecated. This configuration field is no longer supported and will be removed in a future version of Red Hat Quay.

10.1. Helm and OCI prerequisites

Helm simplifies how applications are packaged and deployed. Helm uses a packaging format called Charts which contain the Kubernetes resources representing an application. Red Hat Quay supports Helm charts so long as they are a version supported by OCI.

Use the following procedures to pre-configure your system to use Helm and other OCI media types.

10.1.1. Installing Helm

Use the following procedure to install the Helm client.

Procedure

  1. Download the latest version of Helm from the Helm releases page.
  2. Enter the following command to unpack the Helm binary:

    $ tar -zxvf helm-v3.8.2-linux-amd64.tar.gz
  3. Move the Helm binary to the desired location:

    $ mv linux-amd64/helm /usr/local/bin/helm

For more information about installing Helm, see the Installing Helm documentation.

10.1.2. Upgrading to Helm 3.8

Support for OCI registry charts requires that Helm has been upgraded to at least 3.8. If you have already downloaded Helm and need to upgrade to Helm 3.8, see the Helm Upgrade documentation.

10.1.3. Enabling your system to trust SSL/TLS certificates used by Red Hat Quay

Communication between the Helm client and Red Hat Quay is facilitated over HTTPS. As of Helm 3.5, support is only available for registries communicating over HTTPS with trusted certificates. In addition, the operating system must trust the certificates exposed by the registry. You must ensure that your operating system has been configured to trust the certificates used by Red Hat Quay. Use the following procedure to enable your system to trust the custom certificates.

Procedure

  1. Enter the following command to copy the rootCA.pem file to the /etc/pki/ca-trust/source/anchors/ folder:

    $ sudo cp rootCA.pem   /etc/pki/ca-trust/source/anchors/
  2. Enter the following command to update the CA trust store:

    $ sudo update-ca-trust extract

10.2. Using Helm charts

Use the following example to download and push an etherpad chart from the Red Hat Community of Practice (CoP) repository.

Prerequisites

  • You have logged into Red Hat Quay.

Procedure

  1. Add a chart repository by entering the following command:

    $ helm repo add redhat-cop https://redhat-cop.github.io/helm-charts
  2. Enter the following command to update the information of available charts locally from the chart repository:

    $ helm repo update
  3. Enter the following command to pull a chart from a repository:

    $ helm pull redhat-cop/etherpad --version=0.0.4 --untar
  4. Enter the following command to package the chart into a chart archive:

    $ helm package ./etherpad

    Example output

    Successfully packaged chart and saved it to: /home/user/linux-amd64/etherpad-0.0.4.tgz
  5. Log in to Red Hat Quay using helm registry login:

    $ helm registry login quay370.apps.quayperf370.perfscale.devcluster.openshift.com
  6. Push the chart to your repository using the helm push command:

    $ helm push etherpad-0.0.4.tgz oci://quay370.apps.quayperf370.perfscale.devcluster.openshift.com

    Example output:

    Pushed: quay370.apps.quayperf370.perfscale.devcluster.openshift.com/etherpad:0.0.4
    Digest: sha256:a6667ff2a0e2bd7aa4813db9ac854b5124ff1c458d170b70c2d2375325f2451b
  7. Ensure that the push worked by deleting the local copy, and then pulling the chart from the repository:

    $ rm -rf etherpad-0.0.4.tgz
    $ helm pull oci://quay370.apps.quayperf370.perfscale.devcluster.openshift.com/etherpad --version 0.0.4

    Example output:

    Pulled: quay370.apps.quayperf370.perfscale.devcluster.openshift.com/etherpad:0.0.4
    Digest: sha256:4f627399685880daf30cf77b6026dc129034d68c7676c7e07020b70cf7130902

10.3. Cosign OCI support

Cosign is a tool that can be used to sign and verify container images. It uses the ECDSA-P256 signature algorithm and Red Hat’s Simple Signing payload format to create public keys that are stored in PKIX files. Private keys are stored as encrypted PEM files.

Cosign currently supports the following:

  • Hardware and KMS Signing
  • Bring-your-own PKI
  • OIDC PKI
  • Built-in binary transparency and timestamping service

Use the following procedure to directly install Cosign.

Prerequisites

  • You have installed Go version 1.16 or later.
  • You have set FEATURE_GENERAL_OCI_SUPPORT to true in your config.yaml file.

Procedure

  1. Enter the following go command to directly install Cosign:

    $ go install github.com/sigstore/cosign/cmd/cosign@v1.0.0

    Example output

    go: downloading github.com/sigstore/cosign v1.0.0
    go: downloading github.com/peterbourgon/ff/v3 v3.1.0

  2. Generate a key-value pair for Cosign by entering the following command:

    $ cosign generate-key-pair

    Example output

    Enter password for private key:
    Enter again:
    Private key written to cosign.key
    Public key written to cosign.pub

  3. Sign the key-value pair by entering the following command:

    $ cosign sign -key cosign.key quay-server.example.com/user1/busybox:test

    Example output

    Enter password for private key:
    Pushing signature to: quay-server.example.com/user1/busybox:sha256-ff13b8f6f289b92ec2913fa57c5dd0a874c3a7f8f149aabee50e3d01546473e3.sig

    If you experience the error: signing quay-server.example.com/user1/busybox:test: getting remote image: GET https://quay-server.example.com/v2/user1/busybox/manifests/test: UNAUTHORIZED: access to the requested resource is not authorized; map[] error, which occurs because Cosign relies on ~./docker/config.json for authorization, you might need to execute the following command:

    $ podman login --authfile ~/.docker/config.json quay-server.example.com

    Example output

    Username:
    Password:
    Login Succeeded!

  4. Enter the following command to see the updated authorization configuration:

    $ cat ~/.docker/config.json
    {
    	"auths": {
    		"quay-server.example.com": {
    			"auth": "cXVheWFkbWluOnBhc3N3b3Jk"
    		}
    	}

10.4. Installing and using Cosign

Use the following procedure to directly install Cosign.

Prerequisites

  • You have installed Go version 1.16 or later.
  • You have set FEATURE_GENERAL_OCI_SUPPORT to true in your config.yaml file.

Procedure

  1. Enter the following go command to directly install Cosign:

    $ go install github.com/sigstore/cosign/cmd/cosign@v1.0.0

    Example output

    go: downloading github.com/sigstore/cosign v1.0.0
    go: downloading github.com/peterbourgon/ff/v3 v3.1.0

  2. Generate a key-value pair for Cosign by entering the following command:

    $ cosign generate-key-pair

    Example output

    Enter password for private key:
    Enter again:
    Private key written to cosign.key
    Public key written to cosign.pub

  3. Sign the key-value pair by entering the following command:

    $ cosign sign -key cosign.key quay-server.example.com/user1/busybox:test

    Example output

    Enter password for private key:
    Pushing signature to: quay-server.example.com/user1/busybox:sha256-ff13b8f6f289b92ec2913fa57c5dd0a874c3a7f8f149aabee50e3d01546473e3.sig

    If you experience the error: signing quay-server.example.com/user1/busybox:test: getting remote image: GET https://quay-server.example.com/v2/user1/busybox/manifests/test: UNAUTHORIZED: access to the requested resource is not authorized; map[] error, which occurs because Cosign relies on ~./docker/config.json for authorization, you might need to execute the following command:

    $ podman login --authfile ~/.docker/config.json quay-server.example.com

    Example output

    Username:
    Password:
    Login Succeeded!

  4. Enter the following command to see the updated authorization configuration:

    $ cat ~/.docker/config.json
    {
    	"auths": {
    		"quay-server.example.com": {
    			"auth": "cXVheWFkbWluOnBhc3N3b3Jk"
    		}
    	}

10.5. Using other artifact types

By default, other artifact types are enabled for use by Red Hat Quay.

Use the following procedure to add additional OCI media types.

Prerequisites

  • You have set FEATURE_GENERAL_OCI_SUPPORT to true in your config.yaml file.

Procedure

  1. In your config.yaml file, add the ALLOWED_OCI_ARTIFACT_TYPES configuration field. For example:

    FEATURE_GENERAL_OCI_SUPPORT: true
    ALLOWED_OCI_ARTIFACT_TYPES:
      <oci config type 1>:
      - <oci layer type 1>
      - <oci layer type 2>
    
      <oci config type 2>:
      - <oci layer type 3>
      - <oci layer type 4>
  2. Add support for your desired artifact type, for example, Singularity Image Format (SIF), by adding the following to your config.yaml file:

    ALLOWED_OCI_ARTIFACT_TYPES:
      application/vnd.oci.image.config.v1+json:
      - application/vnd.dev.cosign.simplesigning.v1+json
      application/vnd.cncf.helm.config.v1+json:
      - application/tar+gzip
      application/vnd.sylabs.sif.config.v1+json:
      - application/vnd.sylabs.sif.layer.v1+tar
    Important

    When adding artifact types that are not configured by default, Red Hat Quay administrators will also need to manually add support for Cosign and Helm if desired.

    Now, users can tag SIF images for their Red Hat Quay registry.

10.6. Disabling OCI artifacts in Red Hat Quay

Use the following procedure to disable support for OCI artifacts.

Procedure

  • Disable OCI artifact support by setting FEATURE_GENERAL_OCI_SUPPORT to false in your config.yaml file. For example:

    FEATURE_GENERAL_OCI_SUPPORT = false