Chapter 1. SSL and TLS for Red Hat Quay

Procedure

1. Copy the certificate file and primary key file to your configuration directory, ensuring they are named ssl.cert and ssl.key respectively:

   cp ~/ssl.cert ~/ssl.key /path/to/configuration_directory

2. Navigate to the configuration directory by entering the following command:

   $ cd /path/to/configuration_directory

3. Edit the config.yaml file and specify that you want Red Hat Quay to handle SSL/TLS:

   Example config.yaml file

   # ...
   SERVER_HOSTNAME: <quay-server.example.com>
   ...
   PREFERRED_URL_SCHEME: https
   # ...

4. Optional: Append the contents of the rootCA.pem file to the end of the ssl.cert file by entering the following command:

   $ cat rootCA.pem >> ssl.cert

5. Stop the Quay container by entering the following command:

   $ sudo podman stop <quay_container_name>

6. Restart the registry by entering the following command:

   $ sudo podman run -d --rm -p 80:8080 -p 443:8443 \
     --name=quay \
     -v $QUAY/config:/conf/stack:Z \
     -v $QUAY/storage:/datastorage:Z \
     registry.redhat.io/quay/quay-rhel8:v3.13.1

Procedure

1. Copy the root CA file to one of /etc/containers/certs.d/ or /etc/docker/certs.d/. Use the exact path determined by the server hostname, and name the file ca.crt:

   $ sudo cp rootCA.pem /etc/containers/certs.d/quay-server.example.com/ca.crt

2. Verify that you no longer need to use the --tls-verify=false option when logging in to your Red Hat Quay registry:

   $ sudo podman login quay-server.example.com

   Example output

   Login Succeeded!

Procedure

1. Enter the following command to copy the rootCA.pem file to the consolidated system-wide trust store:

   $ sudo cp rootCA.pem /etc/pki/ca-trust/source/anchors/

2. Enter the following command to update the system-wide trust store configuration:

   $ sudo update-ca-trust extract

3. Optional. You can use the trust list command to ensure that the Quay server has been configured:

   $ trust list | grep quay
       label: quay-server.example.com

   Now, when you browse to the registry at https://quay-server.example.com, the lock icon shows that the connection is secure:

   

4. To remove the rootCA.pem file from system-wide trust, delete the file and update the configuration:

   $ sudo rm /etc/pki/ca-trust/source/anchors/rootCA.pem

   $ sudo update-ca-trust extract

   $ trust list | grep quay

Procedure

1. Create a new YAML file, for example, custom-ssl-config-bundle-secret.yaml:

   $ touch custom-ssl-config-bundle-secret.yaml

2. Create the custom-ssl-config-bundle-secret resource.

   1. Create the resource by entering the following command:

      $ oc -n <namespace> create secret generic custom-ssl-config-bundle-secret \
        --from-file=config.yaml=</path/to/config.yaml> \ 1
        --from-file=ssl.cert=</path/to/ssl.cert> \ 2
        --from-file=extra_ca_cert_<name-of-certificate>.crt=ca-certificate-bundle.crt
       \ 3
        --from-file=ssl.key=</path/to/ssl.key> \ 4
        --dry-run=client -o yaml > custom-ssl-config-bundle-secret.yaml

      1

      Where <config.yaml> is your base64 decoded config.yaml file.

      2

      Where <ssl.cert> is your ssl.cert file.

      3

      Optional. The --from-file=extra_ca_cert_<name-of-certificate>.crt=ca-certificate-bundle.crt field allows Red Hat Quay to recognize custom Certificate Authority (CA) files. If you are using LDAP, OIDC, or another service that uses custom CAs, you must add them via the extra_ca_cert path. For more information, see "Adding additional Certificate Authorities to Red Hat Quay on OpenShift Container Platform."

      4

      Where <ssl.key> is your ssl.key file.

3. Optional. You can check the content of the custom-ssl-config-bundle-secret.yaml file by entering the following command:

   $ cat custom-ssl-config-bundle-secret.yaml

   Example output

   apiVersion: v1
   data:
     config.yaml: QUxMT1dfUFVMTFNfV0lUSE9VVF9TVFJJQ1RfTE9HR0lORzogZmFsc2UKQVVUSEVOVElDQVRJT05fVFlQRTogRGF0YWJhc2UKREVGQVVMVF9UQUdfRVhQSVJBVElPTjogMncKRElTVFJJQlVURURfU1R...
     ssl.cert: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVYakNDQTBhZ0F3SUJBZ0lVTUFBRk1YVWlWVHNoMGxNTWI3U1l0eFV5eTJjd0RRWUpLb1pJaHZjTkFRRUwKQlFBd2dZZ3hDekFKQmdOVkJBWVR...
     extra_ca_cert_<name-of-certificate>:LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVYakNDQTBhZ0F3SUJBZ0lVTUFBRk1YVWlWVHNoMGxNTWI3U1l0eFV5eTJjd0RRWUpLb1pJaHZjTkFRRUwKQlFBd2dZZ3hDe...
     ssl.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2UUlCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktjd2dnU2pBZ0VBQW9JQkFRQ2c0VWxZOVV1SVJPY1oKcFhpZk9MVEdqaS9neUxQMlpiMXQ...
   kind: Secret
   metadata:
     creationTimestamp: null
     name: custom-ssl-config-bundle-secret
     namespace: <namespace>

4. Create the configBundleSecret resource by entering the following command:

   $ oc create -n <namespace> -f custom-ssl-config-bundle-secret.yaml

   Example output

   secret/custom-ssl-config-bundle-secret created

5. Update the QuayRegistry YAML file to reference the custom-ssl-config-bundle-secret object by entering the following command:

   $ oc patch quayregistry <registry_name> -n <namespace> --type=merge -p '{"spec":{"configBundleSecret":"custom-ssl-config-bundle-secret"}}'

   Example output

   quayregistry.quay.redhat.com/example-registry patched

6. Set the tls component of the QuayRegistry YAML to false by entering the following command:

   $ oc patch quayregistry <registry_name> -n <namespace> --type=merge -p '{"spec":{"components":[{"kind":"tls","managed":false}]}}'

   Example output

   quayregistry.quay.redhat.com/example-registry patched

7. Ensure that your QuayRegistry YAML file has been updated to use the custom SSL configBundleSecret resource, and that your and tls resource is set to false by entering the following command:

   $ oc get quayregistry <registry_name> -n <namespace> -o yaml

   Example output

   # ...
     configBundleSecret: custom-ssl-config-bundle-secret
   # ...
   spec:
     components:
     - kind: tls
       managed: false
   # ...