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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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.
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 Copy linkLink copied to clipboard!
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>
5.2. Providing persistent storage using PostgreSQL database Copy linkLink copied to clipboard!
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:
| Property | Description |
| image | Location of the database image |
| volumeSize | Size of the volume in Kubernetes capacity units |
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 Copy linkLink copied to clipboard!
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>
5.3.1. Using an existing PostgreSQL database instance Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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:
| Property | Description | Credential Secret Supported | Required |
| storagePath | Storage Directory | No | No |
5.4.4.2. Configuring persistent local storage Copy linkLink copied to clipboard!
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) Copy linkLink copied to clipboard!
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:
| 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 Copy linkLink copied to clipboard!
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:
| 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 Copy linkLink copied to clipboard!
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:
| 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 Copy linkLink copied to clipboard!
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:
| 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 Copy linkLink copied to clipboard!
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:
| 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 Copy linkLink copied to clipboard!
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:
| 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 Copy linkLink copied to clipboard!
The following is an example for configuring the registry to make use of S3 storage on Amazon Web Services.
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:
| 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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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:
| Component | Type | Injection Location |
| Quay |
|
Mounted within the |
| Quay |
|
Added to the |
| Clair |
|
Added to the |
| Clair |
|
Added to the |
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
The type property within files property overrides the value in the configFiles property.
5.7. Skipping automated setup Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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:
| External Access Type | Description | Notes |
|
| Can only be specified when running in OpenShift | |
|
| ||
|
|
A dns based hostname or IP address must be specified using the | |
|
| 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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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
5.10. Specifying a Red Hat Quay configuration route Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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:
| 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 |