Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 12. Configuring custom SSL/TLS certificates for Red Hat Quay on OpenShift Container Platform

When Red Hat Quay is deployed on OpenShift Container Platform, the tls component of the QuayRegistry custom resource definition (CRD) is set to managed by default. As a result, OpenShift Container Platform’s Certificate Authority is used to create HTTPS endpoints and to rotate SSL/TLS certificates.

You can configure custom SSL/TLS certificates before or after the initial deployment of Red Hat Quay on OpenShift Container Platform. This process involves creating or updating the configBundleSecret resource within the QuayRegistry YAML file to integrate your custom certificates and setting the tls component to unmanaged.

Important

When configuring custom SSL/TLS certificates for Red Hat Quay, administrators are responsible for certificate rotation.

The following procedures enable you to apply custom SSL/TLS certificates to ensure secure communication and meet specific security requirements for your Red Hat Quay on OpenShift Container Platform deployment. These steps assumed you have already created a Certificate Authority (CA) bundle or an ssl.key, and an ssl.cert. The procedure then shows you how to integrate those files into your Red Hat Quay on OpenShift Container Platform deployment, which ensures that your registry operates with the specified security settings and conforms to your organization’s SSL/TLS policies.

Note
  • The following procedure is used for securing Red Hat Quay with an HTTPS certificate. Note that this differs from managing Certificate Authority Trust Bundles. CA Trust Bundles are used by system processes within the Quay container to verify certificates against trusted CAs, and ensure that services like LDAP, storage backend, and OIDC connections are trusted.
  • If you are adding the certificates to an existing deployment, you must include the existing config.yaml file in the new config bundle secret, even if you are not making any configuration changes.

12.1. Creating a Certificate Authority
Copy link

Use the following procedure to set up your own CA and use it to issue a server certificate for your domain. This allows you to secure communications with SSL/TLS using your own certificates.

Procedure

  1. Generate the root CA key by entering the following command: 

    $ openssl genrsa -out rootCA.key 2048
    Copy to Clipboard Toggle word wrap

  2. Generate the root CA certificate by entering the following command: 

    $ openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem
    Copy to Clipboard Toggle word wrap

  3. Enter the information that will be incorporated into your certificate request, including the server hostname, for example: 

    Country Name (2 letter code) [XX]:IE
State or Province Name (full name) []:GALWAY
Locality Name (eg, city) [Default City]:GALWAY
Organization Name (eg, company) [Default Company Ltd]:QUAY
Organizational Unit Name (eg, section) []:DOCS
Common Name (eg, your name or your server's hostname) []:quay-server.example.com
    Copy to Clipboard Toggle word wrap

  4. Generate the server key by entering the following command: 

    $ openssl genrsa -out ssl.key 2048
    Copy to Clipboard Toggle word wrap

  5. Generate a signing request by entering the following command: 

    $ openssl req -new -key ssl.key -out ssl.csr
    Copy to Clipboard Toggle word wrap

  6. Enter the information that will be incorporated into your certificate request, including the server hostname, for example: 

    Country Name (2 letter code) [XX]:IE
State or Province Name (full name) []:GALWAY
Locality Name (eg, city) [Default City]:GALWAY
Organization Name (eg, company) [Default Company Ltd]:QUAY
Organizational Unit Name (eg, section) []:DOCS
Common Name (eg, your name or your server's hostname) []:quay-server.example.com
Email Address []:
    Copy to Clipboard Toggle word wrap

  7. Create a configuration file openssl.cnf, specifying the server hostname, for example:

    Example openssl.cnf file

    [req]
req_extensions = v3_req
distinguished_name = req_distinguished_name
[req_distinguished_name]
[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = <quay-server.example.com>
IP.1 = 192.168.1.112
    Copy to Clipboard Toggle word wrap

  8. Use the configuration file to generate the certificate ssl.cert: 

    $ openssl x509 -req -in ssl.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out ssl.cert -days 356 -extensions v3_req -extfile openssl.cnf
    Copy to Clipboard Toggle word wrap

  9. Confirm your created certificates and files by entering the following command: 

    $ ls /path/to/certificates
    Copy to Clipboard Toggle word wrap

    Example output

    rootCA.key ssl-bundle.cert ssl.key custom-ssl-config-bundle-secret.yaml rootCA.pem ssl.cert
openssl.cnf rootCA.srl  ssl.csr
    Copy to Clipboard Toggle word wrap

After creating your custom SSL/TLS certificates, you can create a custom configBundleSecret resource for Red Hat Quay on OpenShift Container Platform, which allows you to upload ssl.cert and ssl.key files.

Prerequisites

  • You have base64 decoded the original config bundle into a config.yaml file. For more information, see Downloading the existing configuration.
  • You have generated custom SSL certificates and keys.

Procedure

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

    $ touch custom-ssl-config-bundle-secret.yaml
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap
      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
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

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

    $ oc create -n <namespace> -f custom-ssl-config-bundle-secret.yaml
    Copy to Clipboard Toggle word wrap

    Example output

    secret/custom-ssl-config-bundle-secret created
    Copy to Clipboard Toggle word wrap

  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"}}'
    Copy to Clipboard Toggle word wrap

    Example output

    quayregistry.quay.redhat.com/example-registry patched
    Copy to Clipboard Toggle word wrap

  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}]}}'
    Copy to Clipboard Toggle word wrap

    Example output

    quayregistry.quay.redhat.com/example-registry patched
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    Example output

    # ...
  configBundleSecret: custom-ssl-config-bundle-secret
# ...
spec:
  components:
  - kind: tls
    managed: false
# ...
    Copy to Clipboard Toggle word wrap

Verification

  • Confirm a TLS connection to the server and port by entering the following command: 

    $  openssl s_client -connect <quay-server.example.com>:443
    Copy to Clipboard Toggle word wrap

    Example output

    # ...
SSL-Session:
    Protocol  : TLSv1.3
    Cipher    : TLS_AES_256_GCM_SHA384
    Session-ID: 0E995850DC3A8EB1A838E2FF06CE56DBA81BD8443E7FA05895FBD6FBDE9FE737
    Session-ID-ctx:
    Resumption PSK: 1EA68F33C65A0F0FA2655BF9C1FE906152C6E3FEEE3AEB6B1B99BA7C41F06077989352C58E07CD2FBDC363FA8A542975
    PSK identity: None
    PSK identity hint: None
    SRP username: None
    TLS session ticket lifetime hint: 7200 (seconds)

# ...
    Copy to Clipboard Toggle word wrap

Next steps

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat