Chapter 5. Customizing your Red Hat Quay cluster


Although you can run a default Red Hat Quay setup by simply creating a secret and the QuayEcosystem custom resource, the following sections describe how you can modify the default setup.

5.1. Changing your Red Hat Quay credentials

The Red Hat Quay Operator sets up default administrative credentials. Review the default superuser and configuration credentials and change as needed.

5.1.1. Red Hat Quay superuser credentials

The Red Hat Quay superuser credentials let you manage the users, projects and other components of your Red Hat Quay deployment. Here’s how superuser credentials are set by default:

  • Username: quay
  • Password: password
  • Email: quay@redhat.com

To change the superuser credentials, create a new secret:

$ oc create secret generic <secret_name> \
   --from-literal=superuser-username=<username> \
   --from-literal=superuser-password=<password> \
   --from-literal=superuser-email=<email>

The superuser password must be at least 8 characters.

Note

It is recommended that you also set the superusers field of the quay property in the QuayEcosystem object so as to ensure consistency between the the various properties. See the Superusers section below.

5.1.2. Red Hat Quay configuration credentials

A dedicated Red Hat Quay deployment runs to manage Red Hat Quay configuration settings. Using the route to that configuration, you log in with the following credentials:

  • Username: quayconfig
  • Password: quay

You cannot change the username, but you can change the password as follows:

$ oc create secret generic quay-config-app \
      --from-literal=config-app-password=<password>

The PostgreSQL relational database is used by default as the persistent store for Red Hat Quay. PostgreSQL can either be deployed by the Operator within the namespace or leverage an existing instance. The determination of whether to provision an instance or not within the current namespace depends on whether the server property within the QuayEcosystem is defined.

The following options are a portion of the available options to configure the PostgreSQL database:

Expand

Property

Description

image

Location of the database image

volumeSize

Size of the volume in Kubernetes capacity units

Note

It is important to note that persistent storage for the database will only be provisioned if the volumeSize property is specified when provisioned by the operator.

Define the values as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    database:
      volumeSize: 10Gi

5.3. Specifying database credentials

The credentials for accessing the server can be specified through a Secret or when being provisioned by the operator, leverage the following default values:

  • Username: quay
  • Password: quay
  • Root Password: quayAdmin
  • Database Name: quay

To define alternate values, create a secret as shown below:

oc create secret generic <secret_name> \
    --from-literal=database-username=<username> \
    --from-literal=database-password=<password> \
    --from-literal=database-root-password=<root-password> \
    --from-literal=database-name=<database-name>

Reference the name of the secret in the QuayEcosystem custom resource as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    database:
      credentialsSecretName: <secret_name>

Instead of having the operator deploy an instance of PostgreSQL in the project, an existing instance can be leveraged by specifying the location in the server field along with the credentials for access as described in the previous section. The following is an example of how to specify connecting to a remote PostgreSQL instance:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    database:
      credentialsSecretName: <secret_name>
      server: postgresql.databases.example.com

5.4. Choosing a registry storage backend

Red Hat Quay supports multiple backends for the purpose of image storage and consist of a variety of local and cloud storage options. The following sections provide an overview how to configure the Red Hat Quay Operator to make use of these backends.

5.4.1. Overview of storage backends

Storage for Red Hat Quay can be configured using the registryBackend field within the quay property in the QuayEcosystem resource which contain an array of backends. The ability to define multiple backends enables replication and high availability of images.

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    registryBackends:
      - name: backend1
        s3:
        ...

The definition of a registryBackend is an optional field, and if omitted, LocalStorage will be configured (ephemeral, through the use of a PersistentVolume, can be enabled if desired).

5.4.2. Sensitive storage values

In many cases, access to storage requires the use of sensitive values. Each backend that requires such configuration can be included in a Secret and defined within the credentialsSecretName property of the backend.

Instead of declaring the registry backend properties within the specific backend, the values can be added to a secret as shown below:

oc create secret generic s3-credentials \
   --from-literal=accessKey=<accessKey> \
   --from-literal=secretKey=<secretKey>

With the values now present in the secret, the properties explicitly declared in the backend can be removed.

Specific details on the types of properties supported for each backend are found in the registry backend details below.

5.4.3. Storage replication

Support is available to replicate the registry storage to multiple backends. To activate storage replication, set the enableStorageReplication property to the value of true. Individual registry backends can also be configured to be replicated by default by setting the replicateByDefault property to the value of true. A full configuration demonstrating the replication options available is shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    enableStorageReplication: true
    registryBackends:
      - name: azure-ussouthcentral
        credentialsSecretName: azure-ussouthcentral-registry
        replicateByDefault: true
        azure:
          containerName: quay
      - name: azure-seasia
        credentialsSecretName: azure-seasia-registry
        replicateByDefault: true
        azure:
          containerName: quay
