Chapter 1. Getting started with Red Hat Quay configuration

PDF

Red Hat Quay can be deployed by an independent, standalone configuration, or by using the OpenShift Container Platform Red Hat Quay Operator.

How you create, retrieve, update, and validate the Red Hat Quay configuration varies depending on the type of deployment you are using. However, the core configuration options are the same for either deployment type. Core configuration can be set by one of the following options:

Directly, by editing the config.yaml file. See "Editing the configuration file" for more information.
Programmatically, by using the configuration API. See "Using the configuration API" for more information.
Visually, by using the configuration tool UI. See "Using the configuration tool" for more information.

For standalone deployments of Red Hat Quay, you must supply the minimum required configuration parameters before the registry can be started. The minimum requirements to start a Red Hat Quay registry can be found in the "Retrieving the current configuration" section.

If you install Red Hat Quay on OpenShift Container Platform using the Red Hat Quay Operator, you do not need to supply configuration parameters because the Red Hat Quay Operator supplies default information to deploy the registry.

After you have deployed Red Hat Quay with the desired configuration, you should retrieve, and save, the full configuration from your deployment. The full configuration contains additional generated values that you might need when restarting or upgrading your system.

1.1. Configuration updates for Quay 3.8

The following configuration fields have been introduced with Red Hat Quay 3.8:

Table 1.1. Red Hat Quay 3.8 configuration fields
Field	Type	Description
FEATURE_UI_V2	Boolean	When set, allows users to try the beta UI environment. Default: `False`
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: `IPv4` Additional configurations: `IPv6`, `dual-stack`
LDAP_SUPERUSER_FILTER	String	Subset of the `LDAP_USER_FILTER` configuration field. When configured, allows Red Hat Quay administrators the ability to configure Lightweight Directory Access Protocol (LDAP) users as superusers when Red Hat Quay uses LDAP as its authentication provider. With this field, administrators can add or remove superusers without having to update the Red Hat Quay configuration file and restart their deployment.
LDAP_RESTRICTED_USER_FILTER	String	Subset of the `LDAP_USER_FILTER` configuration field. When configured, allows Red Hat Quay administrators the ability to configure Lightweight Directory Access Protocol (LDAP) users as restricted users when Red Hat Quay uses LDAP as its authentication provider.
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: `False`
GLOBAL_READONLY_SUPER_USERS	String	When set, grants users of this list read access to all repositories, regardless of whether they are public repositories.
FEATURE_RESTRICTED_USERS	Boolean	When set with `RESTRICTED_USERS_WHITELIST`, restricted users cannot create organizations or content in their own namespace. Normal permissions apply for an organization’s membership, for example, a restricted user will still have normal permissions in organizations based on the teams that they are members of. Default: `False`
RESTRICTED_USERS_WHITELIST	String	When set with `FEATURE_RESTRICTED_USERS: true`, specific users are excluded from the `FEATURE_RESTRICTED_USERS` setting.

1.2. Configuration updates for Quay 3.7

1.2.1. New configuration fields for Red Hat Quay 3.7.7

Field Type Description

Field	Type	Description
REPO_MIRROR_ROLLBACK	Boolean	When set to `true`, the repository rolls back after a failed mirror attempt. Default: `false`

REPO_MIRROR_ROLLBACK

Boolean

When set to true, the repository rolls back after a failed mirror attempt.

Default: false

1.2.2. New configuration fields

The following configuration fields have been introduced with Red Hat Quay 3.7:

Parameter	Description
FEATURE_QUOTA_MANAGEMENT	Quota management is now supported. With this feature, users have the ability to report storage consumption and to contain registry growth by establishing configured storage quota limits. For more information about quota management, see Red Hat Quay Quota management and enforcement.
DEFAULT_SYSTEM_REJECT_QUOTA_BYTES	The quota size to apply to all organizations and users. For more information about quota management, see Red Hat Quay Quota management and enforcement.
FEATURE_PROXY_CACHE	Using Red Hat Quay to proxy a remote organization is now supported. With this feature, Red Hat Quay will act as a proxy cache to circumvent pull-rate limitations from upstream registries. For more information about quota management, see Red Hat Quay as proxy cache for upstream registries.

1.3. Configuration updates for Red Hat Quay 3.6

1.3.1. New configuration fields

The following configuration fields have been introduced with Red Hat Quay 3.6:

