Chapter 3. Configuration fields
This section describes the both required and optional configuration fields when deploying Red Hat Quay.
3.1. Required configuration fields
The fields required to configure Red Hat Quay are covered in the following sections:
- General required fields
- link::https://access.redhat.com/documentation/en-us/red_hat_quay/3.9/html-single/configure_red_hat_quay/index#config-fields-storage[Storage for images]
- Database for metadata
- Redis for build logs and user events
- Tag expiration options
3.2. Automation options
The following sections describe the available automation options for Red Hat Quay deployments:
3.3. Optional configuration fields
Optional fields for Red Hat Quay can be found in the following sections:
- Basic configuration
- SSL
- LDAP
- Repository mirroring
- Quota management
- Security scanner
- Helm
- Action log
- Build logs
- Dockerfile build
- OAuth
- Configuring nested repositories
- Adding other OCI media types to Quay
- User
- Recaptcha
- ACI
- JWT
- App tokens
- Miscellaneous
- User interface v2
- IPv6 configuration field
- Legacy options
3.4. General required fields
The following table describes the required configuration fields for a Red Hat Quay deployment:
Field | Type | Description |
---|---|---|
AUTHENTICATION_TYPE | String |
The authentication engine to use for credential authentication. |
PREFERRED_URL_SCHEME | String |
The URL scheme to use when accessing Red Hat Quay. |
SERVER_HOSTNAME | String |
The URL at which Red Hat Quay is accessible, without the scheme. |
DATABASE_SECRET_KEY | String | Key used to encrypt sensitive fields within the database. This value should never be changed once set, otherwise all reliant fields, for example, repository mirror username and password configurations, are invalidated. |
SECRET_KEY | String | Key used to encrypt sensitive fields within the database and at run time. This value should never be changed once set, otherwise all reliant fields, for example, encrypted password credentials, are invalidated. |
SETUP_COMPLETE | Boolean |
This is an artefact left over from earlier versions of the software and currently it must be specified with a value of |
3.5. Database configuration
This section describes the database configuration fields available for Red Hat Quay deployments.
3.5.1. Database URI
With Red Hat Quay, connection to the database is configured by using the required DB_URI
field.
The following table describes the DB_URI
configuration field:
Field | Type | Description |
---|---|---|
DB_URI | String | The URI for accessing the database, including any credentials.
Example postgresql://quayuser:quaypass@quay-server.example.com:5432/quay |
3.5.2. Database connection arguments
Optional connection arguments are configured by the DB_CONNECTION_ARGS
parameter. Some of the key-value pairs defined under DB_CONNECTION_ARGS
are generic, while others are database specific.
The following table describes database connection arguments:
Field | Type | Description |
---|---|---|
DB_CONNECTION_ARGS | Object | Optional connection arguments for the database, such as timeouts and SSL/TLS. |
.autorollback | Boolean |
Whether to use thread-local connections. |
.threadlocals | Boolean |
Whether to use auto-rollback connections. |
3.5.2.1. PostgreSQL SSL/TLS connection arguments
With SSL/TLS, configuration depends on the database you are deploying. The following example shows a PostgreSQL SSL/TLS configuration:
DB_CONNECTION_ARGS: sslmode: verify-ca sslrootcert: /path/to/cacert
The sslmode
option determines whether, or with, what priority a secure SSL/TLS TCP/IP connection will be negotiated with the server. There are six modes:
Mode | Description |
---|---|
disable | Your configuration only tries non-SSL/TLS connections. |
allow | Your configuration first tries a non-SSL/TLS connection. Upon failure, tries an SSL/TLS connection. |
prefer | Your configuration first tries an SSL/TLS connection. Upon failure, tries a non-SSL/TLS connection. |
require | Your configuration only tries an SSL/TLS connection. If a root CA file is present, it verifies the certificate in the same way as if verify-ca was specified. |
verify-ca | Your configuration only tries an SSL/TLS connection, and verifies that the server certificate is issued by a trusted certificate authority (CA). |
verify-full | Only tries an SSL/TLS connection, and verifies that the server certificate is issued by a trusted CA and that the requested server hostname matches that in the certificate. |
For more information on the valid arguments for PostgreSQL, see Database Connection Control Functions.
3.5.2.2. MySQL SSL/TLS connection arguments
The following example shows a sample MySQL SSL/TLS configuration:
DB_CONNECTION_ARGS: ssl: ca: /path/to/cacert
Information on the valid connection arguments for MySQL is available at Connecting to the Server Using URI-Like Strings or Key-Value Pairs.
3.6. Image storage
This section details the image storage features and configuration fields that are available with Red Hat Quay.
3.6.1. Image storage features
The following table describes the image storage features for Red Hat Quay:
Field | Type | Description |
---|---|---|
FEATURE_REPO_MIRROR | Boolean |
If set to true, enables repository mirroring. |
FEATURE_PROXY_STORAGE | Boolean |
Whether to proxy all direct download URLs in storage through NGINX. |
FEATURE_STORAGE_REPLICATION | Boolean |
Whether to automatically replicate between storage engines. |
3.6.2. Image storage configuration fields
The following table describes the image storage configuration fields for Red Hat Quay:
Field | Type | Description |
---|---|---|
DISTRIBUTED_STORAGE_CONFIG | Object |
Configuration for storage engine(s) to use in Red Hat Quay. Each key represents an unique identifier for a storage engine. The value consists of a tuple of (key, value) forming an object describing the storage engine parameters. |
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS | Array of string |
The list of storage engine(s) (by ID in |
DISTRIBUTED_STORAGE_PREFERENCE | Array of string |
The preferred storage engine(s) (by ID in |
MAXIMUM_LAYER_SIZE | String |
Maximum allowed size of an image layer. |
3.6.3. Local storage
The following YAML shows a sample configuration using local storage:
DISTRIBUTED_STORAGE_CONFIG: default: - LocalStorage - storage_path: /datastorage/registry DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: [] DISTRIBUTED_STORAGE_PREFERENCE: - default
3.6.4. OCS/NooBaa
The following YAML shows a sample configuration using an Open Container Storage/NooBaa instance:
DISTRIBUTED_STORAGE_CONFIG: rhocsStorage: - RHOCSStorage - access_key: access_key_here secret_key: secret_key_here bucket_name: quay-datastore-9b2108a3-29f5-43f2-a9d5-2872174f9a56 hostname: s3.openshift-storage.svc.cluster.local is_secure: 'true' port: '443' storage_path: /datastorage/registry
3.6.5. Ceph/RadosGW storage
The following examples show two possible YAML configurations when using Ceph/RadosGW.
Example A: Using RadosGW with the radosGWStorage driver
DISTRIBUTED_STORAGE_CONFIG: radosGWStorage: - RadosGWStorage - access_key: <access_key_here> secret_key: <secret_key_here> bucket_name: <bucket_name_here> hostname: <hostname_here> is_secure: true port: '443' storage_path: /datastorage/registry
Example B: Using RadosGW with general s3 access
DISTRIBUTED_STORAGE_CONFIG:
s3Storage: 1
- RadosGWStorage
- access_key: <access_key_here>
bucket_name: <bucket_name_here>
hostname: <hostname_here>
is_secure: true
secret_key: <secret_key_here>
storage_path: /datastorage/registry
- 1
- Used for general s3 access. Note that general s3 access is not strictly limited to Amazon Web Services (AWS) 3, and can be used with RadosGW or other storage services. For an example of general s3 access using the AWS S3 driver, see "AWS S3 storage".
3.6.6. AWS S3 storage
The following YAML shows a sample configuration using AWS S3 storage.
DISTRIBUTED_STORAGE_CONFIG:
default:
- S3Storage 1
- host: s3.us-east-2.amazonaws.com
s3_access_key: ABCDEFGHIJKLMN
s3_secret_key: OL3ABCDEFGHIJKLMN
s3_bucket: quay_bucket
storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
- s3Storage
- 1
- The
S3Storage
storage driver should only be used for AWS S3 buckets. Note that this differs from general S3 access, where the RadosGW driver or other storage services can be used. For an example, see "Example B: Using RadosGW with general S3 access".
3.6.7. Google Cloud Storage
The following YAML shows a sample configuration using Google Cloud Storage:
DISTRIBUTED_STORAGE_CONFIG: googleCloudStorage: - GoogleCloudStorage - access_key: GOOGQIMFB3ABCDEFGHIJKLMN bucket_name: quay-bucket secret_key: FhDAYe2HeuAKfvZCAGyOioNaaRABCDEFGHIJKLMN storage_path: /datastorage/registry DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: [] DISTRIBUTED_STORAGE_PREFERENCE: - googleCloudStorage
3.6.8. Azure Storage
The following YAML shows a sample configuration using Azure Storage:
DISTRIBUTED_STORAGE_CONFIG:
azureStorage:
- AzureStorage
- azure_account_name: azure_account_name_here
azure_container: azure_container_here
storage_path: /datastorage/registry
azure_account_key: azure_account_key_here
sas_token: some/path/
endpoint_url: https://[account-name].blob.core.usgovcloudapi.net 1
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
- azureStorage
- 1
- The
endpoint_url
parameter for Azure storage is optional and can be used with Microsoft Azure Government (MAG) endpoints. If left blank, theendpoint_url
will connect to the normal Azure region.As of Red Hat Quay 3.7, you must use the Primary endpoint of your MAG Blob service. Using the Secondary endpoint of your MAG Blob service will result in the following error:
AuthenticationErrorDetail:Cannot find the claimed account when trying to GetProperties for the account whusc8-secondary
.
3.6.9. Swift storage
The following YAML shows a sample configuration using Swift storage:
DISTRIBUTED_STORAGE_CONFIG: swiftStorage: - SwiftStorage - swift_user: swift_user_here swift_password: swift_password_here swift_container: swift_container_here auth_url: https://example.org/swift/v1/quay auth_version: 1 ca_cert_path: /conf/stack/swift.cert" storage_path: /datastorage/registry DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: [] DISTRIBUTED_STORAGE_PREFERENCE: - swiftStorage
3.6.10. Nutanix object storage
The following YAML shows a sample configuration using Nutanix object storage.
DISTRIBUTED_STORAGE_CONFIG: nutanixStorage: #storage config name - RadosGWStorage #actual driver - access_key: access_key_here #parameters secret_key: secret_key_here bucket_name: bucket_name_here hostname: hostname_here is_secure: 'true' port: '443' storage_path: /datastorage/registry DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: [] DISTRIBUTED_STORAGE_PREFERENCE: #must contain name of the storage config - nutanixStorage
3.7. Redis configuration fields
This section details the configuration fields available for Redis deployments.
3.7.1. Build logs
The following build logs configuration fields are available for Redis deployments:
Field | Type | Description |
---|---|---|
BUILDLOGS_REDIS | Object | Redis connection details for build logs caching. |
.host | String |
The hostname at which Redis is accessible. |
.port | Number |
The port at which Redis is accessible. |
.password | String |
The password to connect to the Redis instance. |
.ssl | Boolean | Whether to enable TLS communication between Redis and Quay. Defaults to false. |
3.7.2. User events
The following user event fields are available for Redis deployments:
Field | Type | Description |
---|---|---|
USER_EVENTS_REDIS | Object | Redis connection details for user event handling. |
.host | String |
The hostname at which Redis is accessible. |
.port | Number |
The port at which Redis is accessible. |
.password | String |
The password to connect to the Redis instance. |
.ssl | Boolean | Whether to enable TLS communication between Redis and Quay. Defaults to false. |
.ssl_keyfile | String |
The name of the key database file, which houses the client certificate to be used. |
.ssl_certfile | String |
Used for specifying the file path of the SSL certificate. |
.ssl_cert_reqs | String |
Used to specify the level of certificate validation to be performed during the SSL/TLS handshake. |
.ssl_ca_certs | String |
Used to specify the path to a file containing a list of trusted Certificate Authority (CA) certificates. |
.ssl_ca_data | String |
Used to specify a string containing the trusted CA certificates in PEM format. |
.ssl_check_hostname | Boolean |
Used when setting up an SSL/TLS connection to a server. It specifies whether the client should check that the hostname in the server’s SSL/TLS certificate matches the hostname of the server it is connecting to. |
3.7.3. Example Redis configuration
The following YAML shows a sample configuration using Redis with optional SSL/TLS fields:
BUILDLOGS_REDIS: host: quay-server.example.com password: strongpassword port: 6379 ssl: true USER_EVENTS_REDIS: host: quay-server.example.com password: strongpassword port: 6379 ssl: true ssl_*: <path_location_or_certificate>
If your deployment uses Azure Cache for Redis and ssl
is set to true
, the port defaults to 6380
.
3.8. ModelCache configuration options
The following options are available on Red Hat Quay for configuring ModelCache.
3.8.1. Memcache configuration option
Memcache is the default ModelCache configuration option. With Memcache, no additional configuration is necessary.
3.8.2. Single Redis configuration option
The following configuration is for a single Redis instance with optional read-only replicas:
DATA_MODEL_CACHE_CONFIG: engine: redis redis_config: primary: host: <host> port: <port> password: <password if ssl is true> ssl: <true | false > replica: host: <host> port: <port> password: <password if ssl is true> ssl: <true | false >
3.8.3. Clustered Redis configuration option
Use the following configuration for a clustered Redis instance:
DATA_MODEL_CACHE_CONFIG: engine: rediscluster redis_config: startup_nodes: - host: <cluster-host> port: <port> password: <password if ssl: true> read_from_replicas: <true|false> skip_full_coverage_check: <true | false> ssl: <true | false >
3.9. Tag expiration configuration fields
The following tag expiration configuration fields are available with Red Hat Quay:
Field | Type | Description |
---|---|---|
FEATURE_GARBAGE_COLLECTION | Boolean |
Whether garbage collection of repositories is enabled. |
TAG_EXPIRATION_OPTIONS | Array of string |
If enabled, the options that users can select for expiration of tags in their namespace. |
DEFAULT_TAG_EXPIRATION | String |
The default, configurable tag expiration time for time machine. |
FEATURE_CHANGE_TAG_EXPIRATION | Boolean |
Whether users and organizations are allowed to change the tag expiration for tags in their namespace. |
3.9.1. Example tag expiration configuration
The following YAML shows a sample tag expiration configuration:
DEFAULT_TAG_EXPIRATION: 2w TAG_EXPIRATION_OPTIONS: - 0s - 1d - 1w - 2w - 4w
3.10. Quota management configuration fields
Field | Type | Description |
---|---|---|
FEATURE_QUOTA_MANAGEMENT | Boolean | Enables configuration, caching, and validation for quota management feature. **Default:** `False` |
DEFAULT_SYSTEM_REJECT_QUOTA_BYTES | String | Enables system default quota reject byte allowance for all organizations. By default, no limit is set. |
QUOTA_BACKFILL | Boolean | Enables the quota backfill worker to calculate the size of pre-existing blobs.
Default: |
QUOTA_TOTAL_DELAY_SECONDS | String | The time delay for starting the quota backfill. Rolling deployments can cause incorrect totals. This field must be set to a time longer than it takes for the rolling deployment to complete.
Default: |
PERMANENTLY_DELETE_TAGS | Boolean | Enables functionality related to the removal of tags from the time machine window.
Default: |
RESET_CHILD_MANIFEST_EXPIRATION | Boolean |
Resets the expirations of temporary tags targeting the child manifests. With this feature set to
Default: |
3.10.1. Example quota management configuration
The following YAML is the suggested configuration when enabling quota management.
Quota management YAML configuration
FEATURE_QUOTA_MANAGEMENT: true FEATURE_GARBAGE_COLLECTION: true PERMANENTLY_DELETE_TAGS: true QUOTA_TOTAL_DELAY_SECONDS: 1800 RESET_CHILD_MANIFEST_EXPIRATION: true
3.11. Proxy cache configuration fields
Field | Type | Description |
---|---|---|
FEATURE_PROXY_CACHE | Boolean | Enables Red Hat Quay to act as a pull through cache for upstream registries.
Default: |
3.12. Pre-configuring Red Hat Quay for automation
Red Hat Quay supports several configuration options that enable automation. Users can configure these options before deployment to reduce the need for interaction with the user interface.
3.12.1. Allowing the API to create the first user
To create the first user, users need to set the FEATURE_USER_INITIALIZE parameter to true and call the /api/v1/user/initialize API. Unlike all other registry API calls that require an OAuth token generated by an OAuth application in an existing organization, the API endpoint does not require authentication.
Users can use the API to create a user such as quayadmin
after deploying Red Hat Quay, provided no other users have been created. For more information, see Using the API to create the first user.
3.12.2. Enabling general API access
Users should set the BROWSER_API_CALLS_XHR_ONLY config option to false to allow general access to the Red Hat Quay registry API.
3.12.3. Adding a superuser
After deploying Red Hat Quay, users can create a user and give the first user administrator privileges with full permissions. Users can configure full permissions in advance by using the SUPER_USER configuration object. For example:
... SERVER_HOSTNAME: quay-server.example.com SETUP_COMPLETE: true SUPER_USERS: - quayadmin ...
3.12.4. Restricting user creation
After you have configured a superuser, you can restrict the ability to create new users to the superuser group by setting the FEATURE_USER_CREATION
to false
. For example:
... FEATURE_USER_INITIALIZE: true BROWSER_API_CALLS_XHR_ONLY: false SUPER_USERS: - quayadmin FEATURE_USER_CREATION: false ...
3.12.5. Enabling new functionality in Red Hat Quay 3.8
To use new Red Hat Quay 3.8 functions, enable some or all of the following features:
... FEATURE_UI_V2: true FEATURE_LISTEN_IP_VERSION: FEATURE_SUPERUSERS_FULL_ACCESS: true GLOBAL_READONLY_SUPER_USERS: - FEATURE_RESTRICTED_USERS: true RESTRICTED_USERS_WHITELIST: - ...
3.12.6. Enabling new functionality in Red Hat Quay 3.7
To use new Red Hat Quay 3.7 functions, enable some or all of the following features:
... FEATURE_QUOTA_MANAGEMENT: true FEATURE_BUILD_SUPPORT: true FEATURE_PROXY_CACHE: true FEATURE_STORAGE_REPLICATION: true DEFAULT_SYSTEM_REJECT_QUOTA_BYTES: 102400000 ...
3.12.7. Suggested configuration for automation
The following config.yaml
parameters are suggested for automation:
... FEATURE_USER_INITIALIZE: true BROWSER_API_CALLS_XHR_ONLY: false SUPER_USERS: - quayadmin FEATURE_USER_CREATION: false ...
3.12.8. Deploying the Red Hat Quay Operator using the initial configuration
Use the following procedure to deploy Red Hat Quay on OpenShift Container Platform using the initial configuration.
Prerequisites
-
You have installed the
oc
CLI.
Procedure
Create a secret using the configuration file:
$ oc create secret generic -n quay-enterprise --from-file config.yaml=./config.yaml init-config-bundle-secret
Create a
quayregistry.yaml
file. Identify the unmanaged components and reference the created secret, for example:apiVersion: quay.redhat.com/v1 kind: QuayRegistry metadata: name: example-registry namespace: quay-enterprise spec: configBundleSecret: init-config-bundle-secret
Deploy the Red Hat Quay registry:
$ oc create -n quay-enterprise -f quayregistry.yaml
Next Steps
3.12.8.1. Using the API to create the first user
Use the following procedure to create the first user in your Red Hat Quay organization.
Prerequisites
-
The config option
FEATURE_USER_INITIALIZE
must be set totrue
. - No users can already exist in the database.
This procedure requests an OAuth token by specifying "access_token": true
.
As the root user, install
python39
by entering the following command:$ sudo yum install python39
Upgrade the
pip
package manager for Python 3.9:$ python3.9 -m pip install --upgrade pip
Use the
pip
package manager to install thebcrypt
package:$ pip install bcrypt
Generate a secure, hashed password using the
bcrypt
package in Python 3.9 by entering the following command:$ python3.9 -c 'import bcrypt; print(bcrypt.hashpw(b"subquay12345", bcrypt.gensalt(12)).decode("utf-8"))'
Open your Red Hat Quay configuration file and update the following configuration fields:
FEATURE_USER_INITIALIZE: true SUPER_USERS: - quayadmin
Stop the Red Hat Quay service by entering the following command:
$ sudo podman stop quay
Start the Red Hat Quay service by entering the following command:
$ sudo podman run -d -p 80:8080 -p 443:8443 --name=quay -v $QUAY/config:/conf/stack:Z -v $QUAY/storage:/datastorage:Z {productrepo}/{quayimage}:{productminv}
Run the following
CURL
command to generate a new user with a username, password, email, and access token:$ curl -X POST -k http://quay-server.example.com/api/v1/user/initialize --header 'Content-Type: application/json' --data '{ "username": "quayadmin", "password":"quaypass12345", "email": "quayadmin@example.com", "access_token": true}'
If successful, the command returns an object with the username, email, and encrypted password. For example:
{"access_token":"6B4QTRSTSD1HMIG915VPX7BMEZBVB9GPNY2FC2ED", "email":"quayadmin@example.com","encrypted_password":"1nZMLH57RIE5UGdL/yYpDOHLqiNCgimb6W9kfF8MjZ1xrfDpRyRs9NUnUuNuAitW","username":"quayadmin"} # gitleaks:allow
If a user already exists in the database, an error is returned:
{"message":"Cannot initialize user in a non-empty database"}
If your password is not at least eight characters or contains whitespace, an error is returned:
{"message":"Failed to initialize user: Invalid password, password must be at least 8 characters and contain no whitespace."}
Log in to your Red Hat Quay deployment by entering the following command:
$ sudo podman login -u quayadmin -p quaypass12345 http://quay-server.example.com --tls-verify=false
Example output
Login Succeeded!
3.12.8.2. Using the OAuth token
After invoking the API, you can call out the rest of the Red Hat Quay API by specifying the returned OAuth code.
Prerequisites
-
You have invoked the
/api/v1/user/initialize
API, and passed in the username, password, and email address.
Procedure
Obtain the list of current users by entering the following command:
$ curl -X GET -k -H "Authorization: Bearer 6B4QTRSTSD1HMIG915VPX7BMEZBVB9GPNY2FC2ED" https://example-registry-quay-quay-enterprise.apps.docs.quayteam.org/api/v1/superuser/users/
Example output:
{ "users": [ { "kind": "user", "name": "quayadmin", "username": "quayadmin", "email": "quayadmin@example.com", "verified": true, "avatar": { "name": "quayadmin", "hash": "3e82e9cbf62d25dec0ed1b4c66ca7c5d47ab9f1f271958298dea856fb26adc4c", "color": "#e7ba52", "kind": "user" }, "super_user": true, "enabled": true } ] }
In this instance, the details for the
quayadmin
user are returned as it is the only user that has been created so far.
3.12.8.3. Using the API to create an organization
The following procedure details how to use the API to create a Red Hat Quay organization.
Prerequisites
-
You have invoked the
/api/v1/user/initialize
API, and passed in the username, password, and email address. - You have called out the rest of the Red Hat Quay API by specifying the returned OAuth code.
Procedure
To create an organization, use a POST call to
api/v1/organization/
endpoint:$ curl -X POST -k --header 'Content-Type: application/json' -H "Authorization: Bearer 6B4QTRSTSD1HMIG915VPX7BMEZBVB9GPNY2FC2ED" https://example-registry-quay-quay-enterprise.apps.docs.quayteam.org/api/v1/organization/ --data '{"name": "testorg", "email": "testorg@example.com"}'
Example output:
"Created"
You can retrieve the details of the organization you created by entering the following command:
$ curl -X GET -k --header 'Content-Type: application/json' -H "Authorization: Bearer 6B4QTRSTSD1HMIG915VPX7BMEZBVB9GPNY2FC2ED" https://min-registry-quay-quay-enterprise.apps.docs.quayteam.org/api/v1/organization/testorg
Example output:
{ "name": "testorg", "email": "testorg@example.com", "avatar": { "name": "testorg", "hash": "5f113632ad532fc78215c9258a4fb60606d1fa386c91b141116a1317bf9c53c8", "color": "#a55194", "kind": "user" }, "is_admin": true, "is_member": true, "teams": { "owners": { "name": "owners", "description": "", "role": "admin", "avatar": { "name": "owners", "hash": "6f0e3a8c0eb46e8834b43b03374ece43a030621d92a7437beb48f871e90f8d90", "color": "#c7c7c7", "kind": "team" }, "can_view": true, "repo_count": 0, "member_count": 1, "is_synced": false } }, "ordered_teams": [ "owners" ], "invoice_email": false, "invoice_email_address": null, "tag_expiration_s": 1209600, "is_free_account": true }
3.13. Basic configuration fields
Field | Type | Description |
---|---|---|
REGISTRY_TITLE | String |
If specified, the long-form title for the registry. Displayed in frontend of your Red Hat Quay deployment, for example, at the sign in page of your organization. Should not exceed 35 characters. |
REGISTRY_TITLE_SHORT | String |
If specified, the short-form title for the registry. Title is displayed on various pages of your organization, for example, as the title of the tutorial on your organization’s Tutorial page. |
CONTACT_INFO | Array of String | If specified, contact information to display on the contact page. If only a single piece of contact information is specified, the contact footer will link directly. |
[0] | String |
Adds a link to send an e-mail. |
[1] | String |
Adds a link to visit an IRC chat room. |
[2] | String |
Adds a link to call a phone number.+ |
[3] | String |
Adds a link to a defined URL. |
3.14. SSL configuration fields
Field | Type | Description |
---|---|---|
PREFERRED_URL_SCHEME | String |
One of
+ Users must set their |
SERVER_HOSTNAME | String |
The URL at which Red Hat Quay is accessible, without the scheme |
SSL_CIPHERS | Array of String |
If specified, the nginx-defined list of SSL ciphers to enabled and disabled |
SSL_PROTOCOLS | Array of String |
If specified, nginx is configured to enabled a list of SSL protocols defined in the list. Removing an SSL protocol from the list disables the protocol during Red Hat Quay startup. |
SESSION_COOKIE_SECURE | Boolean |
Whether the |
3.14.1. Configuring SSL
Copy the certificate file and primary key file to your configuration directory, ensuring they are named
ssl.cert
andssl.key
respectively:$ cp ~/ssl.cert $QUAY/config $ cp ~/ssl.key $QUAY/config $ cd $QUAY/config
Edit the
config.yaml
file and specify that you want Quay to handle TLS:config.yaml
... SERVER_HOSTNAME: quay-server.example.com ... PREFERRED_URL_SCHEME: https ...
-
Stop the
Quay
container and restart the registry
3.15. Adding TLS Certificates to the Red Hat Quay Container
To add custom TLS certificates to Red Hat Quay, create a new directory named extra_ca_certs/
beneath the Red Hat Quay config directory. Copy any required site-specific TLS certificates to this new directory.
3.15.1. Add TLS certificates to Red Hat Quay
View certificate to be added to the container
$ cat storage.crt -----BEGIN CERTIFICATE----- MIIDTTCCAjWgAwIBAgIJAMVr9ngjJhzbMA0GCSqGSIb3DQEBCwUAMD0xCzAJBgNV [...] -----END CERTIFICATE-----
Create certs directory and copy certificate there
$ mkdir -p quay/config/extra_ca_certs $ cp storage.crt quay/config/extra_ca_certs/ $ tree quay/config/ ├── config.yaml ├── extra_ca_certs │ ├── storage.crt
Obtain the
Quay
container’sCONTAINER ID
withpodman ps
:$ sudo podman ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS 5a3e82c4a75f <registry>/<repo>/quay:v3.9.7 "/sbin/my_init" 24 hours ago Up 18 hours 0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 443/tcp grave_keller
Restart the container with that ID:
$ sudo podman restart 5a3e82c4a75f
Examine the certificate copied into the container namespace:
$ sudo podman exec -it 5a3e82c4a75f cat /etc/ssl/certs/storage.pem -----BEGIN CERTIFICATE----- MIIDTTCCAjWgAwIBAgIJAMVr9ngjJhzbMA0GCSqGSIb3DQEBCwUAMD0xCzAJBgNV
3.16. LDAP configuration fields
Field | Type | Description |
---|---|---|
AUTHENTICATION_TYPE | String |
Must be set to |
FEATURE_TEAM_SYNCING | Boolean |
Whether to allow for team membership to be synced from a backing group in the authentication engine (LDAP or Keystone). |
FEATURE_NONSUPERUSER_TEAM_SYNCING_SETUP | Boolean |
If enabled, non-superusers can setup syncing on teams using LDAP. |
LDAP_ADMIN_DN | String | The admin DN for LDAP authentication. |
LDAP_ADMIN_PASSWD | String | The admin password for LDAP authentication. |
LDAP_ALLOW_INSECURE_FALLBACK | Boolean | Whether or not to allow SSL insecure fallback for LDAP authentication. |
LDAP_BASE_DN | Array of String | The base DN for LDAP authentication. |
LDAP_EMAIL_ATTR | String | The email attribute for LDAP authentication. |
LDAP_UID_ATTR | String | The uid attribute for LDAP authentication. |
LDAP_URI | String | The LDAP URI. |
LDAP_USER_FILTER | String | The user filter for LDAP authentication. |
LDAP_USER_RDN | Array of String | The user RDN for LDAP authentication. |
TEAM_RESYNC_STALE_TIME | String |
If team syncing is enabled for a team, how often to check its membership and resync if necessary. |
LDAP_SUPERUSER_FILTER | String |
Subset of the With this field, administrators can add or remove superusers without having to update the Red Hat Quay configuration file and restart their deployment.
This field requires that your |
LDAP_RESTRICTED_USER_FILTER | String |
Subset of the
This field requires that your |
LDAP_TIMEOUT | Integer |
Determines the maximum time period. in seconds, allowed for establishing a connection to the Lightweight Directory Access Protocol (LDAP) server.
+ Default: |
LDAP_NETWORK_TIMEOUT | Integer |
Defines the maximum time duration, in seconds, that Red Hat Quay waits for a response from the Lightweight Directory Access Protocol (LDAP) server during network operations.
+ Default: |
3.16.1. LDAP configuration references
Use the following references to update your config.yaml
file with the desired configuration field.
3.16.1.1. Basic LDAP configuration
--- AUTHENTICATION_TYPE: LDAP --- LDAP_ADMIN_DN: uid=<name>,ou=Users,o=<organization_id>,dc=<example_domain_component>,dc=com LDAP_ADMIN_PASSWD: ABC123 LDAP_ALLOW_INSECURE_FALLBACK: false LDAP_BASE_DN: - o=<organization_id> - dc=<example_domain_component> - dc=com LDAP_EMAIL_ATTR: mail LDAP_UID_ATTR: uid LDAP_URI: ldaps://<ldap_url_domain_name> LDAP_USER_FILTER: (memberof=cn=developers,ou=Users,dc=<domain_name>,dc=com) LDAP_USER_RDN: - ou=<example_organization_unit> - o=<organization_id> - dc=<example_domain_component> - dc=com
3.16.1.2. LDAP restricted user configuration
--- AUTHENTICATION_TYPE: LDAP --- LDAP_ADMIN_DN: uid=<name>,ou=Users,o=<organization_id>,dc=<example_domain_component>,dc=com LDAP_ADMIN_PASSWD: ABC123 LDAP_ALLOW_INSECURE_FALLBACK: false LDAP_BASE_DN: - o=<organization_id> - dc=<example_domain_component> - dc=com LDAP_EMAIL_ATTR: mail LDAP_UID_ATTR: uid LDAP_URI: ldap://<example_url>.com LDAP_USER_FILTER: (memberof=cn=developers,ou=Users,o=<example_organization_unit>,dc=<example_domain_component>,dc=com) LDAP_RESTRICTED_USER_FILTER: (<filterField>=<value>) LDAP_USER_RDN: - ou=<example_organization_unit> - o=<organization_id> - dc=<example_domain_component> - dc=com ---
3.16.1.3. LDAP superuser configuration reference
--- AUTHENTICATION_TYPE: LDAP --- LDAP_ADMIN_DN: uid=<name>,ou=Users,o=<organization_id>,dc=<example_domain_component>,dc=com LDAP_ADMIN_PASSWD: ABC123 LDAP_ALLOW_INSECURE_FALLBACK: false LDAP_BASE_DN: - o=<organization_id> - dc=<example_domain_component> - dc=com LDAP_EMAIL_ATTR: mail LDAP_UID_ATTR: uid LDAP_URI: ldap://<example_url>.com LDAP_USER_FILTER: (memberof=cn=developers,ou=Users,o=<example_organization_unit>,dc=<example_domain_component>,dc=com) LDAP_SUPERUSER_FILTER: (<filterField>=<value>) LDAP_USER_RDN: - ou=<example_organization_unit> - o=<organization_id> - dc=<example_domain_component> - dc=com
3.17. Mirroring configuration fields
Field | Type | Description |
---|---|---|
FEATURE_REPO_MIRROR | Boolean |
Enable or disable repository mirroring |
REPO_MIRROR_INTERVAL | Number |
The number of seconds between checking for repository mirror candidates |
REPO_MIRROR_SERVER_HOSTNAME | String |
Replaces the |
REPO_MIRROR_TLS_VERIFY | Boolean |
Require HTTPS and verify certificates of Quay registry during mirror. |
REPO_MIRROR_ROLLBACK | Boolean |
When set to
Default: |
3.18. Security scanner configuration fields
Field | Type | Description |
---|---|---|
FEATURE_SECURITY_SCANNER | Boolean |
Enable or disable the security scanner |
FEATURE_SECURITY_NOTIFICATIONS | Boolean |
If the security scanner is enabled, turn on or turn off security notifications |
SECURITY_SCANNER_V4_REINDEX_THRESHOLD | String |
This parameter is used to determine the minimum time, in seconds, to wait before re-indexing a manifest that has either previously failed or has changed states since the last indexing. The data is calculated from the |
SECURITY_SCANNER_V4_ENDPOINT | String |
The endpoint for the V4 security scanner |
SECURITY_SCANNER_V4_PSK | String | The generated pre-shared key (PSK) for Clair |
SECURITY_SCANNER_ENDPOINT | String |
The endpoint for the V2 security scanner |
SECURITY_SCANNER_INDEXING_INTERVAL | Integer |
This parameter is used to determine the number of seconds between indexing intervals in the security scanner. When indexing is triggered, Red Hat Quay will query its database for manifests that must be indexed by Clair. These include manifests that have not yet been indexed and manifests that previously failed indexing. + Default: 30 |
FEATURE_SECURITY_SCANNER_NOTIFY_ON_NEW_INDEX | Boolean | Whether to allow sending notifications about vulnerabilities for new pushes.
+ Default*: |
3.18.1. Re-indexing with Clair v4
When Clair v4 indexes a manifest, the result should be deterministic. For example, the same manifest should produce the same index report. This is true until the scanners are changed, as using different scanners will produce different information relating to a specific manifest to be returned in the report. Because of this, Clair v4 exposes a state representation of the indexing engine (/indexer/api/v1/index_state
) to determine whether the scanner configuration has been changed.
Red Hat Quay leverages this index state by saving it to the index report when parsing to Quay’s database. If this state has changed since the manifest was previously scanned, Red Hat Quay will attempt to re-index that manifest during the periodic indexing process.
By default this parameter is set to 30 seconds. Users might decrease the time if they want the indexing process to run more frequently, for example, if they did not want to wait 30 seconds to see security scan results in the UI after pushing a new tag. Users can also change the parameter if they want more control over the request pattern to Clair and the pattern of database operations being performed on the Red Hat Quay database.
3.18.2. Example security scanner configuration
The following YAML is the suggested configuration when enabling the security scanner feature.
Security scanner YAML configuration
FEATURE_SECURITY_NOTIFICATIONS: true FEATURE_SECURITY_SCANNER: true FEATURE_SECURITY_SCANNER_NOTIFY_ON_NEW_INDEX: true ... SECURITY_SCANNER_INDEXING_INTERVAL: 30 SECURITY_SCANNER_V4_ENDPOINT: http://quay-server.example.com:8081 SECURITY_SCANNER_V4_PSK: MTU5YzA4Y2ZkNzJoMQ== SERVER_HOSTNAME: quay-server.example.com ...
3.19. Helm configuration fields
Field | Type | Description |
---|---|---|
FEATURE_GENERAL_OCI_SUPPORT | Boolean |
Enable support for OCI artifacts. |
The following Open Container Initiative (OCI) artifact types are built into Red Hat Quay by default and are enabled through the FEATURE_GENERAL_OCI_SUPPORT configuration field:
Field | Media Type | Supported content types |
---|---|---|
Helm |
|
|
Cosign |
|
|
SPDX |
|
|
Syft |
|
|
CycloneDX |
|
|
In-toto |
|
|
Unknown |
|
|
3.19.1. Configuring Helm
The following YAML is the example configuration when enabling Helm.
Helm YAML configuration
FEATURE_GENERAL_OCI_SUPPORT: true
3.20. Open Container Initiative configuration fields
Field | Type | Description |
---|---|---|
ALLOWED_OCI_ARTIFACT_TYPES | Object | The set of allowed OCI artifact mimetypes and the associated layer types. |
3.20.1. Configuring additional artifact types
Other OCI artifact types that are not supported by default can be added to your Red Hat Quay deployment by using the ALLOWED_OCI_ARTIFACT_TYPES
configuration field.
Use the following reference to add additional OCI artifact types:
OCI artifact types configuration
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>
For example, you can add Singularity (SIF) support by adding the following to your config.yaml
file:
Example OCI artifact type configuration
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
When adding OCI 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.
3.21. Unknown media types
Field | Type | Description |
---|---|---|
IGNORE_UNKNOWN_MEDIATYPES | Boolean | When enabled, allows a container registry platform to disregard specific restrictions on supported artifact types and accept any unrecognized or unknown media types.
Default: |
3.21.1. Configuring unknown media types
The following YAML is the example configuration when enabling unknown or unrecognized media types.
Unknown media types YAML configuration
IGNORE_UNKNOWN_MEDIATYPES: true
3.22. Action log configuration fields
3.22.1. Action log storage configuration
Field | Type | Description |
---|---|---|
FEATURE_LOG_EXPORT | Boolean |
Whether to allow exporting of action logs. |
LOGS_MODEL | String |
Specifies the preferred method for handling log data. |
LOGS_MODEL_CONFIG | Object | Logs model config for action logs. |
LOGS_MODEL_CONFIG [object]: Logs model config for action logs.
elasticsearch_config [object]: Elasticsearch cluster configuration.
access_key [string]: Elasticsearch user (or IAM key for AWS ES).
-
Example:
some_string
-
Example:
host [string]: Elasticsearch cluster endpoint.
-
Example:
host.elasticsearch.example
-
Example:
index_prefix [string]: Elasticsearch’s index prefix.
-
Example:
logentry_
-
Example:
- index_settings [object]: Elasticsearch’s index settings
use_ssl [boolean]: Use ssl for Elasticsearch. Defaults to
True
.-
Example:
True
-
Example:
secret_key [string]: Elasticsearch password (or IAM secret for AWS ES).
-
Example:
some_secret_string
-
Example:
aws_region [string]: Amazon web service region.
-
Example:
us-east-1
-
Example:
port [number]: Elasticsearch cluster endpoint port.
-
Example:
1234
-
Example:
kinesis_stream_config [object]: AWS Kinesis Stream configuration.
aws_secret_key [string]: AWS secret key.
-
Example:
some_secret_key
-
Example:
stream_name [string]: Kinesis stream to send action logs to.
-
Example:
logentry-kinesis-stream
-
Example:
aws_access_key [string]: AWS access key.
-
Example:
some_access_key
-
Example:
retries [number]: Max number of attempts made on a single request.
-
Example:
5
-
Example:
read_timeout [number]: Number of seconds before timeout when reading from a connection.
-
Example:
5
-
Example:
max_pool_connections [number]: The maximum number of connections to keep in a connection pool.
-
Example:
10
-
Example:
aws_region [string]: AWS region.
-
Example:
us-east-1
-
Example:
connect_timeout [number]: Number of seconds before timeout when attempting to make a connection.
-
Example:
5
-
Example:
producer [string]: Logs producer if logging to Elasticsearch.
- enum: kafka, elasticsearch, kinesis_stream
-
Example:
kafka
kafka_config [object]: Kafka cluster configuration.
topic [string]: Kafka topic to publish log entries to.
-
Example:
logentry
-
Example:
- bootstrap_servers [array]: List of Kafka brokers to bootstrap the client from.
max_block_seconds [number]: Max number of seconds to block during a
send()
, either because the buffer is full or metadata unavailable.-
Example:
10
-
Example:
-
producer [string]:
splunk
splunk_config [object]: Logs model configuration for Splunk action logs or the Splunk cluster configuration.
- host [string]: Splunk cluster endpoint.
- port [integer]: Splunk management cluster endpoint port.
- bearer_token [string]: The bearer token for Splunk.
-
verify_ssl [boolean]: Enable (
True
) or disable (False
) TLS/SSL verification for HTTPS connections. - index_prefix [string]: Splunk’s index prefix.
-
ssl_ca_path [string]: The relative container path to a single
.pem
file containing a certificate authority (CA) for SSL validation.
3.22.2. Action log rotation and archiving configuration
Field | Type | Description |
---|---|---|
FEATURE_ACTION_LOG_ROTATION | Boolean |
Enabling log rotation and archival will move all logs older than 30 days to storage. |
ACTION_LOG_ARCHIVE_LOCATION | String |
If action log archiving is enabled, the storage engine in which to place the archived data. |
ACTION_LOG_ARCHIVE_PATH | String |
If action log archiving is enabled, the path in storage in which to place the archived data. |
ACTION_LOG_ROTATION_THRESHOLD | String |
The time interval after which to rotate logs. |
3.22.3. Action log audit configuration
Field | Type | Description |
---|---|---|
ACTION_LOG_AUDIT_LOGINS | Boolean |
When set to |
3.23. Build logs configuration fields
Field | Type | Description |
---|---|---|
FEATURE_READER_BUILD_LOGS | Boolean |
If set to true, build logs can be read by those with |
LOG_ARCHIVE_LOCATION | String |
The storage location, defined in |
LOG_ARCHIVE_PATH | String |
The path under the configured storage engine in which to place the archived build logs in |
3.24. Dockerfile build triggers fields
Field | Type | Description |
---|---|---|
FEATURE_BUILD_SUPPORT | Boolean |
Whether to support Dockerfile build. |
SUCCESSIVE_TRIGGER_FAILURE_DISABLE_THRESHOLD | Number |
If not set to |
SUCCESSIVE_TRIGGER_INTERNAL_ERROR_DISABLE_THRESHOLD | Number |
If not set to |
3.24.1. GitHub build triggers
Field | Type | Description |
---|---|---|
FEATURE_GITHUB_BUILD | Boolean |
Whether to support GitHub build triggers. |
|
|
|
GITHUB_TRIGGER_CONFIG | Object | Configuration for using GitHub Enterprise for build triggers. |
.GITHUB_ENDPOINT | String |
The endpoint for GitHub Enterprise. |
.API_ENDPOINT | String |
The endpoint of the GitHub Enterprise API to use. Must be overridden for |
.CLIENT_ID | String |
The registered client ID for this Red Hat Quay instance; this cannot be shared with |
.CLIENT_SECRET | String | The registered client secret for this Red Hat Quay instance. |
3.24.2. BitBucket build triggers
Field | Type | Description |
---|---|---|
FEATURE_BITBUCKET_BUILD | Boolean |
Whether to support Bitbucket build triggers. |
|
|
|
BITBUCKET_TRIGGER_CONFIG | Object | Configuration for using BitBucket for build triggers. |
.CONSUMER_KEY | String | The registered consumer key (client ID) for this Red Hat Quay instance. |
.CONSUMER_SECRET | String | The registered consumer secret (client secret) for this Red Hat Quay instance. |
3.24.3. GitLab build triggers
Field | Type | Description |
---|---|---|
FEATURE_GITLAB_BUILD | Boolean |
Whether to support GitLab build triggers. |
|
|
|
GITLAB_TRIGGER_CONFIG | Object | Configuration for using Gitlab for build triggers. |
.GITLAB_ENDPOINT | String | The endpoint at which Gitlab Enterprise is running. |
.CLIENT_ID | String | The registered client ID for this Red Hat Quay instance. |
.CLIENT_SECRET | String | The registered client secret for this Red Hat Quay instance. |
3.25. Build manager configuration fields
Field | Type | Description |
---|---|---|
ALLOWED_WORKER_COUNT | String |
Defines how many Build Workers are instantiated per Red Hat Quay pod. Typically set to |
ORCHESTRATOR_PREFIX | String | Defines a unique prefix to be added to all Redis keys. This is useful to isolate Orchestrator values from other Redis keys. |
REDIS_HOST | Object | The hostname for your Redis service. |
REDIS_PASSWORD | String | The password to authenticate into your Redis service. |
REDIS_SSL | Boolean | Defines whether or not your Redis connection uses SSL/TLS. |
REDIS_SKIP_KEYSPACE_EVENT_SETUP | Boolean |
By default, Red Hat Quay does not set up the keyspace events required for key events at runtime. To do so, set |
EXECUTOR | String |
Starts a definition of an Executor of this type. Valid values are |
BUILDER_NAMESPACE | String | Kubernetes namespace where Red Hat Quay Builds will take place. |
K8S_API_SERVER | Object | Hostname for API Server of the OpenShift Container Platform cluster where Builds will take place. |
K8S_API_TLS_CA | Object |
The filepath in the |
KUBERNETES_DISTRIBUTION | String |
Indicates which type of Kubernetes is being used. Valid values are |
CONTAINER_* | Object |
Define the resource requests and limits for each |
NODE_SELECTOR_* | Object |
Defines the node selector label name-value pair where |
CONTAINER_RUNTIME | Object |
Specifies whether the Builder should run |
SERVICE_ACCOUNT_NAME/SERVICE_ACCOUNT_TOKEN | Object |
Defines the Service Account name or token that will be used by |
QUAY_USERNAME/QUAY_PASSWORD | Object |
Defines the registry credentials needed to pull the Red Hat Quay build worker image that is specified in the |
WORKER_IMAGE | Object | Image reference for the Red Hat Quay Builder image. registry.redhat.io/quay/quay-builder |
WORKER_TAG | Object | Tag for the Builder image desired. The latest version is 3.9. |
BUILDER_VM_CONTAINER_IMAGE | Object |
The full reference to the container image holding the internal VM needed to run each Red Hat Quay Build. ( |
SETUP_TIME | String |
Specifies the number of seconds at which a Build times out if it has not yet registered itself with the Build Manager. Defaults at |
MINIMUM_RETRY_THRESHOLD | String |
This setting is used with multiple Executors. It indicates how many retries are attempted to start a Build before a different Executor is chosen. Setting to |
SSH_AUTHORIZED_KEYS | Object |
List of SSH keys to bootstrap in the |
3.26. OAuth configuration fields
Field | Type | Description |
---|---|---|
DIRECT_OAUTH_CLIENTID_WHITELIST | Array of String | A list of client IDs for Quay-managed applications that are allowed to perform direct OAuth approval without user approval. |
3.26.1. GitHub OAuth configuration fields
Field | Type | Description |
---|---|---|
FEATURE_GITHUB_LOGIN | Boolean |
Whether GitHub login is supported |
GITHUB_LOGIN_CONFIG | Object | Configuration for using GitHub (Enterprise) as an external login provider. |
.ALLOWED_ORGANIZATIONS | Array of String | The names of the GitHub (Enterprise) organizations whitelisted to work with the ORG_RESTRICT option. |
.API_ENDPOINT | String |
The endpoint of the GitHub (Enterprise) API to use. Must be overridden for github.com |
.CLIENT_ID | String |
The registered client ID for this Red Hat Quay instance; cannot be shared with |
.CLIENT_SECRET | String |
The registered client secret for this Red Hat Quay instance. |
.GITHUB_ENDPOINT | String |
The endpoint for GitHub (Enterprise). |
.ORG_RESTRICT | Boolean | If true, only users within the organization whitelist can login using this provider. |
3.26.2. Google OAuth configuration fields
Field | Type | Description |
---|---|---|
FEATURE_GOOGLE_LOGIN | Boolean |
Whether Google login is supported. |
GOOGLE_LOGIN_CONFIG | Object | Configuration for using Google for external authentication. |
.CLIENT_ID | String |
The registered client ID for this Red Hat Quay instance. |
.CLIENT_SECRET | String |
The registered client secret for this Red Hat Quay instance. |
3.27. OIDC configuration fields
Field | Type | Description |
<string>_LOGIN_CONFIG | String |
The parent key that holds the OIDC configuration settings. Typically the name of the OIDC provider, for example, |
.CLIENT_ID | String |
The registered client ID for this Red Hat Quay instance. |
.CLIENT_SECRET | String |
The registered client secret for this Red Hat Quay instance. |
.DEBUGLOG | Boolean | Whether to enable debugging. |
.LOGIN_BINDING_FIELD | String | Used when the internal authorization is set to LDAP. Red Hat Quay reads this parameter and tries to search through the LDAP tree for the user with this username. If it exists, it automatically creates a link to that LDAP account. |
.LOGIN_SCOPES | Object | Adds additional scopes that Red Hat Quay uses to communicate with the OIDC provider. |
.OIDC_ENDPOINT_CUSTOM_PARAMS | String |
Support for custom query parameters on OIDC endpoints. The following endpoints are supported: |
.OIDC_ISSUER | String |
Allows the user to define the issuer to verify. For example, JWT tokens container a parameter known as |
.OIDC_SERVER | String |
The address of the OIDC server that is being used for authentication. |
.PREFERRED_USERNAME_CLAIM_NAME | String | Sets the preferred username to a parameter from the token. |
.SERVICE_ICON | String | Changes the icon on the login screen. |
.SERVICE_NAME | String |
The name of the service that is being authenticated. |
.VERIFIED_EMAIL_CLAIM_NAME | String | The name of the claim that is used to verify the email address of the user. |
3.27.1. OIDC configuration
The following example shows a sample OIDC configuration.
Example OIDC configuration
AZURE_LOGIN_CONFIG: CLIENT_ID: <client_id> CLIENT_SECRET: <client_secret> OIDC_SERVER: <oidc_server_address_> DEBUGGING: true SERVICE_NAME: Azure AD VERIFIED_EMAIL_CLAIM_NAME: <verified_email> OIDC_ENDPOINT_CUSTOM_PARAMS": "authorization_endpoint": "some": "param",
3.28. Nested repositories configuration fields
Support for nested repository path names has been added under the FEATURE_EXTENDED_REPOSITORY_NAMES
property. This optional configuration is added to the config.yaml by default. Enablement allows the use of /
in repository names.
Field | Type | Description |
---|---|---|
FEATURE_EXTENDED_REPOSITORY_NAMES | Boolean |
Enable support for nested repositories |
OCI and nested repositories configuration example
FEATURE_EXTENDED_REPOSITORY_NAMES: true
3.29. QuayIntegration configuration fields
The following configuration fields are available for the QuayIntegration custom resource:
Name | Description | Schema |
---|---|---|
allowlistNamespaces | A list of namespaces to include. | Array |
clusterID | The ID associated with this cluster. | String |
credentialsSecret.key | The secret containing credentials to communicate with the Quay registry. | Object |
denylistNamespaces | A list of namespaces to exclude. | Array |
insecureRegistry | Whether to skip TLS verification to the Quay registry | Boolean |
quayHostname | The hostname of the Quay registry. | String |
scheduledImageStreamImport | Whether to enable image stream importing. | Boolean |
3.30. Mail configuration fields
Field | Type | Description |
---|---|---|
FEATURE_MAILING | Boolean |
Whether emails are enabled |
MAIL_DEFAULT_SENDER | String |
If specified, the e-mail address used as the |
MAIL_PASSWORD | String | The SMTP password to use when sending e-mails |
MAIL_PORT | Number | The SMTP port to use. If not specified, defaults to 587. |
MAIL_SERVER | String |
The SMTP server to use for sending e-mails. Only required if FEATURE_MAILING is set to true. |
MAIL_USERNAME | String | The SMTP username to use when sending e-mails |
MAIL_USE_TLS | Boolean |
If specified, whether to use TLS for sending e-mails |
3.31. User configuration fields
Field | Type | Description |
---|---|---|
FEATURE_SUPER_USERS | Boolean |
Whether superusers are supported |
FEATURE_USER_CREATION | Boolean |
Whether users can be created (by non-superusers) |
FEATURE_USER_LAST_ACCESSED | Boolean |
Whether to record the last time a user was accessed |
FEATURE_USER_LOG_ACCESS | Boolean |
If set to true, users will have access to audit logs for their namespace |
FEATURE_USER_METADATA | Boolean |
Whether to collect and support user metadata |
FEATURE_USERNAME_CONFIRMATION | Boolean |
If set to true, users can confirm and modify their initial usernames when logging in via OpenID Connect (OIDC) or a non-database internal authentication provider like LDAP. |
FEATURE_USER_RENAME | Boolean |
If set to true, users can rename their own namespace |
FEATURE_INVITE_ONLY_USER_CREATION | Boolean |
Whether users being created must be invited by another user |
FRESH_LOGIN_TIMEOUT | String |
The time after which a fresh login requires users to re-enter their password |
USERFILES_LOCATION | String |
ID of the storage engine in which to place user-uploaded files |
USERFILES_PATH | String |
Path under storage in which to place user-uploaded files |
USER_RECOVERY_TOKEN_LIFETIME | String |
The length of time a token for recovering a user accounts is valid |
FEATURE_SUPERUSERS_FULL_ACCESS | Boolean | Grants superusers the ability to read, write, and delete content from other repositories in namespaces that they do not own or have explicit permissions for.
Default: |
FEATURE_SUPERUSERS_ORG_CREATION_ONLY | Boolean | Whether to only allow superusers to create organizations.
Default: |
FEATURE_RESTRICTED_USERS | Boolean |
When set with
Default: |
RESTRICTED_USERS_WHITELIST | String |
When set with |
GLOBAL_READONLY_SUPER_USERS | String | When set, grants users of this list read access to all repositories, regardless of whether they are public repositories. |
3.31.1. User configuration fields references
Use the following references to update your config.yaml
file with the desired configuration field.
3.31.1.1. FEATURE_SUPERUSERS_FULL_ACCESS configuration reference
--- SUPER_USERS: - quayadmin FEATURE_SUPERUSERS_FULL_ACCESS: True ---
3.31.1.2. GLOBAL_READONLY_SUPER_USERS configuration reference
--- GLOBAL_READONLY_SUPER_USERS: - user1 ---
3.31.1.3. FEATURE_RESTRICTED_USERS configuration reference
--- AUTHENTICATION_TYPE: Database --- --- FEATURE_RESTRICTED_USERS: true ---
3.31.1.4. RESTRICTED_USERS_WHITELIST configuration reference
Prerequisites
-
FEATURE_RESTRICTED_USERS
is set totrue
in yourconfig.yaml
file.
--- AUTHENTICATION_TYPE: Database --- --- FEATURE_RESTRICTED_USERS: true RESTRICTED_USERS_WHITELIST: - user1 ---
When this field is set, whitelisted users can create organizations, or read or write content from the repository even if FEATURE_RESTRICTED_USERS
is set to true
. Other users, for example, user2
, user3
, and user4
are restricted from creating organizations, reading, or writing content
3.32. Recaptcha configuration fields
Field | Type | Description |
---|---|---|
FEATURE_RECAPTCHA | Boolean |
Whether Recaptcha is necessary for user login and recovery |
RECAPTCHA_SECRET_KEY | String | If recaptcha is enabled, the secret key for the Recaptcha service |
RECAPTCHA_SITE_KEY | String | If recaptcha is enabled, the site key for the Recaptcha service |
3.33. ACI configuration fields
Field | Type | Description |
---|---|---|
FEATURE_ACI_CONVERSION | Boolean |
Whether to enable conversion to ACIs |
GPG2_PRIVATE_KEY_FILENAME | String | The filename of the private key used to decrypte ACIs |
GPG2_PRIVATE_KEY_NAME | String | The name of the private key used to sign ACIs |
GPG2_PUBLIC_KEY_FILENAME | String | The filename of the public key used to encrypt ACIs |
3.34. JWT configuration fields
Field | Type | Description |
---|---|---|
JWT_AUTH_ISSUER | String |
The endpoint for JWT users |
JWT_GETUSER_ENDPOINT | String |
The endpoint for JWT users |
JWT_QUERY_ENDPOINT | String |
The endpoint for JWT queries |
JWT_VERIFY_ENDPOINT | String |
The endpoint for JWT verification |
3.35. App tokens configuration fields
Field | Type | Description |
---|---|---|
FEATURE_APP_SPECIFIC_TOKENS | Boolean |
If enabled, users can create tokens for use by the Docker CLI |
APP_SPECIFIC_TOKEN_EXPIRATION | String |
The expiration for external app tokens. |
EXPIRED_APP_SPECIFIC_TOKEN_GC | String |
Duration of time expired external app tokens will remain before being garbage collected |
3.36. Miscellaneous configuration fields
Field | Type | Description |
---|---|---|
ALLOW_PULLS_WITHOUT_STRICT_LOGGING | String |
If true, pulls will still succeed even if the pull audit log entry cannot be written . This is useful if the database is in a read-only state and it is desired for pulls to continue during that time. |
AVATAR_KIND | String |
The types of avatars to display, either generated inline (local) or Gravatar (gravatar) |
BROWSER_API_CALLS_XHR_ONLY | Boolean |
If enabled, only API calls marked as being made by an XHR will be allowed from browsers |
DEFAULT_NAMESPACE_MAXIMUM_BUILD_COUNT | Number |
The default maximum number of builds that can be queued in a namespace. |
ENABLE_HEALTH_DEBUG_SECRET | String | If specified, a secret that can be given to health endpoints to see full debug info when not authenticated as a superuser |
EXTERNAL_TLS_TERMINATION | Boolean |
Set to |
FRESH_LOGIN_TIMEOUT | String |
The time after which a fresh login requires users to re-enter their password |
HEALTH_CHECKER | String |
The configured health check |
PROMETHEUS_NAMESPACE | String |
The prefix applied to all exposed Prometheus metrics |
PUBLIC_NAMESPACES | Array of String | If a namespace is defined in the public namespace list, then it will appear on all users' repository list pages, regardless of whether the user is a member of the namespace. Typically, this is used by an enterprise customer in configuring a set of "well-known" namespaces. |
REGISTRY_STATE | String |
The state of the registry |
SEARCH_MAX_RESULT_PAGE_COUNT | Number |
Maximum number of pages the user can paginate in search before they are limited |
SEARCH_RESULTS_PER_PAGE | Number |
Number of results returned per page by search page |
V2_PAGINATION_SIZE | Number |
The number of results returned per page in V2 registry APIs |
WEBHOOK_HOSTNAME_BLACKLIST | Array of String | The set of hostnames to disallow from webhooks when validating, beyond localhost |
CREATE_PRIVATE_REPO_ON_PUSH | Boolean |
Whether new repositories created by push are set to private visibility |
CREATE_NAMESPACE_ON_PUSH | Boolean |
Whether new push to a non-existent organization creates it |
NON_RATE_LIMITED_NAMESPACES | Array of String |
If rate limiting has been enabled using |
Boolean | When set, allows users to try the beta UI environment.
Default: | |
FEATURE_REQUIRE_TEAM_INVITE | Boolean |
Whether to require invitations when adding a user to a team |
FEATURE_REQUIRE_ENCRYPTED_BASIC_AUTH | Boolean |
Whether non-encrypted passwords (as opposed to encrypted tokens) can be used for basic auth |
FEATURE_RATE_LIMITS | Boolean |
Whether to enable rate limits on API and registry endpoints. Setting FEATURE_RATE_LIMITS to |
FEATURE_FIPS | Boolean |
If set to true, Red Hat Quay will run using FIPS-compliant hash functions |
FEATURE_AGGREGATED_LOG_COUNT_RETRIEVAL | Boolean |
Whether to allow retrieval of aggregated log counts |
FEATURE_ANONYMOUS_ACCESS | Boolean |
Whether to allow anonymous users to browse and pull public repositories |
FEATURE_DIRECT_LOGIN | Boolean |
Whether users can directly login to the UI |
FEATURE_LIBRARY_SUPPORT | Boolean |
Whether to allow for "namespace-less" repositories when pulling and pushing from Docker |
FEATURE_PARTIAL_USER_AUTOCOMPLETE | Boolean |
If set to true, autocompletion will apply to partial usernames+ |
FEATURE_PERMANENT_SESSIONS | Boolean |
Whether sessions are permanent |
FEATURE_PUBLIC_CATALOG | Boolean |
If set to true, the |
3.37. Legacy configuration fields
The following fields are deprecated or obsolete.
Field | Type | Description |
---|---|---|
FEATURE_BLACKLISTED_EMAILS | Boolean | If set to true, no new User accounts may be created if their email domain is blacklisted |
BLACKLISTED_EMAIL_DOMAINS | Array of String |
The list of email-address domains that is used if FEATURE_BLACKLISTED_EMAILS is set to true |
BLACKLIST_V2_SPEC | String |
The Docker CLI versions to which Red Hat Quay will respond that V2 is unsupported |
DOCUMENTATION_ROOT | String | Root URL for documentation links |
SECURITY_SCANNER_V4_NAMESPACE_WHITELIST | String | The namespaces for which the security scanner should be enabled |
FEATURE_RESTRICTED_V1_PUSH | Boolean |
If set to true, only namespaces listed in V1_PUSH_WHITELIST support V1 push |
V1_PUSH_WHITELIST | Array of String | The array of namespace names that support V1 push if FEATURE_RESTRICTED_V1_PUSH is set to true |
FEATURE_HELM_OCI_SUPPORT | Boolean |
Enable support for Helm artifacts. |
3.38. User interface v2 configuration field
Field | Type | Description |
---|---|---|
FEATURE_UI_V2 | Boolean | When set, allows users to try the beta UI environment.
Default: |
3.38.1. v2 user interface configuration
With FEATURE_UI_V2
enabled, you can toggle between the current version of the user interface and the new version of the user interface.
- This UI is currently in beta and subject to change. In its current state, users can only create, view, and delete organizations, repositories, and image tags.
- When running Red Hat Quay in the old UI, timed-out sessions would require that the user input their password again in the pop-up window. With the new UI, users are returned to the main page and required to input their username and password credentials. This is a known issue and will be fixed in a future version of the new UI.
- There is a discrepancy in how image manifest sizes are reported between the legacy UI and the new UI. In the legacy UI, image manifests were reported in mebibytes. In the new UI, Red Hat Quay uses the standard definition of megabyte (MB) to report image manifest sizes.
Procedure
In your deployment’s
config.yaml
file, add theFEATURE_UI_V2
parameter and set it totrue
, for example:--- FEATURE_TEAM_SYNCING: false FEATURE_UI_V2: true FEATURE_USER_CREATION: true ---
- Log in to your Red Hat Quay deployment.
In the navigation pane of your Red Hat Quay deployment, you are given the option to toggle between Current UI and New UI. Click the toggle button to set it to new UI, and then click Use Beta Environment, for example:
3.39. IPv6 configuration field
Field | Type | Description |
---|---|---|
FEATURE_LISTEN_IP_VERSION | String | Enables IPv4, IPv6, or dual-stack protocol family. This configuration field must be properly set, otherwise Red Hat Quay fails to start.
Default:
Additional configurations: |
3.40. Branding configuration fields
Field | Type | Description |
---|---|---|
BRANDING | Object | Custom branding for logos and URLs in the Red Hat Quay UI. |
.logo | String |
Main logo image URL.
The header logo defaults to 205x30 PX. The form logo on the Red Hat Quay sign in screen of the web UI defaults to 356.5x39.7 PX. |
.footer_img | String |
Logo for UI footer. Defaults to 144x34 PX. |
.footer_url | String |
Link for footer image. |
3.40.1. Example configuration for Red Hat Quay branding
Branding config.yaml example
BRANDING: logo: https://www.mend.io/wp-content/media/2020/03/5-tips_small.jpg footer_img: https://www.mend.io/wp-content/media/2020/03/5-tips_small.jpg footer_url: https://opensourceworld.org/
3.41. Session timeout configuration field
The following configuration field relies on on the Flask API configuration field of the same name.
Field | Type | Description |
---|---|---|
PERMANENT_SESSION_LIFETIME | Integer |
A
Default: |
3.41.1. Example session timeout configuration
The following YAML is the suggest configuration when enabling session lifetime.
Altering session lifetime is not recommended. Administrators should be aware of the allotted time when setting a session timeout. If you set the time too early, it might interrupt your workflow.
Session timeout YAML configuration
PERMANENT_SESSION_LIFETIME: 3000