Note

Support for replicated storage is not available for the local registry backend and will result in an error during the verification phase.

5.4.4. Registry storage backend types

One or more of the following registry storage backends can be defined to specify the underlying storage for the Red Hat Quay registry:

5.4.4.1. Local Storage

The following is an example for configuring the registry to make use of local storage (note that local storage is not supported for production deployments):

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    registryBackends:
      - name: local
        local:
          storagePath: /opt/quayregistry

The following is a comprehensive list of properties for the local registry backend:

Expand

Property

Description

Credential Secret Supported

Required

storagePath

Storage Directory

No

No

5.4.4.2. Configuring persistent local storage

By default, Red Hat Quay uses an ephemeral volume for local storage. In order to avoid data loss, persistent storage is required. To enable the use of a PersistentVolume to store images, specify the registryStorage parameter underneath the quay property.

The following example will cause a PersistentVolumeClaim to be created within the project requesting storage of 10Gi and an access mode of ReadWriteOnce. The default value is ReadWriteMany.

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    imagePullSecretName: redhat-pull-secret
    registryStorage:
      persistentVolumeAccessModes:
        - ReadWriteOnce
      persistentVolumeSize: 10Gi

A Storage Class can also be provided using the persistentVolumeStorageClassName property.

5.4.4.3. Amazon Web Services (S3)

The following is an example for configuring the registry to make use of S3 storage on Amazon Web Services.

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    registryBackends:
      - name: s3
        s3:
          accessKey: <accessKey>
          bucketName: <bucketName>
          secretKey: <secretKey
          host: <host>

The following is a comprehensive list of properties for the s3 registry backend:

Expand

Property

Description

Credential Secret Supported

Required

storagePath

Storage Directory

No

No

bucketName

S3 Bucket

No

Yes

accessKey

AWS Access Key

Yes

Yes

secretKey

AWS Secret Key

Yes

Yes

host

S3 Host

No

No

port

S3 Port

No

No

5.4.4.4. Microsoft Azure storage

The following is an example for configuring the registry to make use of Blob storage on the Microsoft Azure platform.

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    registryBackends:
      - name: azure
        azure:
          containerName: <containerName>
          accountName: <accountName>
          accountKey: <accountKey>

The following is a comprehensive list of properties for the azure registry backend:

Expand

Property

Description

Credential Secret Suppazureorted

Required

storagePath

Storage Directory

No

No

containerName

Azure Storage Container

No

Yes

accountName

Azure Account Name

No

Yes

accountKey

Azure Account Key

No

Yes

sas_token

Azure SAS Token

No

No

5.4.4.5. Google Cloud storage

The following is an example for configuring the registry to make use of Blob storage on the Google Cloud Platform.

apiVersion: redhatcop.redhat.io/v1alpha1azure
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    registryBackends:
      - name: googleCloud
        googleCloud:
        accessKey: <accessKey>
        secretKey: <secretKey>
        bucketName: <bucketName>

The following is a comprehensive list of properties for the googlecloud registry backend:

Expand

Property

Description

Credential Secret Supported

Required

storagePath

Storage Directory

No

No

accessKey

Cloud Access Key

Yes

Yes

secretKey

Cloud Secret Key

Yes

Yes

bucketName

GCS Bucket

No

Yes

5.4.4.6. NooBaa (RHOCS) storage

The following is an example for configuring the registry to make use of NooBaa (Red Hat OpenShift Container Storage) storage.

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    registryBackends:
      - name: rhocs
        rhocs:
          hostname: <hostname>
          secure: <secure>
          accessKey: <accessKey>
          secretKey: <secretKey>
          bucketName: <bucketName>

The following is a comprehensive list of properties for the rhocs registry backend:

Expand

Property

Description

Credential Secret Supported

Required

storagePath

Storage Directory

No

No

hostname

NooBaa Server Hostname

No

Yes

port

Custom Port

No

No

secure

Is Secure

No

No

secretKey

Secret Key

Yes

Yes

bucketName

Bucket Name

No

Yes

5.4.4.7. RADOS storage

The following is an example for configuring the registry to make use of RADOS storage.

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    registryBackends:
      - name: rados
        rados:
          hostname: <hostname>
          secure: <is_secure>
          accessKey: <accessKey>
          secretKey: <secretKey>
          bucketName: <bucketName>

The following is a comprehensive list of properties for the rados registry backend:

Expand

Property

Description

Credential Secret Supported

Required

storagePath

Storage Directory

No

No

hostname

Rados Server Hostname

No

Yes

port

Custom Port