Parameter	Description
FEATURE_EXTENDED_REPOSITORY_NAMES	Support for nested repositories and extended repository names has been added. This change allows the use of `/` in repository names needed for certain OpenShift Container Platform use cases. For more information, see Configuring nested repositories.
FEATURE_USER_INITIALIZE	If set to true, the first `User` account can be created by the API `/api/v1/user/initialize`. For more information, see Pre-configuring Red Hat Quay for automation.
ALLOWED_OCI_ARTIFACT_TYPES	Helm, cosign, and ztsd compression scheme artifacts are built into Red Hat Quay 3.6 by default. For any other Open Container Initiative (OCI) media types that are not supported by default, you can add them to the `ALLOWED_OCI_ARTIFACT_TYPES` configuration in Quay’s `config.yaml` For more information, see Adding other OCI media types to Quay.
CREATE_PRIVATE_REPO_ON_PUSH	Registry users now have the option to set `CREATE_PRIVATE_REPO_ON_PUSH` in their `config.yaml` to `True` or `False` depending on their security needs.
CREATE_NAMESPACE_ON_PUSH	Pushing to a non-existent organization can now be configured to automatically create the organization.

1.3.2. Deprecated configuration fields

The following configuration fields have been deprecated with Red Hat Quay 3.6:

Parameter	Description
FEATURE_HELM_OCI_SUPPORT	This option has been deprecated and will be removed in a future version of Red Hat Quay. In Red Hat Quay 3.6, Helm artifacts are supported by default and included under the `FEATURE_GENERAL_OCI_SUPPORT` property. Users are no longer required to update their `config.yaml` files to enable support.

1.4. Editing the configuration file

To deploy a standalone instance of Red Hat Quay, you must provide the minimal configuration information. The requirements for a minimal configuration can be found in "Red Hat Quay minimal configuration."

After supplying the required fields, you can validate your configuration. If there are any issues, they will be highlighted.

Note

It is possible to use the configuration API to validate the configuration, but this requires starting the Quay container in configuration mode. For more information, see "Using the configuration tool."

For changes to take effect, the registry must be restarted.

1.5. Location of configuration file in a standalone deployment

For standalone deployments of Red Hat Quay, the config.yaml file must be specified when starting the Red Hat Quay registry. This file is located in the configuration volume. For example, the configuration file is located at $QUAY/config/config.yaml when deploying Red Hat Quay by the following command:

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

1.6. Minimal configuration

The following configuration options are required for a standalone deployment of Red Hat Quay:

Server hostname
HTTP or HTTPS
Authentication type, for example, Database or Lightweight Directory Access Protocol (LDAP)
Secret keys for encrypting data
Storage for images
Database for metadata
Redis for build logs and user events
Tag expiration options

1.6.1. Sample minimal configuration file

The following example shows a sample minimal configuration file that uses local storage for images:

AUTHENTICATION_TYPE: Database
BUILDLOGS_REDIS:
    host: quay-server.example.com
    password: strongpassword
    port: 6379
    ssl: false
DATABASE_SECRET_KEY: 0ce4f796-c295-415b-bf9d-b315114704b8
DB_URI: postgresql://quayuser:quaypass@quay-server.example.com:5432/quay
DEFAULT_TAG_EXPIRATION: 2w
DISTRIBUTED_STORAGE_CONFIG:
    default:
        - LocalStorage
        - storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - default
PREFERRED_URL_SCHEME: http
SECRET_KEY: e8f9fe68-1f84-48a8-a05f-02d72e6eccba
SERVER_HOSTNAME: quay-server.example.com
SETUP_COMPLETE: true
TAG_EXPIRATION_OPTIONS:
    - 0s
    - 1d
    - 1w
    - 2w
    - 4w
USER_EVENTS_REDIS:
    host: quay-server.example.com
    port: 6379
    ssl: false

Note

The SETUP_COMPLETE field indicates that the configuration has been validated. You should use the configuration editor tool to validate your configuration before starting the registry.

1.6.2. Local storage

Using local storage for images is only recommended when deploying a registry for proof of concept purposes.

When configuring local storage, storage is specified on the command line when starting the registry. The following command maps a local directory, $QUAY/storage to the datastorage path in the container:

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

1.6.3. Cloud storage

Storage configuration is detailed in the Image storage section. For some users, it might be useful to compare the difference between Google Cloud Platform and local storage configurations. For example, the following YAML presents a Google Cloud Platform storage configuration:

$QUAY/config/config.yaml

DISTRIBUTED_STORAGE_CONFIG:
    default:
        - GoogleCloudStorage
        - access_key: GOOGQIMFB3ABCDEFGHIJKLMN
          bucket_name: quay_bucket
          secret_key: FhDAYe2HeuAKfvZCAGyOioNaaRABCDEFGHIJKLMN
          storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - default

When starting the registry using cloud storage, no configuration is required on the command line. For example:

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