No

No

secure

Is Secure

No

No

accessKey

Access Key

Yes

Yes

secretKey

Secret Key

Yes

Yes

bucketName

Bucket Name

No

Yes

5.4.4.8. Swift (OpenStack) storage

The following is an example for configuring the registry to make use of Swift storage.

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    registryBackends:
      - name: swift
        swift:
          authVersion: <authVersion>
          authURL: <authURL>
          container: <container>
          user: <user>
          password: <password>
          caCertPath: <caCertPath>
          osOptions:
            object_storage_url: <object_storage_url>
            user_domain_name: <user_domain_name>
            project_id: <project_id>

The following is a comprehensive list of properties for the swift registry backend:

Expand

Property

Description

Credential Secret Supported

Required

storagePath

Storage Directory

No

No

authVersion

Swift Auth Version

No

Yes

authURL

Swift Auth URL

No

Yes

container

Swift Container Name

No

Yes

user

Username

Yes

Yes

password

Key/Password

Yes

Yes

caCertPath

CA Cert Filename

No

No

tempURLKey

Temp URL Key

No

No

osOptions

OS Options

Yes

Yes

5.4.4.9. CloudFront (S3) storage

The following is an example for configuring the registry to make use of S3 storage on Amazon Web Services.

Note

CloudFront configuration cannot currently be configured using the CR, due to a known issue. You can, however, manage it through the Red Hat Quay Config Tool.

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    registryBackends:
      - name: s3
        s3:
          accessKey: <accessKey>
          bucketName: <bucketName>
          secretKey: <secretKey>
          host: <host>
          distributionDomain: <distributionDomain>
          key_ID: <key_ID>
          privateKeyFilename: <privateKeyFilename>

The following is a comprehensive list of properties for the cloudfrontS3 registry backend:

Expand

Property

Description

Credential Secret Supported

Required

storagePath

Storage Directory

No

No

bucketName

S3 Bucket

No

Yes

accessKey

AWS Access Key

Yes

Yes

secretKey

AWS Secret Key

Yes

Yes

host

S3 Host

No

No

port

S3 Port

No

No

distributionDomain

CloudFront Distribution Domain Name

No

Yes

keyID

CloudFront Key ID

No

Yes

privateKeyFilename

CloudFront Private Key

No

Yes

5.5. Repository mirroring

Red Hat Quay provides the capability to create container image repositories that exactly match the content of external registries. This functionality can be enabled by setting the enableRepoMirroring: true as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    enableRepoMirroring: true

The following additional options are also available:

  • repoMirrorTLSVerify - Require HTTPS and verify certificates of Quay registry during mirror
  • repoMirrorServerHostname - URL for use by the skopeo copy command
  • repoMirrorEnvVars - Environment variables to be applied to the repository mirror container
  • repoMirrorResources - Compute resources to be applied to the repository mirror container

5.6. Injecting configuration files

Files related to the configuration of Red Hat Quay and Clair can be provided to be injected at runtime. Common examples include certificates, private keys and configuration files. The Quay Operator supports the injection of these assets within the configFiles property in the quay or clair property of the QuayEcosystem object where one or more assets can be specified.

Two types of configuration files can be specified by the type property:

  • config: Configuration files
  • extraCaCert: Certificates to be trusted by the quay container

The following table illustrates the location for which configFiles are injected:

Expand

Component

Type

Injection Location

Quay

config

Mounted within the /conf/stack directory in Quay components

Quay

extraCaCert

Added to the quay-enterprise-config-secret which is automatically processed as an additional CA certificate

Clair

config

Added to the /clair/config directory

Clair

extraCaCert

Added to the /etc/pki/ca-trust/source/anchors directory

Configuration files are stored as values within Secrets. The following describes several of the ways that this feature can be leveraged.

The first step is to create a secret containing these files. The following command illustrates how a private key can be added:

$ oc create secret generic quayconfigfile --from-file=<path_to_file>

With the secret created, the secret containing the configuration file can be referenced in the QuayEcosystem object as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    configFiles:
      - secretName: quayconfigfile

By default, the config type is assumed. If the contents of the secret contains certificates that should be added as a trusted certificate, specify the type as extraCaCert as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    configFiles:
      - secretName: quayconfigfile
        type: extraCaCert

Individual keys within a secret can be referenced to fine tune the resources that are added to the configuration using the files property as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    configFiles:
      - secretName: quayconfigfile
        files:
          - key: myprivatekey.pem
            filename: cloudfront.pem
          - key: myExtraCaCert.crt
            type: extraCaCert

The example above assumes that two files have been added to a secret called quayconfigfile. The file myprivatekey.pem that was added to the secret will be mounted in the quay pod at the path /conf/stack/cloudfront.pem since it is a config file type and specifies a custom filename that should be projected into the pod. The myExtraCaCert.crt file will be added to the Quay pod within at the path /conf/stack/extra_certs/myExtraCert.crt

Note

The type property within files property overrides the value in the configFiles property.

5.7. Skipping automated setup

The operator by default is configured to complete the automated setup process for Red Hat Quay. This can be bypassed by setting the skipSetup field to true as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    skipSetup: true

5.8. Methods for external access

Support is available to access Quay through a number of OpenShift and Kubernetes mechanisms for ingress. When running on OpenShift, a Route is used while a LoadBalancer Service and Ingress is used.

All of the properties for defining the configuration for external access can be managed within the externalAccess property. The type of external access can be specified by setting the type property within externalAccess using one of the available options in the table below:

Expand

External Access Type

Description

Notes

Route

OpenShift Route

Can only be specified when running in OpenShift

LoadBalancer

LoadBalancer Service

 

NodePort

NodePort Service

A dns based hostname or IP address must be specified using the hostname property of the quay resource

Ingress

Ingress

Kubernetes native solution for external access

An example of how to specify the type is shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    externalAccess:
      type: LoadBalancer

5.8.1. NodePorts

By default, NodePort type Services are allocated a randomly assigned network port between 30000-32767. To support a predictive allocation of resources, the NodePort services for Quay and Quay Config can be define using the nodePort as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    externalAccess:
      type: NodePort
      nodePort: 30100
      hostname: quay.example.com

The hostname field must be specified to refer to the location (DNS or IP) for which the Quay server will be available. The port number allocated to tke service will be added automatically as necessary.

5.8.2. Ingress

Ingress makes use of a similar concept as an OpenShift route, but requires a separate deployment of an ingress controller that manages external traffic. There are a variety of ingress controllers that can be used and implementation specific properties are typically defined through the use of annotations on the ingress resource.

The following is an example of how to define an Ingress type of External Access using annotations specific for an Nginx controller:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    externalAccess:
      type: Ingress
      annotations:
        nginx.ingress.kubernetes.io/ssl-passthrough: "true"
        nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
      hostname: quay.example.com

Annotations can also be applied for the Config ingress by using the configAnnotations property

The hostname field must be specified to refer to the location for which the Quay server will be available.

5.9. Specifying the Red Hat Quay route

Red Hat Quay makes use of an OpenShift route to enable ingress. The hostname for this route is automatically generated as per the configuration of the OpenShift cluster. Alternatively, the hostname for this route can be explicitly specified using the hostname property under the externalAccess field as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    externalAccess:
      hostname: example-quayecosystem-quay-quay-enterprise.apps.openshift.example.com

During the development process, you may want to test the provisioning and setup of your Red Hat Quay server. By default, the operator will use the internal service to communicate with the configuration pod. However, when running external to the cluster, you will need to specify the hostname location that the setup process can use.

Specify the configHostname as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    externalAccess:
      configHostname: example-quayecosystem-quay-config-quay-enterprise.apps.openshift.example.com

5.11. Providing SSL certificates

Red Hat Quay, as a secure registry, makes use of SSL certificates to secure communication between the various components within the ecosystem. Transport to the Quay user interface and container registry is secured via SSL certificates. These certificates are generated at startup with the OpenShift route being configured with a TLS termination type of Passthrough.

5.11.1. User-provided certificates

SSL certificates can be provided and used instead of having the operator generate certificates. Certificates can be provided in a secret which is then referenced in the QuayEcosystem custom resource.

Create a secret containing the certificate and private key:

oc create secret tls custom-quay-ssl \
   --key=<ssl_private_key> --cert<ssl_certificate>

The secret containing the certificates are referenced using the secretName underneath a property called tls as defined within the externalAccess property as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    externalAccess:
      tls:
        secretName: custom-quay-ssl
        termination: passthrough

5.12. TLS Termination

Red Hat Quay can be configured to protect connections using SSL certificates. By default, SSL communication is terminated within Red Hat Quay. There are several different ways that SSL termination can be configured including omitting the use of certificates altogether. TLS termination is determined by the termination property as shown below:

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
  name: example-quayecosystem
spec:
  quay:
    externalAccess:
      tls:
        termination: passthrough

The example above is the default configuration applied to Red Hat Quay. Alternate options are available as described in the table below:

Expand

TLS Termination Type

Description

Notes

passthrough

SSL communication is terminated at Quay

Default configuration

edge

SSL communication is terminated prior to reaching Quay. Traffic reaching quay is not encrypted (HTTP)

 

none

All communication is unencrypted

 
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

© 2026 Red Hat
Back to top