Understand Red Hat Quay configuration: Overview

Learn how Red Hat Quay configuration works across deployment types, including the role of config.yaml and common configuration concepts.

Getting started with Project Quay configuration

Project Quay is a secure artifact registry that can be deployed as a self-managed installation, or through the Red Hat Quay on OpenShift Container Platform Operator. Each deployment type offers a different approach to configuration and management, but each relies on the same set of configuration parameters to control registry behavior. Common configuration parameters allow administrators to define how their registry interacts with users, storage backends, authentication providers, security policies, and other integrated services.

You can configure Project Quay in one of two ways, depending on your deployment type:

  • On-premises Project Quay: With an on-premises Project Quay deployment, a registry administrator provides a config.yaml file that includes all required parameters. For this deployment type, the registry is unable to start without a valid configuration.

  • Project Quay Operator: By default, the Project Quay Operator automatically configures your Project Quay deployment by generating the minimal required values and deploying the necessary components for you. After the initial deployment, you can customize your registry’s behavior by modifying the QuayRegistry custom resource, or by using the OpenShift Container Platform Web Console.

This guide offers an overview of the following configuration concepts:

  • How to retrieve, inspect, and modify your current configuration for both on-premises and Operator-based Project Quay deployment types.

  • The minimal configuration fields required for startup.

  • An overview of all available Project Quay configuration fields and YAML examples for those fields.

Project Quay configuration disclaimer

Some Project Quay configuration parameters and feature flags are undocumented or not actively supported. Modifying these settings can cause unexpected behavior in your deployment, so you should use them only with caution.

In both self-managed and Operator-based deployments of Project Quay, certain features and configuration parameters are not actively used or implemented. As a result, some feature flags, such as those that enable or disable specific functionality, or configuration parameters that are not explicitly documented or supported by or requested for documentation by Red Hat Support, should only be modified with caution.

Understanding the Project Quay configuration file

The Project Quay config.yaml file defines registry behavior. The config.yaml file must include all required configuration fields for the registry to start. Project Quay administrators can also define optional parameters that customize their registry, such as authentication parameters, storage parameters, proxy cache parameters, and so on.

The config.yaml file must be written using valid YAML ("YAML Ain’t Markup Language") syntax, and Project Quay cannot start if the file itself contains any formatting errors or missing required fields. Regardless of deployment type, whether on-premises or Red Hat Quay on OpenShift Container Platform with the Operator, the YAML principles stay the same, even if the required configuration fields are slightly different.

The following section outlines basic YAML syntax relevant to creating and editing the Project Quay config.yaml file. For a more complete overview of YAML, see "What is YAML?".

Key-value pairs

Configuration fields within a config.yaml file are written as key-value pairs in the following form:

# ...
EXAMPLE_FIELD_NAME: <value>
# ...

The # …​ comment denotes fields before and after this specific field. Note that by supplying the #, or hash symbol, comments can be provided within the YAML file.

Each line within a config.yaml file contains a field name, followed by a colon, a space, and then an appropriate value that matches with the key. The following example shows you how the AUTHENTICATION_TYPE configuration field must be formatted in your config.yaml file.

AUTHENTICATION_TYPE: Database
# ...
AUTHENTICATION_TYPE

Specifies the authentication engine to use for credential authentication.

In the previous example, the AUTHENTICATION_TYPE is set to Database, however, different deployment types require a different value. The following example shows you how your config.yaml file might look if LDAP, or Lightweight Directory Access Protocol, was used for authentication:

AUTHENTICATION_TYPE: LDAP
# ...

Indentation and nesting

Many Project Quay configuration fields require indentation to indicate nested structures. Indentation must be done by using white spaces, or literal space characters; tab characters are not allowed by design. Indentation must be consistent across the file. The following YAML snippet shows you how the BUILDLOGS_REDIS field uses indentation for the required host, password, and port fields:

# ...
BUILDLOGS_REDIS:
    host: quay-server.example.com
    password: example-password
    port: 6379
# ...

Lists

In some cases, the Project Quay configuration field relies on lists to define certain values. You format lists by using a hyphen (-) followed by a space. The following example shows you how the SUPER_USERS configuration field uses a list to define superusers:

# ...
SUPER_USERS:
- quayadmin
# ...

Quoted values

Some Project Quay configuration fields require the use of quotation marks ("") to properly define a variable. This is generally not required. The following examples shows you how the FOOTER_LINKS configuration field uses quotation marks to define the TERMS_OF_SERVICE_URL, PRIVACY_POLICY_URL, SECURITY_URL, and ABOUT_URL:

FOOTER_LINKS:
  "TERMS_OF_SERVICE_URL": "https://www.index.hr"
  "PRIVACY_POLICY_URL": "https://www.jutarnji.hr"
  "SECURITY_URL": "https://www.bug.hr"
  "ABOUT_URL": "https://www.zagreb.hr"

Comments

The hash symbol, or #, can be placed at the beginning of a line to add comments or to temporarily disable a configuration field. The configuration parser ignores them, so they do not affect registry behavior. For example:

# ...
# FEATURE_UI_V2: true
# ...

In this example, the configuration parser ignores the FEATURE_UI_V2 configuration, meaning that the option to use the v2 UI is disabled. Using the # symbol on a required configuration field results in failure for the registry to start.

Understand Red Hat Quay configuration: Standalone deployment

Configure a standalone or on-premises Red Hat Quay deployment using minimal config.yaml examples, post-deployment updates, and procedures to verify, troubleshoot, and read the configuration file.

On-premise Project Quay configuration overview

For on-premise Project Quay deployments, you manage a config.yaml file that Project Quay reads at container startup. You must restart the registry container after you change the file because Project Quay does not reload configuration dynamically.

This chapter provides an overview of the following concepts:

  • The minimal required configuration fields.

  • How to edit and manage your configuration after deployment.

This section applies specifically to on-premise Project Quay deployment types. For information about configuring Red Hat Quay on OpenShift Container Platform, see "Red Hat Quay on OpenShift Container Platform configuration overview".

Minimal required fields for standalone config

The following configuration fields are required to start an on-premises Project Quay deployment. You must include each field in your config.yaml file before the registry can start.

Table 1. Required configuration fields
Field Type Description

AUTHENTICATION_TYPE (Required)

String

The authentication engine to use for credential authentication. Values: One of Database, LDAP, JWT, Keystone, OIDC. Default: Database.

BUILDLOGS_REDIS (Required)

Object

Redis connection details for build logs caching.

.host (Required)

String

The hostname at which Redis is accessible.

.password

String

The password to connect to the Redis instance.

DATABASE_SECRET_KEY (Required)

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. This value is set automatically by the Project Quay Operator for Operator-based deployments. For standalone deployments, administrators can provide their own key using Open SSL or a similar tool. Key length should not exceed 63 characters.

DB_URI (Required)

String

The URI for accessing the database, including any credentials.

DISTRIBUTED_STORAGE_CONFIG (Required)

Object

Configuration for storage engine(s) to use in Project 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. Default: []

SECRET_KEY (Required)

String

Key used to encrypt the session cookie and the CSRF token needed for correct interpretation of the user session. The value should not be changed when set. Should be persistent across all Project Quay instances. If not persistent across all instances, login failures and other errors related to session persistence might occur.

SERVER_HOSTNAME (Required)

String

The URL at which Project Quay is accessible, without the scheme.

SETUP_COMPLETE (Required)

Boolean

This is an artifact left over from earlier versions of the software and currently it must be specified with a value of True.

USER_EVENTS_REDIS (Required)

Object

Redis connection details for user event handling.

.host (Required)

String

The hostname at which Redis is accessible.

.port (Required)

Number

The port at which Redis is accessible.

.password

String

The password to connect to the Redis instance.

Minimal configuration file examples

You can use minimal config.yaml file examples to start an on-premises Project Quay registry with local or cloud-based storage. These examples show only the required fields.

This section provides two examples of a minimal configuration file: one example that uses local storage, and another example that uses cloud-based storage with Google Cloud Platform.

Minimal configuration using local storage

A minimal config.yaml for on-premises Project Quay uses local storage for images. Use this example only for proof of concept deployments, not production.

Important

Only use local storage when deploying a registry for proof of concept purposes. Local storage is not intended for production purposes. When using local storage, you must map the registry to a local directory to the datastorage path in the container when starting the registry. For more information, see Proof of Concept - Deploying Project Quay
Local storage minimal configuration
AUTHENTICATION_TYPE: Database
BUILDLOGS_REDIS:
    host: <quay-server.example.com>
    password: <password>
    port: <port>
DATABASE_SECRET_KEY: <example_database_secret_key>
DB_URI: postgresql://<username>:<password>@<registry_url>.com:<port>/quay
DISTRIBUTED_STORAGE_CONFIG:
  default:
    - LocalStorage
    - storage_path: /datastorage/registry
SECRET_KEY: <example_secret_key>
SERVER_HOSTNAME: <server_host_name>
SETUP_COMPLETE: true
USER_EVENTS_REDIS:
  host: <redis_events_url>
  password: <password>
  port: <port>
Minimal configuration using cloud-based storage

A minimal config.yaml for on-premises Project Quay can use cloud-based object storage such as Google Cloud Platform. Use this pattern when you deploy Project Quay with a supported enterprise storage backend.

In most production environments, Project Quay administrators use cloud or enterprise-grade storage backends provided by supported vendors. The following example shows you how to configure Project Quay to use Google Cloud Platform for image storage. For a complete list of supported storage providers, see "Image storage".

Note

When using a cloud or enterprise-grade storage backend, additional configuration, such as mapping the registry to a local directory, is not required.
Cloud storage minimal configuration
AUTHENTICATION_TYPE: Database
BUILDLOGS_REDIS:
    host: <quay-server.example.com>
    password: <password>
    port: <port>
DATABASE_SECRET_KEY: <example_database_secret_key>
DB_URI: postgresql://<username>:<password>@<registry_url>.com:<port>/quay
DISTRIBUTED_STORAGE_CONFIG:
    default:
        - GoogleCloudStorage
        - access_key: <access_key>
          bucket_name: <bucket_name>
          secret_key: <secret_key>
          storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - default
SECRET_KEY: <example_secret_key>
SERVER_HOSTNAME: <server_host_name>
SETUP_COMPLETE: true
USER_EVENTS_REDIS:
  host: <redis_events_url>
  password: <password>
  port: <port>

Modifying your configuration file after deployment

To update your on-premises Project Quay configuration after deployment, you can edit the config.yaml file and restart the quay-registry container. You can retrieve the file from the container if you do not have direct access to it.

After deploying a Project Quay registry with an initial config.yaml file, Project Quay administrators can update the configuration file to enable or disable features as needed. This flexibility allows administrators to tailor the registry to fit their specific environment needs, or to meet certain security policies.

Note

Because the config.yaml file is not dynamically reloaded, you must restart the Project Quay container after making changes for them to take effect.

The following procedure shows you how to retrieve the config.yaml file from the quay-registry container, how to enable a new feature by adding that feature’s configuration field to the file, and how to restart the quay-registry container using Podman.

Prerequisites

  • You have deployed Project Quay.

  • You are a registry administrator.

Procedure

  1. If you have access to the config.yaml file:

    1. Navigate to the directory that is storing the config.yaml file. For example:

      $ cd /home/<username>/<quay-deployment-directory>/config

    2. Make changes to the config.yaml file by adding a new feature flag. The following example enables the v2 UI:

      # ...
FEATURE_UI_V2: true
# ...

    3. Save the changes made to the config.yaml file.

    4. Restart the quay-registry pod by entering the following command:

      $ podman restart <container_id>

  2. If you do not have access to the config.yaml file and need to create a new file while keeping the same credentials:

    1. Retrieve the container ID of your quay-registry pod by entering the following command:

      $ podman ps
      Example output
      CONTAINER ID  IMAGE                                                                     COMMAND         CREATED       STATUS       PORTS                                                                       NAMES
5f2297ef53ff  registry.redhat.io/rhel8/postgresql-13:1-109                              run-postgresql  20 hours ago  Up 20 hours  0.0.0.0:5432->5432/tcp                                                      postgresql-quay
3b40fb83bead  registry.redhat.io/rhel8/redis-5:1                                        run-redis       20 hours ago  Up 20 hours  0.0.0.0:6379->6379/tcp                                                      redis
0b4b8fbfca6d  registry-proxy.engineering.redhat.com/rh-osbs/quay-quay-rhel8:v3.14.0-14  registry        20 hours ago  Up 20 hours  0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp, 7443/tcp, 9091/tcp, 55443/tcp  quay

    2. Copy the config.yaml file from the quay-registry pod to a directory by entering the following command:

      $ podman cp <container_id>:/quay-registry/conf/stack/config.yaml ./config.yaml

    3. Make changes to the config.yaml file by adding a new feature flag. The following example sets the AUTHENTICATION_TYPE to LDAP

      # ...
AUTHENTICATION_TYPE: LDAP
# ...

    4. Re-deploy the registry, mounting the config.yaml file into the quay-registry configuration volume by entering the following command:

      $ sudo podman run -d --rm -p 80:8080 -p 443:8443 \
   --name=quay \
   -v /home/<username>/<quay-deployment-directory>/config:/conf/stack:Z \
   registry.redhat.io/quay/quay-rhel8:v3.14.0

Troubleshooting the configuration file for standalone deployments

To identify configuration errors that prevent your on-premises Project Quay registry from starting, you can deploy the quay-registry container interactively and review the validation output.

Failure to add all of the required configuration field, or to provide the proper information for some parameters, might result in the quay-registry container failing to deploy. Use the following procedure to view and troubleshoot a failed on-premises deployment type.

Prerequisites

  • You have created a minimal configuration file.

Procedure

  • Attempt to deploy the quay-registry container by entering the following command. Note that this command uses the -it, which shows you debugging information:

    $ podman run -it --rm -p 80:8080 -p 443:8443 --name=quay -v /home/<username>/<quay-deployment-directory>/config:/conf/stack:Z    -v /home/<username>/<quay-deployment-directory>/storage:/datastorage:Z 33f1c3dc86be
    Example output
    ---
+------------------------+-------+--------+
| LDAP                   | -     | X      |
+------------------------+-------+--------+
| LDAP_ADMIN_DN is required      | X      |
+-----------------------------------------+
| LDAP_ADMIN_PSSWD is required   | X      |
+-----------------------------------------+
| . . . Connection refused       | X      |
+-----------------------------------------+
---

    In this example, the quay-registry container failed to deploy because improper LDAP credentials were provided.

Reading the configuration file from a standalone deployment by using Podman

To obtain configuration information for your Project Quay deployment and troubleshoot issues, you can use podman cp or podman exec for standalone deployments. You can then update your config.yaml file, search the Red Hat Knowledgebase, or file a support ticket.

Procedure

  1. To obtain configuration information on standalone Project Quay deployments, you can use podman cp or podman exec.

    1. To use the podman copy command, enter the following commands:

      $ podman cp <quay_container_id>:/conf/stack/config.yaml /tmp/local_directory/

      To display this information in your terminal, enter the following command:

      $ cat /tmp/local_directory/config.yaml

    2. To use podman exec, enter the following commands:

      $ podman exec -it <quay_container_id> cat /conf/stack/config.yaml
      Example output
      BROWSER_API_CALLS_XHR_ONLY: false
ALLOWED_OCI_ARTIFACT_TYPES:
    application/vnd.oci.image.config.v1+json:
        - application/vnd.oci.image.layer.v1.tar+zstd
    application/vnd.sylabs.sif.config.v1+json:
        - application/vnd.sylabs.sif.layer.v1+tar
AUTHENTICATION_TYPE: Database
AVATAR_KIND: local
BUILDLOGS_REDIS:
    host: quay-server.example.com
    password: strongpassword
    port: 6379
DATABASE_SECRET_KEY: 05ee6382-24a6-43c0-b30f-849c8a0f7260
DB_CONNECTION_ARGS: {}
---

Understand Red Hat Quay configuration: OpenShift Container Platform

Learn how the Quay Operator manages registry configuration on OpenShift through the QuayRegistry custom resource, managed and unmanaged components, and the config bundle Secret.

How Operator configuration works

When deploying Red Hat Quay on OpenShift Container Platform, the registry configuration is managed declaratively through two primary mechanisms: the QuayRegistry custom resource (CR) and the configBundleSecret resource. You use these mechanisms to configure and manage your registry deployment.

Understanding the QuayRegistry CR

The QuayRegistry CR is used to determine whether a component is managed, or automatically handled by the Operator, or unmanaged, or provided externally by the user.

By default, the QuayRegistry CR contains the following key fields:

  • configBundleSecret: The name of a Kubernetes Secret containing the config.yaml file which defines additional configuration parameters.

  • name: The name of your Project Quay registry.

  • namespace: The namespace, or project, in which the registry was created.

  • spec.components: A list of components that the Operator automatically manages. Each component entry includes the following fields:

    • kind: The name of the component

    • managed: A boolean that addresses whether the component lifecycle is handled by the Project Quay Operator. Setting managed: true to a component in the QuayRegistry CR means that the Operator manages the component.

    • secretRef: Optional. For the tls component only, references an external kubernetes.io/tls Secret when managed is false. For more information, see Referencing an external TLS Secret for Red Hat Quay on OpenShift Container Platform.

All QuayRegistry components are automatically managed and auto-filled upon reconciliation for visibility unless specified otherwise. The following sections highlight the major QuayRegistry components and provide an example YAML file that shows the default settings.

Managed components

Managed components are Project Quay registry components that the Operator automatically configures and installs. By using managed components, you simplify deployment and reduce manual configuration tasks.

Table 2. QuayRegistry required fields
Field Type Description

quay

Boolean

Holds overrides for deployment of Red Hat Quay on OpenShift Container Platform, such as environment variables and number of replicas. This component cannot be set to unmanaged (managed: false).

postgres

Boolean

Used for storing registry metadata. Currently, PostgreSQL version 13 is used.

clair

Boolean

Provides image vulnerability scanning. You can override ephemeral scratch storage for image layer extraction by using overrides.volumeSize and overrides.storageClassName.

redis

Boolean

Stores live builder logs and the locking mechanism that is required for garbage collection. You can override CPU and memory resources for this component when it is managed.

horizontalpodautoscaler

Boolean

Adjusts the number of quay pods depending on your memory and CPU consumption.

objectstorage

Boolean

Stores image layer blobs. When set to managed: true, utilizes the ObjectBucketClaim Kubernetes API which is provided by NooBaa or Red Hat OpenShift Data Foundation. Setting this field to managed: false requires you to provide your own object storage.

route

Boolean

Provides an external entrypoint to the Project Quay registry from outside of OpenShift Container Platform.

mirror

Boolean

Configures repository mirror workers to support optional repository mirroring.

monitoring

Boolean

Features include a Grafana dashboard, access to individual metrics, and notifications for frequently restarting quay pods.

tls

Boolean

Configures whether SSL/TLS is automatically handled. When managed is false, you can optionally set secretRef to reference an external kubernetes.io/tls Secret instead of embedding ssl.cert and ssl.key in the configBundleSecret.

clairpostgres

Boolean

Configures a managed Clair database. This is a separate database than the PostgreSQL database that is used to deploy Project Quay.

The following example shows you the default configuration for the QuayRegistry custom resource provided by the Project Quay Operator. It is available on the OpenShift Container Platform web console.

apiVersion: quay.redhat.com/v1
kind: QuayRegistry
metadata:
  name: <example_registry>
  namespace: <namespace>
  spec:
    configBundleSecret: config-bundle-secret
    components:
    - kind: quay
      managed: true
    - kind: postgres
      managed: true
    - kind: clair
      managed: true
    - kind: redis
      managed: true
    - kind: horizontalpodautoscaler
      managed: true
    - kind: objectstorage
      managed: true
    - kind: route
      managed: true
    - kind: mirror
      managed: true
    - kind: monitoring
      managed: true
    - kind: tls
      managed: true
    - kind: clairpostgres
      managed: true

Disabling the monitoring component

Disabling the monitoring component sets the monitoring component to unmanaged in the QuayRegistry custom resource. You must disable monitoring when you install the Project Quay Operator in a single namespace, or you can disable it in multi-namespace installations to use your own monitoring stack.

Note

Monitoring cannot be enabled when the Project Quay Operator is installed in a single namespace.

You might also disable monitoring in multi-namespace deployments if you use an external Prometheus or Grafana instance, want to reduce resource overhead, or require custom observability integration.

 
apiVersion: quay.redhat.com/v1
kind: QuayRegistry
metadata:
  name: example-registry
  namespace: quay-enterprise
spec:
  components:
    - kind: monitoring
      managed: false

Disabling the mirroring component

Repository mirroring in Project Quay allows you to automatically synchronize container images from remote registries into your local Project Quay instance. The Project Quay Operator deploys a separate mirroring worker component that handles these synchronization tasks.

You can disable the managed mirroring component by setting it to managed: false in the QuayRegistry custom resource.

Note

Disabling managed mirroring means that the Operator does not deploy or reconcile any mirroring pods. You are responsible for creating, scheduling, and maintaining mirroring jobs manually. For most production deployments, leaving mirroring as managed: true is recommended.

 
apiVersion: quay.redhat.com/v1
kind: QuayRegistry
metadata:
  name: example-registry
  namespace: quay-enterprise
spec:
  components:
    - kind: mirroring
      managed: false

Using unmanaged components for dependencies

Unmanaged components are Project Quay dependencies such as PostgreSQL, Redis, or object storage that you deploy and maintain outside of the Operator’s control. You use unmanaged components to integrate existing infrastructure or meet specific configuration requirements.

Note

If you are using an unmanaged PostgreSQL database, and the version is PostgreSQL 10, it is highly recommended that you upgrade to PostgreSQL 13. PostgreSQL 10 had its final release on November 10, 2022 and is no longer supported. For more information, see the PostgreSQL Versioning Policy.

For more information about configuring unmanaged components, see "Configure Red Hat Quay database and Redis backends", "Object storage backend configuration fields", "Configure networking for Red Hat Quay", and "Tune Operator autoscaling and component resources".

Referencing an external TLS Secret for Red Hat Quay on OpenShift Container Platform

You can reference an external kubernetes.io/tls Secret from the tls component of the QuayRegistry custom resource (CR). The Project Quay Operator uses the certificate and private key from that Secret instead of embedding ssl.cert and ssl.key files in the configBundleSecret resource. This approach supports automated certificate rotation from sources such as cert-manager, HashiCorp Vault, or manual Secret updates.

When you use an external TLS Secret, set spec.components[kind: tls].managed to false and specify secretRef. The Operator watches the referenced Secret and performs a rolling restart of Project Quay pods when the certificate data changes.

Important

  • secretRef is valid only when the tls component is unmanaged (managed: false).

  • Do not configure both secretRef and ssl.cert / ssl.key files in the configBundleSecret resource. The Operator reports a conflict if both TLS sources are present.

  • The certificate Subject Alternative Name (SAN) must include the hostname clients use to reach the registry. If the hostname does not match, the Operator can report RolloutBlocked=True until the certificate is corrected.

  • Existing deployments that use embedded ssl.cert and ssl.key files in the config bundle continue to work without changes.
Prerequisites

  • You have deployed the Project Quay Operator and a QuayRegistry CR.

  • You have a TLS Secret of type kubernetes.io/tls in the same namespace as the QuayRegistry, with tls.crt and tls.key data keys.

  • The certificate and private key are valid (format, key match, chain, and hostname).

Procedure

  1. Create a TLS Secret in the registry namespace, for example:

    apiVersion: v1
kind: Secret
metadata:
  name: my-quay-tls
  namespace: <namespace>
type: kubernetes.io/tls
data:
  tls.crt: <base64_encoded_certificate>
  tls.key: <base64_encoded_private_key>

  2. Set the tls component to unmanaged and reference the Secret by entering the following command:

    $ oc patch quayregistry <registry_name> -n <namespace> --type=merge -p '{"spec":{"components":[{"kind":"tls","managed":false,"secretRef":{"name":"my-quay-tls"}}]}}'

  3. Verify that the QuayRegistry CR contains the expected configuration:

    $ oc get quayregistry <registry_name> -n <namespace> -o yaml
    Example output
    spec:
  components:
  - kind: tls
    managed: false
    secretRef:
      name: my-quay-tls

  4. Wait for the Operator to reconcile the registry. When certificate data in the referenced Secret changes, the Operator triggers a rolling restart of Project Quay pods to load the updated certificate.

  5. Verify that TLS from the external Secret is ready by entering the following command. When the TLS component is healthy, the ComponentTLSReady condition reports status: "True".

    $ oc wait quayregistry <registry_name> -n <namespace> --for=condition=ComponentTLSReady=True --timeout=300s

    You can also review all component conditions in the OpenShift Container Platform web console on the QuayRegistry details page, or by entering oc get quayregistry <registry_name> -n <namespace> -o yaml and checking status.conditions.

Additional resources

Modifying the QuayRegistry CR after deployment

Modifying the QuayRegistry custom resource (CR) in Project Quay after deployment lets you customize or reconfigure aspects of your Project Quay environment.

Project Quay administrators might modify the QuayRegistry CR for the following reasons:

  • To change component management: Switch components from managed: true to managed: false in order to bring your own infrastructure. For example, you might set kind: objectstorage to unmanaged to integrate external object storage platforms such as Google Cloud Storage or Nutanix.

  • To apply custom configuration: Update or replace the configBundleSecret to apply new configuration settings, for example, authentication providers, external SSL/TLS settings, feature flags.

  • To enable or disable features: Toggle features like repository mirroring, Clair scanning, or horizontal pod autoscaling by modifying the spec.components list.

  • To scale the deployment: Adjust environment variables or replica counts for the Quay application.

  • To integrate with external services: Provide configuration for external PostgreSQL, Redis, or Clair databases, and update endpoints or credentials.

Modifying the QuayRegistry CR by using the OpenShift Container Platform web console

To modify the QuayRegistry custom resource in Project Quay, you can use the OpenShift Container Platform web console to change component management settings. You can set managed components to unmanaged and use your own infrastructure.

Prerequisites

  • You are logged into OpenShift Container Platform as a user with admin privileges.

  • You have installed the Project Quay Operator.

Procedure

  1. On the OpenShift Container Platform web console, click Operators → Installed Operators.

  2. Click Red Hat Quay.

  3. Click Quay Registry.

  4. Click the name of your Project Quay registry, for example, example-registry.

  5. Click YAML.

  6. Adjust the managed field of the desired component to either True or False.

  7. Click Save.

    Note

    Setting a component to unmanaged (managed: false) might require additional configuration. For more information about setting unmanaged components in the QuayRegistry CR, see Using unmanaged components for dependencies.

Modifying the QuayRegistry CR by using the CLI

To modify the QuayRegistry custom resource in Project Quay, you can use the CLI to change component management settings. You can set managed components to unmanaged and use your own infrastructure.

Prerequisites

  • You are logged in to your OpenShift Container Platform cluster as a user with admin privileges.

Procedure

  1. Edit the QuayRegistry CR by entering the following command:

    $ oc edit quayregistry <registry_name> -n <namespace>

  2. Make the desired changes to the QuayRegistry CR.

    Note

    Setting a component to unmanaged (managed: false) might require additional configuration. For more information about setting unmanaged components in the QuayRegistry CR, see Using unmanaged components for dependencies.

  3. Save the changes.

Additional resources

Understanding the configBundleSecret resource

The configBundleSecret resource is a Kubernetes Secret that stores the config.yaml file for Project Quay. You use this secret to configure authentication backends, feature flags, TLS settings, and other registry parameters that the Operator merges with managed component settings.

Project Quay administrators might update this secret for the following reasons:

  • Enable a new authentication method

  • Add custom SSL/TLS certificates

  • Enable features

  • Modify security scanning settings

If this field is omitted, the Project Quay Operator automatically generates a configuration secret based on default values and managed component settings. If you provide this field, Project Quay uses the config.yaml contents as the base configuration and merges them with values from managed components to form the final configuration, which is mounted into the quay application pods.

Modifying the configuration file by using the OpenShift Container Platform web console

To modify the config.yaml file stored in the configBundleSecret, you can use the OpenShift Container Platform web console to edit the secret and add configuration key-value pairs.

Prerequisites

  • You are logged in to the OpenShift Container Platform cluster as a user with admin privileges.

Procedure

  1. On the OpenShift Container Platform web console, click Operators → Installed Operators → Red Hat Quay.

  2. Click Quay Registry.

  3. Click the name of your Project Quay registry, for example, example-registry.

  4. On the QuayRegistry details page, click the name of your Config Bundle Secret, for example, example-registry-config-bundle.

  5. Click Actions → Edit Secret.

  6. In the Value box, add the desired key/value pair. For example, to add a superuser to your Red Hat Quay on OpenShift Container Platform deployment, add the following reference:

    SUPER_USERS:
- quayadmin

  7. Click Save.

    Note

    You must base64 encode any updated config.yaml file before placing it in the Secret. Ensure the Secret name matches the value specified in spec.configBundleSecret resource. Once the Secret is updated, the Operator detects the change and automatically rolls out updates to the Project Quay pods.

    For detailed steps, see "Updating configuration secrets through the Project Quay UI."
Verification

  1. Verify that the changes have been accepted:

    1. On the OpenShift Container Platform web console, click Operators → Installed Operators → Red Hat Quay.

    2. Click Quay Registry.

    3. Click the name of your Project Quay registry, for example, example-registry.

    4. Click Events. If successful, the following message is displayed:

      All objects created/updated successfully

Modifying the configuration file by using the CLI

To modify the config.yaml file for your Project Quay registry and enable new features, you can download the existing configuration from the configBundleSecret by using the CLI. After making changes, you can re-upload the configBundleSecret resource to apply the changes.

Note

Modifying the config.yaml file that is stored by the configBundleSecret resource is a multi-step procedure that requires base64 decoding the existing configuration file and then uploading the changes. For most cases, using the OpenShift Container Platform web console to make changes to the config.yaml file is simpler.
Prerequisites

  • You are logged in to the OpenShift Container Platform cluster as a user with admin privileges.

Procedure

  1. Describe the QuayRegistry resource by entering the following command:

    $ oc describe quayregistry -n <quay_namespace>
    # ...
  Config Bundle Secret: example-registry-config-bundle-v123x
# ...

  2. Obtain the secret data by entering the following command:

    $ oc get secret -n <quay_namespace> <example-registry-config-bundle-v123x> -o jsonpath='{.data}'
    {
    "config.yaml": "RkVBVFVSRV9VU0 ... MDAwMAo="
}

  3. Decode the data into a YAML file into the current directory by passing in the >> config.yaml flag. For example:

    $ echo 'RkVBVFVSRV9VU0 ... MDAwMAo=' | base64 --decode >> config.yaml

  4. Make the desired changes to your config.yaml file, and then save the file as config.yaml.

  5. Create a new configBundleSecret YAML by entering the following command.

    $ touch <new_configBundleSecret_name>.yaml

  6. Create the new configBundleSecret resource, passing in the config.yaml file` by entering the following command:

    $ oc -n <namespace> create secret generic <secret_name> \
  --from-file=config.yaml=</path/to/config.yaml> \
  --dry-run=client -o yaml > <new_configBundleSecret_name>.yaml

    where:

    </path/to/config.yaml>

    Specifies your base64 decoded config.yaml file.

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

    $ oc create -n <namespace> -f <new_configBundleSecret_name>.yaml
    secret/config-bundle created

  8. Update the QuayRegistry YAML file to reference the new configBundleSecret object by entering the following command:

    $ oc patch quayregistry <registry_name> -n <namespace> --type=merge -p '{"spec":{"configBundleSecret":"<new_configBundleSecret_name>"}}'
    quayregistry.quay.redhat.com/example-registry patched
Verification

  1. Verify that the QuayRegistry CR has been updated with the new configBundleSecret:

    $ oc describe quayregistry -n <quay_namespace>
    # ...
  Config Bundle Secret: <new_configBundleSecret_name>
# ...

    After patching the registry, the Project Quay Operator automatically reconciles the changes.

Reading the configuration file from an Operator deployment by using the OpenShift CLI

To obtain configuration information for your Project Quay deployment and troubleshoot issues, you can use oc exec, oc cp, or oc rsync for Operator deployments, or podmobtaining-configuration-information-quay-standalonean cp or podman exec for standalone deployments. You can then update your config.yaml file, search the Red Hat Knowledgebase, or file a support ticket.

Procedure

  1. To obtain configuration information on Project Quay Operator deployments, you can use oc exec, oc cp, or oc rsync.

    1. To use the oc exec command, enter the following command:

      $ oc exec -it <quay_pod_name> -- cat /conf/stack/config.yaml

      This command returns your config.yaml file directly to your terminal.

    2. To use the oc copy command, enter the following commands:

      $ oc cp <quay_pod_name>:/conf/stack/config.yaml /tmp/config.yaml

      To display this information in your terminal, enter the following command:

      $ cat /tmp/config.yaml

    3. To use the oc rsync command, enter the following commands:

      oc rsync <quay_pod_name>:/conf/stack/ /tmp/local_directory/

      To display this information in your terminal, enter the following command:

      $ cat /tmp/local_directory/config.yaml
      Example output
      DISTRIBUTED_STORAGE_CONFIG:
local_us:
- RHOCSStorage
- access_key: redacted
  bucket_name: lht-quay-datastore-68fff7b8-1b5e-46aa-8110-c4b7ead781f5
  hostname: s3.openshift-storage.svc.cluster.local
  is_secure: true
  port: 443
  secret_key: redacted
  storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS:
- local_us
DISTRIBUTED_STORAGE_PREFERENCE:
- local_us

Retrieve Red Hat Quay configuration by using the API

Retrieve active Red Hat Quay configuration settings by using the superuser API.

Retrieving active configuration settings by using the API

To retrieve Project Quay configuration settings from the command line, you can enable FEATURE_SUPERUSER_CONFIGDUMP and call the v1/superuser/config API endpoint with a superuser OAuth 2 access token. As a Project Quay superuser, you can return all Flask configuration fields that are set, which you can use to show proof of compliance for various security policies, such as PCI-DSS 4.0.

Prerequisites

  • You have set FEATURE_SUPERUSER_CONFIGDUMP: true in your config.yaml file.

  • You have assigned the superuser role to a user in your config.yaml file.

  • You have generated an OAuth 2 access token for the superuser.

Procedure

  • Retrieve configuration settings by using the v1/superuser/config API endpoint. For example:

    $ curl -X GET -H "Authorization: Bearer <bearer_token>" "http://<quay-server.example.com>/api/v1/superuser/config" | jq -r .config
    Example output
    ...
  "TEAM_RESYNC_STALE_TIME": "30m",
  "UI_DELAY_AFTER_WRITE_SECONDS": 3,
  "UI_MODELCARD_ANNOTATION": {},
  "UI_MODELCARD_ARTIFACT_TYPE": "application/x-mlmodel",
  "UI_MODELCARD_LAYER_ANNOTATION": {
    "org.opencontainers.image.title": "README.md"
  }
...

  • You can pass in one of .config, .env, .warning, or .schema to return specific information. For example:

    $ curl -X GET -H "Authorization: Bearer <bearer_token>" "http://<quay-server.example.com>/api/v1/superuser/config" | jq -r .warning
    Example output
    ...
  "BILLING_TYPE": "FakeStripe",
  "BUILDLOGS_OPTIONS": [],
  "BUILD_MANAGER": null,
  "CDN_SPECIFIC_NAMESPACES": [],
  "CHANNEL_COLORS": [
  ]
...

Required configuration fields

Look up required configuration fields for general settings, storage, database, and Redis.

Required configuration field categories

Project Quay requires a minimal set of configuration fields to operate correctly. These fields define essential aspects of your deployment, such as how the registry is accessed, where image content is stored, how metadata is persisted, and how background services such as logs are managed.

The required configuration fields fall into four main categories:

  • General required configuration fields. Core fields such as the authentication type, URL scheme, server hostname, database secret key, and secret key are covered in this section.

  • Database configuration fields. Project Quay requires a PostgreSQL relational database to store metadata about repositories, users, teams, and tags.

  • Object storage configuration fields. Object storage defines the backend where container image blobs and manifests are stored. Your storage backend must be supported by Project Quay, such as Ceph/RadosGW, AWS S3 storage, Google Cloud Storage, and Nutanix.

  • Redis configuration fields. Redis is used as a backend for data such as push logs, user notifications, and other operations.

General required configuration fields

General required fields must be present in every Project Quay configuration to start the registry. Use this reference to confirm values for authentication, URL settings, and secret keys.

Table 3. General required fields
Field Type Description

AUTHENTICATION_TYPE (Required)

String

The authentication engine to use for credential authentication. Values: One of Database, LDAP, JWT, Keystone, OIDC. Default: Database.

PREFERRED_URL_SCHEME (Required)

String

The URL scheme to use when accessing Project Quay. Values: One of http, https. Default: http.

SERVER_HOSTNAME (Required)

String

The URL at which Project Quay is accessible, without the scheme. Example: quay-server.example.com.

DATABASE_SECRET_KEY (Required)

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. This value is set automatically by the Project Quay Operator for Operator-based deployments. For standalone deployments, administrators can provide their own key using Open SSL or a similar tool. Key length should not exceed 63 characters.

SECRET_KEY (Required)

String

Key used to encrypt the session cookie and the CSRF token needed for correct interpretation of the user session. The value should not be changed when set. The value should be persistent across all Project Quay instances. If the value is not persistent across all instances, login failures and other errors related to session persistence might occur.

SETUP_COMPLETE (Required)

Boolean

This is an artifact left over from earlier versions of the software and currently it must be specified with a value of True.
General required fields example
AUTHENTICATION_TYPE: Database
PREFERRED_URL_SCHEME: https
SERVER_HOSTNAME: <quay-server.example.com>
SECRET_KEY: <secret_key_value>
DATABASE_SECRET_KEY: <database_secret_key_value>
SETUP_COMPLETE: true
# ...

Object storage backend configuration fields

Look up object storage configuration fields for local, cloud, Ceph, Nutanix, IBM Cloud, NetApp, and HCP backends.

Storage configuration fields

You configure backend storage for Project Quay by setting distributed storage fields such as engine configuration, default locations, and preferences. Use this reference to review field types, defaults, and an example configuration.

Table 4. Storage configuration fields
Field Type Description

DISTRIBUTED_STORAGE_CONFIG (Required)

Object

Configuration for storage engine(s) to use in Project 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. Default: []

DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS (Required)

Array of string

The list of storage engine(s) (by ID in DISTRIBUTED_STORAGE_CONFIG) whose images should be fully replicated, by default, to all other storage engines.

DISTRIBUTED_STORAGE_PREFERENCE (Required)

Array of string

The preferred storage engine(s) (by ID in DISTRIBUTED_STORAGE_CONFIG) to use. A preferred engine means it is first checked for pulling and images are pushed to it. Default: False

MAXIMUM_LAYER_SIZE (Optional)

String

Maximum allowed size of an image layer. Pattern: ^[0-9]+(G|M)$ Example: 100G Default: 20G
Storage configuration example
DISTRIBUTED_STORAGE_CONFIG:
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - default
MAXIMUM_LAYER_SIZE: 100G

Local storage

You can configure Project Quay to use local filesystem storage for proof of concept deployments. Use this example to map registry data to the datastorage path in the container.

Important

Only use local storage when deploying a registry for proof of concept purposes. It is not intended for production purposes. When using local storage, you must map the registry to a local directory to the datastorage path in the container when starting the registry. For more information, see Proof of Concept - Deploying Project Quay in Additional resources.
Local storage example
DISTRIBUTED_STORAGE_CONFIG:
  default:
    - LocalStorage
    - storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - default
Additional resources

Red Hat OpenShift Data Foundation

You can configure Project Quay to use Red Hat OpenShift Data Foundation object storage by defining a DISTRIBUTED_STORAGE_CONFIG entry for the storage backend. Use this example as a starting point for required fields and optional tuning parameters.

The following YAML shows a sample configuration using an Red Hat OpenShift Data Foundation:

DISTRIBUTED_STORAGE_CONFIG:
  rhocsStorage:
    - RHOCSStorage
    - access_key: <access_key_here>
      secret_key: <secret_key_here>
      bucket_name: <bucket_name>
      hostname: <hostname>
      is_secure: 'true'
      port: '443'
      storage_path: /datastorage/registry
      maximum_chunk_size_mb: 100
      server_side_assembly: true

where:

DISTRIBUTED_STORAGE_CONFIG.rhocsStorage.maximum_chunk_size_mb

Specifies the maximum chunk size, in MB, for the final copy. Has no effect if server_side_assembly is set to False.

DISTRIBUTED_STORAGE_CONFIG.rhocsStorage.server_side_assembly

Specifies whether Project Quay tries to use server-side assembly and the final chunked copy instead of client assembly. Defaults to True. This field is optional.

Ceph Object Gateway (RadosGW) storage example

You can configure Project Quay to use Ceph Object Gateway (RadosGW) as an S3-compatible storage backend. Use this example to set required authentication fields and optional assembly settings.

Note

RadosGW is an on-premises S3-compatible storage solution. It implements the S3 API and requires the same authentication fields, such as access_key, secret_key, and bucket_name.

The following YAML shows an example configuration using RadosGW.

RadosGW with general s3 access example
DISTRIBUTED_STORAGE_CONFIG:
  radosGWStorage:
    - RadosGWStorage
    - access_key: <access_key_here>
      bucket_name: <bucket_name_here>
      hostname: <hostname_here>
      is_secure: true
      port: '443'
      secret_key: <secret_key_here>
      storage_path: /datastorage/registry
      maximum_chunk_size_mb: 100
      server_side_assembly: true

where:

DISTRIBUTED_STORAGE_CONFIG.radosGWStorage

Specifies general S3 access. Note that general S3 access is not strictly limited to Amazon Web Services (AWS) S3, 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".

DISTRIBUTED_STORAGE_CONFIG.radosGWStorage.maximum_chunk_size_mb

Specifies the maximum chunk size in MB for the final copy. Has no effect if server_side_assembly is set to False. This field is optional.

DISTRIBUTED_STORAGE_CONFIG.radosGWStorage.server_side_assembly

Specifies whether Project Quay tries to use server-side assembly and the final chunked copy instead of client assembly. Defaults to True. This field is optional.

Additional resources

Amazon Web Services storage backends

You can configure Project Quay to use AWS S3, STS, or CloudFront storage backends in DISTRIBUTED_STORAGE_CONFIG. Use these examples to set credentials, regions, and distribution settings for each backend.

Project Quay supports multiple Amazon Web Services (AWS) storage backends:

  • S3 storage: Standard support for AWS S3 buckets that uses AWS’s native object storage service.

  • STS S3 storage: Support for AWS Security Token Service (STS) to assume IAM roles, allowing for more secure S3 operations.

  • CloudFront S3 storage: Integrates with AWS CloudFront to enable high-availability distribution of content while still using AWS S3 as the origin.

The following sections provide example YAML configurations and additional information about each AWS storage backend.

Amazon Web Services S3 storage

Project Quay supports using AWS S3 as an object storage backend. AWS S3 is an object storage service designed for data availability, scalability, security, and performance. The following YAML shows an example configuration using AWS S3.

AWS S3 example
# ...
DISTRIBUTED_STORAGE_CONFIG:
  default:
    - S3Storage
    - host: s3.us-east-2.amazonaws.com
      s3_access_key: ABCDEFGHIJKLMN
      s3_secret_key: OL3ABCDEFGHIJKLMN
      s3_bucket: quay_bucket
      s3_region: <region>
      storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - default
# ...

where:

DISTRIBUTED_STORAGE_CONFIG.default

Specifies the S3Storage storage driver 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".

DISTRIBUTED_STORAGE_CONFIG.default.s3_region

Specifies the Amazon Web Services region. Defaults to us-east-1.

Amazon Web Services STS S3 storage

AWS Security Token Service (STS) provides temporary, limited-privilege credentials for accessing AWS resources, improving security by avoiding the need to store long-term access keys. This is useful in environments such as OpenShift Container Platform where credentials can be rotated or managed through IAM roles.

The following YAML shows an example configuration for using AWS STS with Red Hat Quay on OpenShift Container Platform configurations.

AWS STS S3 storage example
# ...
DISTRIBUTED_STORAGE_CONFIG:
   default:
    - STSS3Storage
    - sts_role_arn: <role_arn>
      s3_bucket: <s3_bucket_name>
      storage_path: <storage_path>
      sts_user_access_key: <s3_user_access_key>
      sts_user_secret_key: <s3_user_secret_key>
      s3_region: <region>
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - default
# ...

where:

DISTRIBUTED_STORAGE_CONFIG.default.sts_role_arn

Specifies the unique Amazon Resource Name (ARN).

DISTRIBUTED_STORAGE_CONFIG.default.sts_user_access_key

Specifies the generated AWS S3 user access key.

DISTRIBUTED_STORAGE_CONFIG.default.sts_user_secret_key

Specifies the generated AWS S3 user secret key.

DISTRIBUTED_STORAGE_CONFIG.default.s3_region

Specifies the Amazon Web Services region. Defaults to us-east-1.

AWS CloudFront storage

AWS CloudFront is a content delivery network (CDN) service that caches and distributes content closer to users for improved performance and lower latency. Project Quay supports CloudFront through the CloudFrontedS3Storage driver, which enables secure, signed access to S3 buckets via CloudFront distributions.

Use the following example when configuring AWS CloudFront for your Project Quay deployment.

Note

  • When configuring AWS CloudFront storage, the following conditions must be met for proper use with Project Quay:

    • You must set an Origin path that is consistent with Project Quay’s storage path as defined in your config.yaml file. Failure to meet this requirement results in a 403 error when pulling an image.

    • You must configure a Bucket policy and a Cross-origin resource sharing (CORS) policy.
Cloudfront S3 example YAML
DISTRIBUTED_STORAGE_CONFIG:
    default:
      - CloudFrontedS3Storage
      - cloudfront_distribution_domain: <CLOUDFRONT_DISTRIBUTION_DOMAIN>
        cloudfront_key_id: <CLOUDFRONT_KEY_ID>
        cloudfront_privatekey_filename: <CLOUDFRONT_PRIVATE_KEY_FILENAME>
        host: <S3_HOST>
        s3_access_key: <S3_ACCESS_KEY>
        s3_bucket: <S3_BUCKET_NAME>
        s3_secret_key: <S3_SECRET_KEY>
        storage_path: <STORAGE_PATH>
        s3_region: <S3_REGION>
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS:
  - default
DISTRIBUTED_STORAGE_PREFERENCE:
  - default
Bucket policy example
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AWS_ACCOUNT_ID>:user/CloudFront Origin Access Identity <CLOUDFRONT_OAI_ID>"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::<S3_BUCKET_NAME>/*"
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AWS_ACCOUNT_ID>:user/CloudFront Origin Access Identity <CLOUDFRONT_OAI_ID>"
            },
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::<S3_BUCKET_NAME>"
        }
    ]
}

  • <AWS_ACCOUNT_ID> is the identifier, or account ID, of the AWS account that owns the CloudFront OAI and S3 bucket.

  • <CLOUDFRONT_OAI_ID> is the CloudFront Origin Access Identity (OAI) that accesses the S3 bucket.

  • arn:aws:s3:::<S3_BUCKET_NAME> specifies that CloudFront can access the specified bucket in the S3 bucket.

Additional resources

Google Cloud Storage

You can configure Project Quay to use Google Cloud Storage (GCS) as an object storage backend. Use this example to set bucket credentials and optional connection timeout settings.

Google Cloud Storage example
DISTRIBUTED_STORAGE_CONFIG:
    googleCloudStorage:
        - GoogleCloudStorage
        - access_key: <access_key>
          bucket_name: <bucket_name>
          secret_key: <secret_key>
          storage_path: /datastorage/registry
          boto_timeout: 120
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - googleCloudStorage
DISTRIBUTED_STORAGE_CONFIG.googleCloudStorage.boto_timeout

Specifies the time, in seconds, until a timeout exception is thrown when attempting to read from a connection. The default is 60 seconds. Also encompasses the time, in seconds, until a timeout exception is thrown when attempting to make a connection. The default is 60 seconds. This field is optional.

Microsoft Azure Blob Storage

You can configure Project Quay to use Microsoft Azure Blob Storage as an object storage backend. Use this example to set account credentials, container details, and optional government cloud endpoints.

Microsoft Azure Blob Storage example
DISTRIBUTED_STORAGE_CONFIG:
  azureStorage:
    - AzureStorage
    - azure_account_name: <azure_account_name>
      azure_container: <azure_container_name>
      storage_path: /datastorage/registry
      azure_account_key: <azure_account_key>
      sas_token: some/path/
      endpoint_url: https://[account-name].blob.core.usgovcloudapi.net
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - azureStorage
DISTRIBUTED_STORAGE_CONFIG.azureStorage.endpoint_url

Specifies the endpoint URL for Azure storage. This parameter is optional and can be used with Microsoft Azure Government (MAG) endpoints. If left blank, the endpoint_url connects to the normal Azure region.

You must use the Primary endpoint of your MAG Blob service. Using the Secondary endpoint of your MAG Blob service results in the following error: AuthenticationErrorDetail:Cannot find the claimed account when trying to GetProperties for the account whusc8-secondary.

Additional resources

Swift object storage

You can configure Project Quay to use Red Hat OpenStack Platform (RHOSP) Swift object storage as a backend. Use this example to set authentication credentials, container details, and tenant options.

Swift object storage example
DISTRIBUTED_STORAGE_CONFIG:
  swiftStorage:
    - SwiftStorage
    - swift_user: <swift_username>
      swift_password: <swift_password>
      swift_container: <swift_container>
      auth_url: https://example.org/swift/v1/quay
      auth_version: 3
      os_options:
        tenant_id: <osp_tenant_id>
        user_domain_name: <osp_domain_name>
      ca_cert_path: /conf/stack/swift.cert
      storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - swiftStorage
Additional resources

Nutanix Objects Storage

You can configure Project Quay to use Nutanix Objects Storage as an object storage backend. Use this example to set credentials, bucket details, and connection options for private cloud infrastructure.

Nutanix Objects Storage example
DISTRIBUTED_STORAGE_CONFIG:
  nutanixStorage: # storage config name
    - RadosGWStorage # actual driver
    - access_key: <access_key>
      secret_key: <secret_key>
      bucket_name: <bucket_name>
      hostname: <hostname>
      is_secure: 'true'
      port: '443'
      storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE: # must contain name of the storage config
    - nutanixStorage
Additional resources

IBM Cloud Object Storage

You can configure Project Quay to use IBM Cloud Object Storage as an object storage backend. Use this example to set credentials, bucket details, and optional chunk size parameters.

IBM Cloud Object Storage
DISTRIBUTED_STORAGE_CONFIG:
  default:
  - IBMCloudStorage # actual driver
  - access_key: <access_key> # parameters
    secret_key: <secret_key>
    bucket_name: <bucket_name>
    hostname: <hostname>
    is_secure: 'true'
    port: '443'
    storage_path: /datastorage/registry
    maximum_chunk_size_mb: 100mb
    minimum_chunk_size_mb: 5mb
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS:
- default
DISTRIBUTED_STORAGE_PREFERENCE:
- default

where:

DISTRIBUTED_STORAGE_CONFIG.default.maximum_chunk_size_mb

Specifies the maximum chunk size. Recommended to be set to 100mb. This field is optional.

DISTRIBUTED_STORAGE_CONFIG.default.minimum_chunk_size_mb

Specifies defaults to 5mb. Do not adjust this field without consulting Red Hat Support in Additional resources, because it can have unintended consequences. This field is optional.

Additional resources

NetApp ONTAP S3 object storage

You can configure Project Quay to use NetApp ONTAP S3 as an object storage backend. Use this example to set credentials, bucket details, and connection options.

Netapp ONTAP S3 example
DISTRIBUTED_STORAGE_CONFIG:
  local_us:
  - RadosGWStorage
  - access_key: <access_key>
    bucket_name: <bucket_name>
    hostname: <host_url_address>
    is_secure: true
    port: <port>
    secret_key: <secret_key>
    storage_path: /datastorage/registry
    signature_version: v4
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS:
- local_us
DISTRIBUTED_STORAGE_PREFERENCE:
- local_us
Additional resources

Hitachi Content Platform object storage

You can configure Project Quay to use Hitachi Content Platform (HCP) as an object storage backend. Use this example to set credentials, bucket details, and connection options.

HCP storage configuration example
DISTRIBUTED_STORAGE_CONFIG:
  hcp_us:
  - RadosGWStorage
  - access_key: <access_key>
    bucket_name: <bucket_name>
    hostname: <hitachi_hostname_example>
    is_secure: true
    secret_key: <secret_key>
    storage_path: /datastorage/registry
    signature_version: v4
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS:
- hcp_us
DISTRIBUTED_STORAGE_PREFERENCE:
- hcp_us
Additional resources

Configure Red Hat Quay database and Redis backends

Configure Red Hat Quay settings for red hat quay database and redis backends.

Database configuration fields

You must configure database connectivity for Project Quay by setting the DB_URI field. You can optionally define connection settings such as SSL/TLS behavior by using DB_CONNECTION_ARGS.

Database URI

You configure the database connection for Project Quay by setting the required DB_URI field.

The following table describes the DB_URI configuration field:

Table 5. Database URI
Field Type Description

DB_URI (Required)

String

The URI for accessing the database, including any credentials.
Database URI example
# ...
DB_URI: postgresql://quayuser:quaypass@quay-server.example.com:5432/quay
# ...

Database connection arguments

You can define optional connection arguments by using the DB_CONNECTION_ARGS parameter. Some of the key-value pairs under DB_CONNECTION_ARGS are generic, while others are database specific.

Table 6. 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. Should always be True.

.threadlocals

Boolean

Whether to use auto-rollback connections. Should always be True.
Database connection arguments example
# ...
DB_URI: postgresql://quayuser:quaypass@quay-server.example.com:5432/quay
DB_CONNECTION_ARGS:
  autorollback: true
  threadlocals: true
# ...

SSL/TLS connection arguments

With SSL/TLS, configuration depends on the database you are deploying.

The sslmode option determines whether Project Quay negotiates a secure SSL/TLS TCP/IP connection with the server, and with what priority. The following modes are available:

Table 7. sslmode options
Mode Description

sslmode

Determines whether, or with, what priority a secure SSL/TLS or TCP/IP connection is negotiated with the server.

   *: 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     (Default)

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 in Additional resources.

PostgreSQL SSL/TLS configuration
# ...
DB_CONNECTION_ARGS:
  sslmode: <value>
  sslrootcert: path/to/.postgresql/root.crt
# ...
Additional resources

Redis configuration fields

Redis is used by Project Quay to support backend tasks and services, such as build triggers and notifications. There are configuration types related to Redis: build logs and user events. The following sections detail the configuration fields available for each type.

Build logs

Project Quay uses Redis to temporarily store build logs before they are accessed through the user interface or API. Use this reference to configure Redis connection settings for build log caching.

Table 8. Build logs configuration fields
Field Type Description

BUILDLOGS_REDIS (Required)

Object

Redis connection details for build logs caching.

.host (Required)

String

The hostname at which Redis is accessible. Example: quay-server.example.com

.port (Required)

Number

The port at which Redis is accessible. Example: 6379

.password

String

The password to connect to the Redis instance. Example: strongpassword

.ssl (Optional)

Boolean

Whether to enable TLS communication between Redis and Quay. Defaults to false.
Build logs configuration example
# ...
BUILDLOGS_REDIS:
  host: <quay-server.example.com>
  password: <example_password>
  port: 6379
  ssl: true
# ...

If your deployment uses Azure Cache for Redis and ssl is set to True, the port defaults to 6380.

User events

User events record activity in Project Quay and store it in Redis for access through the API or web interface. Use these fields to configure the Redis connection for user event handling.

Table 9. User events config
Field Type Description

USER_EVENTS_REDIS (Required)

Object

Redis connection details for user event handling.

.host (Required)

String

The hostname at which Redis is accessible. Example: quay-server.example.com.

.port (Required)

Number

The port at which Redis is accessible. Example: 6379.

.password

String

The password to connect to the Redis instance. Example: strongpassword.

.ssl

Boolean

Whether to enable TLS communication between Redis and Quay. Defaults to false.

.ssl_keyfile (Optional)

String

The key database file that contains the client certificate key. Example: ssl_keyfile: /path/to/server/privatekey.pem.

.ssl_certfile (Optional)

String

The file path of the SSL certificate. Example: ssl_certfile: /path/to/server/certificate.pem.

.ssl_cert_reqs (Optional)

String

The certificate validation level to use during the SSL/TLS handshake. Example: ssl_cert_reqs: CERT_REQUIRED.

.ssl_ca_certs (Optional)

String

The path to a file containing trusted CA certificates. Example: ssl_ca_certs: /path/to/ca_certs.pem.

.ssl_ca_data (Optional)

String

A string that contains trusted CA certificates in PEM format. Example: ssl_ca_data: <certificate>.

.ssl_check_hostname (Optional)

Boolean

Whether the client checks that the hostname in the server SSL/TLS certificate matches the hostname of the server it connects to. Example: ssl_check_hostname: true.
Redis user events example
# ...
USER_EVENTS_REDIS:
  host: <quay-redis.example.com>
  port: 6379
  password: <example_password>
  ssl: true
  ssl_keyfile: /etc/ssl/private/redis-client.key
  ssl_certfile: /etc/ssl/certs/redis-client.crt
  ssl_cert_reqs: <required_certificate>
  ssl_ca_certs: /etc/ssl/certs/ca-bundle.crt
  ssl_check_hostname: true
# ...

Using an external PostgreSQL database

Using an external PostgreSQL database with Project Quay lets you manage your own database infrastructure instead of using the Operator-managed database. You must ensure that required configuration and extensions, such as pg_trgm, are in place before deployment.

If you use the Operator-managed PostgreSQL database and require encryption in transit, you can enable TLS on the postgres component without switching to an external database. For more information, see "TLS encryption for Operator-managed PostgreSQL".

Important

Do not share the same PostgreSQL database between Project Quay and Clair deployments. Each service must use its own database instance. Sharing databases with other workloads is also not supported, because connection-intensive components such as Project Quay and Clair can quickly exceed PostgreSQL’s connection limits.

Connection poolers such as pgBouncer are not supported with Project Quay or Clair.

When managing your own PostgreSQL database for use with Project Quay, the following best practices are recommended:

  • pg_trgm extension: The pg_trgm extension must be enabled on the database for a successful deployment.

  • Backups: Perform regular database backups using PostgreSQL-native tools or your existing backup infrastructure. The Project Quay Operator does not manage database backups.

  • Restores: When restoring a backup, ensure that all Project Quay pods are stopped before beginning the restore process.

  • Storage sizing: When using the Operator-managed PostgreSQL database, the default storage allocation is 50 GiB. For external databases, you must ensure sufficient storage capacity for your environment, as the Operator does not handle volume resizing.

  • Monitoring: Monitor disk usage, connection limits, and query performance to prevent outages caused by resource exhaustion.

Configuring an external PostgreSQL connection

To integrate an existing PostgreSQL database with your Project Quay registry, you can set the postgres component to unmanaged and configure the DB_URI in the configBundleSecret. This lets you leverage your current database infrastructure instead of using the Operator-managed database.

Note

The following procedure uses the OpenShift Container Platform web console to configure the Project Quay registry to use an external PostgreSQL database. For most users, use the web console is simpler.

This procedure can also be done by using the oc CLI and following the instructions in "Modifying the QuayRegistry CR by using the CLI" and " Modifying the configuration file by using the CLI".
Procedure

  1. On the OpenShift Container Platform web console, click Operators → Installed Operators.

  2. Click Red Hat Quay.

  3. Click Quay Registry.

  4. Click the name of your Project Quay registry, for example, example-registry.

  5. Click YAML.

  6. Set the postgres field of the QuayRegistry CR to managed: false. For example:

        - kind: postgres
      managed: false

  7. Click Save.

  8. Click Details → the name of your Config Bundle Secret resource.

  9. On the Secret Details page, click Actions → Edit Secret.

  10. Add the DB_URI field to your config.yaml file. For example:

    DB_URI: postgresql://test-quay-database:postgres@test-quay-database:5432/test-quay-database

  11. Optional: Add additional database configuration fields, such as DB_CONNECTION_ARGS or SSL/TLS connection arguments. For more information, see Database connection arguments.

  12. Click Save.

Configuring an external Redis connection

Using an external Redis database with Project Quay lets you manage your own Redis infrastructure instead of using the Operator-managed Redis. To integrate an existing Redis database with your Project Quay registry, you can set the redis component to unmanaged and configure BUILDLOGS_REDIS and USER_EVENTS_REDIS in the configBundleSecret resource.

Important

Do not share the same Redis instance between Project Quay and Clair deployments. Each service must use its own dedicated Redis instance. Sharing Redis with other workloads is not supported, because connection-intensive components such as Project Quay and Clair can quickly exhaust available Redis connections and degrade performance.
Procedure

  1. In the OpenShift Container Platform web console, navigate to Operators → Installed Operators.

  2. Click Red Hat Quay.

  3. Click QuayRegistry.

  4. Click the name of your Project Quay registry, for example, example-registry.

  5. Click YAML.

  6. Set the redis component to unmanaged by adding the following entry under spec.components:

        - kind: redis
      managed: false

  7. Click Save.

  8. Click Details → the name of your Config Bundle Secret resource.

  9. On the Secret details page, click Actions → Edit Secret.

  10. In the config.yaml section, add entries for your external Redis instance. For example:

    BUILDLOGS_REDIS:
  host: redis.example.com
  port: 6379
  ssl: false

USER_EVENTS_REDIS:
  host: redis.example.com
  port: 6379
  ssl: false
    Important

    If both the BUILDLOGS_REDIS and USER_EVENTS_REDIS fields reference the same Redis deployment, ensure that your Redis service can handle the combined connection load. For large or high-throughput registries, use separate Redis databases or clusters for these components.

  11. Optional: Add additional database configuration fields, such as DB_CONNECTION_ARGS or SSL/TLS connection arguments. For more information, see Redis configuration fields.

  12. Click Save.

Configure AWS STS for object storage

Configure AWS Security Token Service (STS) for Amazon S3 object storage on standalone Red Hat Quay deployments.

Configuring Project Quay to use AWS STS

To configure Project Quay to use AWS STS for Amazon S3 storage, you can update the DISTRIBUTED_STORAGE_CONFIG block in your config.yaml file and restart the registry.

Procedure

  1. Update your config.yaml file for Project Quay to include the following information:

    # ...
DISTRIBUTED_STORAGE_CONFIG:
   default:
    - STSS3Storage
    - sts_role_arn: <role_arn>
      s3_bucket: <s3_bucket_name>
      storage_path: <storage_path>
      s3_region: <region>
      sts_user_access_key: <s3_user_access_key>
      sts_user_secret_key: <s3_user_secret_key>
# ...

    where:

    sts_role_arn

    Specifies the unique Amazon Resource Name (ARN) required when configuring AWS STS.

    s3_bucket

    Specifies the name of your S3 bucket.

    storage_path

    Specifies the storage path for data. Usually /datastorage.

    s3_region

    Specifies the Amazon Web Services region. Defaults to us-east-1.

    sts_user_access_key

    Specifies the generated AWS S3 user access key required when configuring AWS STS.

    sts_user_secret_key

    Specifies the generated AWS S3 user secret key required when configuring AWS STS.

  2. Restart your Project Quay deployment.

Verification

  1. Tag a sample image, for example, busybox, that you push to the repository. For example:

    $ podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/busybox:test

  2. Push the sample image by running the following command:

    $ podman push <quay-server.example.com>/<organization_name>/busybox:test

  3. Verify that the push was successful by navigating to the Organization that you pushed the image to in your Project Quay registry → Tags.

  4. Navigate to the Amazon Web Services (AWS) console and locate your S3 bucket.

  5. Click the name of your S3 bucket.

  6. On the Objects page, click datastorage/.

  7. On the datastorage/ page, the following resources should appear:

    • sha256/

    • uploads/

      These resources indicate that the push was successful, and that AWS STS is properly configured.

Additional resources

Core, web UI, and user configuration fields

Optional configuration fields for core registry behavior, IPv6, debugging, registry state, the web UI, session logout, and user and robot account settings.

Core configuration overview

The following core configuration fields set the registry hostname, protocol, authentication, and other fundamental Project Quay behavior.

Registry branding and identity fields

Customize registry branding, contact information, and footer links that appear in the Project Quay user interface.

The following configuration fields allow you to modify the branding, identity, and contact information displayed in your Project Quay deployment. With these fields, you can customize how the registry appears to users by specifying titles, headers, footers, and organizational contact links shown throughout the UI.

Note

Some of the following fields are not available on the Project Quay v2 UI.
Table 10. Registry branding and identity configuration fields
Field Type Description

REGISTRY_TITLE

String

If specified, the long-form title for the registry. Displayed in frontend of your Project Quay deployment, for example, at the sign in page of your organization. Should not exceed 35 characters. Default: Red Hat Quay

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. Default: Red Hat Quay

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. Pattern: ^mailto:(.)+$ Example: mailto:support@quay.io

[1]

String

Adds a link to visit an IRC chat room. Pattern: ^irc://(.)+$ Example: irc://chat.freenode.net:6665/quay

[2]

String

Adds a link to call a phone number. Pattern: ^tel:(.)+$ Example: tel:+1-888-930-3475

[3]

String

Adds a link to a defined URL. Pattern: ^http(s)?://(.)+$ Example: https://twitter.com/quayio
Table 11. Branding configuration fields
Field Type Description

BRANDING

Object

Custom branding for logos and URLs in the Project Quay UI.

.logo (Required)

String

Main logo image URL. The header logo defaults to 205x30 PX. The form logo on the Project Quay sign in screen of the web UI defaults to 356.5x39.7 PX. Example: /static/img/quay-horizontal-color.svg

.footer_img

String

Logo for UI footer. Defaults to 144x34 PX. Example: /static/img/RedHat.svg

.footer_url

String

Link for footer image. Example: https://redhat.com
Table 12. Footer links configuration fields
Field Type Description

FOOTER_LINKS

Object

Enable customization of footer links in Project Quay’s UI for on-prem installations.

.TERMS_OF_SERVICE_URL

String

Custom terms of service for on-prem installations. Example: https://index.hr

.PRIVACY_POLICY_URL

String

Custom privacy policy for on-prem installations. Example: https://example.hr

.SECURITY_URL

String

Custom security page for on-prem installations. Example: https://example.hr

.ABOUT_URL

String

Custom about page for on-prem installations. Example: https://example.hr
Registry branding and identity example YAML
# ...
REGISTRY_TITLE: "Example Container Registry"
REGISTRY_TITLE_SHORT: "Example Quay"
CONTACT_INFO:
  - mailto:support@example.io
  - irc://chat.freenode.net:6665/examplequay
  - tel:+1-800-555-1234
  - https://support.example.io
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/
FOOTER_LINKS:
  "TERMS_OF_SERVICE_URL": "https://www.index.hr"
  "PRIVACY_POLICY_URL": "https://www.example.hr"
  "SECURITY_URL": "https://www.example.hr"
  "ABOUT_URL": "https://www.example.hr"
# ...

IPv6 configuration field

Use the FEATURE_LISTEN_IP_VERSION field to configure whether Project Quay listens on IPv4, IPv6, or dual-stack networks.

You can use the FEATURE_LISTEN_IP_VERSION configuration field to specify which IP protocol family Project Quay should listen on: IPv4, IPv6, or both (dual-stack). This field is critical in environments where the registry must operate on IPv6-only or dual-stack networks.

Table 13. 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 Project Quay fails to start. Default: IPv4 Additional configurations: IPv6, dual-stack
IPv6 example YAML
# ...
FEATURE_LISTEN_IP_VERSION: dual-stack
# ...
Additional resources

Logging and debugging variables

Configure logging, debugging, and health check variables for troubleshooting Project Quay.

The following variables control how Project Quay logs events, exposes debugging information, and interacts with system health checks. These settings are useful for troubleshooting and monitoring your registry

Table 14. Logging and debug configuration variables
Variable Type Description

DEBUGLOG

Boolean

Whether to enable or disable debug logs.

USERS_DEBUG

Integer. Either 0 or 1.

Used to debug LDAP operations in clear text, including passwords. Must be used with DEBUGLOG=TRUE.

+

Important

Setting USERS_DEBUG=1 exposes credentials in clear text. This variable should be removed from the Project Quay deployment after debugging. The log file that is generated with this environment variable should be scrutinized, and passwords should be removed before sending to other users. Use with caution.

ALLOW_PULLS_WITHOUT_STRICT_LOGGING

Boolean

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. Default: False

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

HEALTH_CHECKER

String

The configured health check Example: ('RDSAwareHealthCheck', {'access_key': 'foo', 'secret_key': 'bar'})

FEATURE_AGGREGATED_LOG_COUNT_RETRIEVAL

Boolean

Whether to allow retrieval of aggregated log counts Default: True
Logging and debugging example YAML
#...
DEBUGLOG: true
USERS_DEBUG: 1
ALLOW_PULLS_WITHOUT_STRICT_LOGGING: "true"
ENABLE_HEALTH_DEBUG_SECRET: "<secret_value>"
HEALTH_CHECKER: "('RDSAwareHealthCheck', {'access_key': 'foo', 'secret_key': 'bar'})"
FEATURE_AGGREGATED_LOG_COUNT_RETRIEVAL: true
# ...
Additional resources

Registry state and system behavior configuration fields

The following configuration fields control Project Quay registry operational state, including read-only mode and webhook hostname restrictions.

Table 15. Registry state and system behavior configuration fields
Field Type Description

REGISTRY_STATE

String

The state of the registry. Values: normal or read-only

WEBHOOK_HOSTNAME_BLACKLIST

Array of String

The set of hostnames to disallow from webhooks when validating, beyond localhost
Registry state and system behavior example YAML
# ...
REGISTRY_STATE: normal
WEBHOOK_HOSTNAME_BLACKLIST:
  - "169.254.169.254"
  - "internal.example.com"
  - "127.0.0.2"
# ...
Additional resources

User Experience and Interface

The following fields configure how users interact with the UI, including branding, pagination, browser behavior, and accessibility options like recaptcha. This also covers user-facing performance and display settings.

Web UI and user experience configuration fields

The following configuration fields control the behavior and appearance of the Project Quay web interface and overall user experience. Options in this section allow administrators to customize login behavior, avatar display, user autocomplete, session handling, and catalog visibility.

Table 16. Web UI and UX configuration fields
Field Type Description

AVATAR_KIND

String

The types of avatars to display, either generated inline (local) or Gravatar (gravatar) Values: local, gravatar

FRESH_LOGIN_TIMEOUT

String

The time after which a fresh login requires users to re-enter their password Example: 5m

FEATURE_UI_V2

Boolean

When set, allows users to try the v2 beta UI environment.

Default: True

FEATURE_UI_V2_REPO_SETTINGS

Boolean

When set to True, enables repository settings in the Project Quay v2 UI.

Default: False

FEATURE_DIRECT_LOGIN

Boolean

Whether users can directly login to the UI

Default: True

FEATURE_PARTIAL_USER_AUTOCOMPLETE

Boolean

If set to true, autocompletion will apply to partial usernames+

Default: True

FEATURE_LIBRARY_SUPPORT

Boolean

Whether to allow for "namespace-less" repositories when pulling and pushing from Docker

Default: True

FEATURE_PERMANENT_SESSIONS

Boolean

Whether sessions are permanent

Default: True

FEATURE_PUBLIC_CATALOG

Boolean

If set to true, the _catalog endpoint returns public repositories. Otherwise, only private repositories can be returned.

Default: False

DISABLE_ANGULAR_UI

Boolean

Disable legacy Angular UI pages and redirects.

Default: False

DEFAULT_UI

String

Allows Project Quay administrators the option to set the default UI to the angular theme (legacy) or react theme (v2 UI).

Options: react, angular
Example YAML
# ...
AVATAR_KIND: local
FRESH_LOGIN_TIMEOUT: 5m
FEATURE_UI_V2: true
FEATURE_UI_V2_REPO_SETTINGS: false
FEATURE_DIRECT_LOGIN: true
FEATURE_PARTIAL_USER_AUTOCOMPLETE: true
FEATURE_LIBRARY_SUPPORT: true
FEATURE_PERMANENT_SESSIONS: true
FEATURE_PUBLIC_CATALOG: false
# ...

Session timeout configuration field

The following configuration field sets how long permanent user sessions remain active in Project Quay before they expire.

This field relies on on the Flask API configuration field of the same name.

Important

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.
Table 17. Session logout configuration field
Field Type Description

PERMANENT_SESSION_LIFETIME

Integer

A timedelta which is used to set the expiration date of a permanent session. The default is 31 days, which makes a permanent session survive for roughly one month.

Default: 2678400
Session timeout example YAML
# ...
PERMANENT_SESSION_LIFETIME: 3000
# ...

User and Access Management

Use the following fields to configure how users are created, authenticated, and managed. This includes settings for superusers, account recovery, app-specific tokens, login behavior, and external identity providers like LDAP, OAuth, and OIDC.

User configuration fields

The user configuration fields define how user accounts behave in your Project Quay deployment. These fields enable control over user creation, access levels, metadata tracking, recovery options, and namespace management. You can also enforce restrictions, such as invite-only creation or superuser privileges, to match your organization’s governance and security policies.

Table 18. User configuration fields
Field Type Description

FEATURE_SUPER_USERS

Boolean

Whether superusers are supported

Default: True

FEATURE_USER_CREATION

Boolean

Whether users can be created (by non-superusers)

Default: True

FEATURE_USER_LAST_ACCESSED

Boolean

Whether to record the last time a user was accessed

Default: True

FEATURE_USER_LOG_ACCESS

Boolean

If set to true, users will have access to audit logs for their namespace

Default: False

FEATURE_USER_METADATA

Boolean

Whether to collect and support user metadata

Default: False

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.

Default: True

FEATURE_USER_RENAME

Boolean

If set to true, users can rename their own namespace.

Default: False

FEATURE_INVITE_ONLY_USER_CREATION

Boolean

Whether users being created must be invited by another user

Default: False

FRESH_LOGIN_TIMEOUT

String

The time after which a fresh login requires users to re-enter their password

Example: 5m

USERFILES_LOCATION

String

ID of the storage engine in which to place user-uploaded files

Example: s3_us_east

USERFILES_PATH

String

Path under storage in which to place user-uploaded files

Example: userfiles

USER_RECOVERY_TOKEN_LIFETIME

String

The length of time a token for recovering a user accounts is valid Pattern: ^[0-9]+(w|m|d|h|s)$

Default: 30m

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

FEATURE_SUPERUSERS_ORG_CREATION_ONLY

Boolean

Whether to only allow superusers to create organizations.

Default: False

FEATURE_SUPERUSER_CONFIGDUMP

Boolean

Enables a full config dump of the running Framework, environment and schema for validation.

Default: False

FEATURE_RESTRICTED_USERS

Boolean

When set to True with RESTRICTED_USERS_WHITELIST:

  • All normal users and superusers are restricted from creating organizations or content in their own namespace unless they are allowlisted via RESTRICTED_USERS_WHITELIST.

  • Restricted users retain their normal permissions within organizations based on team memberships.

Default: False

RESTRICTED_USERS_WHITELIST

String

When set with FEATURE_RESTRICTED_USERS: true, specific users are excluded from the FEATURE_RESTRICTED_USERS setting.

GLOBAL_READONLY_SUPER_USERS

String

When set, grants users of this list read access to all repositories, regardless of whether they are public repositories.
User example YAML
# ...
FEATURE_SUPER_USERS: true
FEATURE_USER_CREATION: true
FEATURE_INVITE_ONLY_USER_CREATION: false
FEATURE_USER_RENAME: true
FEATURE_SUPERUSERS_FULL_ACCESS: true
FEATURE_SUPERUSERS_ORG_CREATION_ONLY: false
FEATURE_SUPERUSER_CONFIGDUMP: true
FEATURE_RESTRICTED_USERS: true
RESTRICTED_USERS_WHITELIST:
      - user1
GLOBAL_READONLY_SUPER_USERS:
      - quayadmin
FRESH_LOGIN_TIMEOUT: "5m"
USER_RECOVERY_TOKEN_LIFETIME: "30m"
USERFILES_LOCATION: "s3_us_east"
USERFILES_PATH: "userfiles"
# ...

When the RESTRICTED_USERS_WHITELIST field is set, allowlisted 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.

Robot account configuration fields

The following configuration fields control whether robot account creation and interaction is allowed globally in Project Quay.

Table 19. Robot account configuration fields
Field Type Description

ROBOTS_DISALLOW

Boolean

When set to True, robot accounts are prevented from all interactions, as well as from being created
Default: False
Robot account disallow example YAML
# ...
ROBOTS_DISALLOW: true
# ...
Additional resources

Authentication, repository, and security configuration fields

Optional configuration fields for reCAPTCHA, JWT, application tokens, programmatic bootstrap, namespace and repository management, nested repositories, additional security policies, and registry search.

Recaptcha configuration fields

The following configuration fields enable Recaptcha protection for user login and account recovery forms in Project Quay.

Table 20. Recaptcha configuration fields
Field Type Description

FEATURE_RECAPTCHA

Boolean

Whether Recaptcha is necessary for user login and recovery

Default: False

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
Recaptcha example YAML
# ...
FEATURE_RECAPTCHA: true
RECAPTCHA_SITE_KEY: "<site_key>"
RECAPTCHA_SECRET_KEY: "<secret_key>"
# ...

JWT configuration fields

Project Quay can be configured to support external authentication using JSON Web Tokens (JWT). This integration allows third-party identity providers or token issuers to authenticate and authorize users by calling specific endpoints that handle token verification, user lookup, and permission queries.

Table 21. JWT configuration fields
Field Type Description

JWT_AUTH_ISSUER

String

The endpoint for JWT users Pattern: ^http(s)?://(.)+$ Example: http://192.168.99.101:6060

JWT_GETUSER_ENDPOINT

String

The endpoint for JWT users Pattern: ^http(s)?://(.)+$ Example: http://192.168.99.101:6060

JWT_QUERY_ENDPOINT

String

The endpoint for JWT queries Pattern: ^http(s)?://(.)+$ Example: http://192.168.99.101:6060

JWT_VERIFY_ENDPOINT

String

The endpoint for JWT verification Pattern: ^http(s)?://(.)+$ Example: http://192.168.99.101:6060
JWT example YAML
# ...
JWT_AUTH_ISSUER: "http://192.168.99.101:6060"
JWT_GETUSER_ENDPOINT: "http://192.168.99.101:6060/getuser"
JWT_QUERY_ENDPOINT: "http://192.168.99.101:6060/query"
JWT_VERIFY_ENDPOINT: "http://192.168.99.101:6060/verify"
# ...

App tokens configuration fields

App-specific tokens allow users to authenticate with Project Quay using token-based credentials. These fields might be useful for CLI tools like Docker.

Table 22. App tokens configuration fields
Field Type Description

FEATURE_APP_SPECIFIC_TOKENS

Boolean

If enabled, users can create tokens for use by the Docker CLI

Default: True

APP_SPECIFIC_TOKEN_EXPIRATION

String

The expiration for external app tokens.

Default None

Pattern: ^[0-9]+(w|m|d|h|s)$

EXPIRED_APP_SPECIFIC_TOKEN_GC

String

Duration of time expired external app tokens will remain before being garbage collected

Default: 1d
App tokens example YAML
# ...
FEATURE_APP_SPECIFIC_TOKENS: true
APP_SPECIFIC_TOKEN_EXPIRATION: "30d"
EXPIRED_APP_SPECIFIC_TOKEN_GC: "1d"
# ...

Programmatic bootstrap configuration fields

Use these configuration fields to control bootstrap OAuth token provisioning for automated Project Quay deployments. The feature remains disabled until you enable it. Standalone deployments store the token in a local file. Red Hat Quay on OpenShift Container Platform Operator deployments store the token in a Kubernetes Secret that the Operator creates and mounts.

Table 23. Programmatic bootstrap fields
Field Type Description

FEATURE_PROGRAMMATIC_BOOTSTRAP

Boolean

Enables programmatic bootstrap token provisioning. When true, Project Quay creates a bootstrap OAuth token on startup and writes it to a local file or Kubernetes Secret. When false, Project Quay revokes any existing bootstrap token on restart.

Default: false

BOOTSTRAP_TOKEN_OWNER

String

Username that owns the bootstrap OAuth application and token. Required when FEATURE_PROGRAMMATIC_BOOTSTRAP is true. The user must exist in the database and be listed in SUPER_USERS.

BOOTSTRAP_TOKEN_PATH

String

Filesystem path where the bootstrap token JSON is written on standalone and virtual machine deployments. In containerized deployments, use a mounted path that the Project Quay process can write, for example /datastorage/bootstrap-token.json.

Default: /var/lib/quay/quay-machine-token.json

BOOTSTRAP_TOKEN_EXPIRATION

Integer

Bootstrap token lifetime in seconds.

Default: 3600 (60 minutes)

BOOTSTRAP_TOKEN_SCOPE

String

Space-separated OAuth scopes assigned to the bootstrap token.

Default: org:admin repo:admin repo:create repo:read repo:write super:user user:admin user:read

PROGRAMMATIC_TOKEN_K8S_SECRET

String

Kubernetes Secret name used to store the bootstrap token when Project Quay runs in Kubernetes. When set, Project Quay writes the token to this Secret instead of BOOTSTRAP_TOKEN_PATH. On Red Hat Quay on OpenShift Container Platform, the Operator sets this field to <quayregistry_name>-bootstrap-token when programmatic bootstrap is enabled. Do not set this field manually in Operator-managed deployments.

PROGRAMMATIC_TOKEN_K8S_KEY

String

Secret data key that stores the bootstrap token JSON. On Red Hat Quay on OpenShift Container Platform, the Operator sets this field to token.json.

Default: token.json

PROGRAMMATIC_TOKEN_K8S_NAMESPACE

String

Kubernetes namespace that contains the bootstrap token Secret. When unset, Project Quay uses the pod service account namespace. On Red Hat Quay on OpenShift Container Platform, the Operator uses the QuayRegistry namespace.

PROGRAMMATIC_TOKEN_PATH

String

Operator-rendered mount path for configuration compatibility. On Red Hat Quay on OpenShift Container Platform, the Operator sets this field to /var/lib/quay/bootstrap-token/token.json. Standalone deployments use BOOTSTRAP_TOKEN_PATH for local file storage.
Programmatic bootstrap example YAML (standalone)
FEATURE_PROGRAMMATIC_BOOTSTRAP: true
SUPER_USERS:
  - quayadmin
BOOTSTRAP_TOKEN_OWNER: quayadmin
BOOTSTRAP_TOKEN_PATH: /var/lib/quay/quay-machine-token.json
BOOTSTRAP_TOKEN_EXPIRATION: 7776000
BOOTSTRAP_TOKEN_SCOPE: "org:admin repo:admin repo:create repo:read repo:write super:user user:admin user:read"
Programmatic bootstrap example YAML (Red Hat Quay on OpenShift Container Platform configBundleSecret)
FEATURE_PROGRAMMATIC_BOOTSTRAP: true
SUPER_USERS:
  - quayadmin
BOOTSTRAP_TOKEN_OWNER: quayadmin
BOOTSTRAP_TOKEN_EXPIRATION: 7776000
BOOTSTRAP_TOKEN_SCOPE: "org:admin repo:admin repo:create repo:read repo:write super:user user:admin user:read"
Note

For Operator deployments, omit BOOTSTRAP_TOKEN_PATH and the PROGRAMMATIC_TOKEN_K8S_* fields from the configBundleSecret. The Operator injects PROGRAMMATIC_TOKEN_K8S_SECRET, PROGRAMMATIC_TOKEN_K8S_KEY, and PROGRAMMATIC_TOKEN_PATH, and creates the <quayregistry_name>-bootstrap-token Secret, Role, and RoleBinding automatically.

Always quote BOOTSTRAP_TOKEN_SCOPE. Unquoted values that contain : can be misparsed by YAML.
Important

The bootstrap token is a high-privilege credential. Use it only to provision organizations, applications, and narrower-scoped OAuth tokens for automation. Do not use the bootstrap token for routine API operations.

For regulated environments, set BOOTSTRAP_TOKEN_EXPIRATION according to your token rotation policy and renew the token by using POST /api/v1/bootstrap/renew.

Namespace and repository management configuration fields

The following configuration fields govern how Project Quay manages namespaces and repositories, including behavior during automated image pushes, visibility defaults, and rate limiting exceptions.

Table 24. Namespace and repository management configuration fields
Field Type Description

DEFAULT_NAMESPACE_MAXIMUM_BUILD_COUNT

Number

The default maximum number of builds that can be queued in a namespace.

Default: None

CREATE_PRIVATE_REPO_ON_PUSH

Boolean

Whether new repositories created by push are set to private visibility

Default: True

CREATE_NAMESPACE_ON_PUSH

Boolean

Whether new push to a non-existent organization creates it

Default: False

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.

NON_RATE_LIMITED_NAMESPACES

Array of String

If rate limiting has been enabled using FEATURE_RATE_LIMITS, you can override it for specific namespace that require unlimited access.

DISABLE_PUSHES

Boolean

Disables pushes of new content to the registry while retaining all other functionality. Differs from read-only mode because database is not set as read-only. When DISABLE_PUSHES is set to True, the Project Quay garbage collector is disabled. As a result, when PERMANENTLY_DELETE_TAGS is enabled, using the Project Quay UI to permanently delete a tag does not result in the immediate deletion of a tag. Instead, the image stays in the backend storage until DISABLE_PUSHES is set to False, which re-enables the garbage collector. Project Quay administrators should be aware of this caveat when using DISABLE_PUSHES and PERMANENTLY_DELETE_TAGS together.

Default: False
Namespace and repository management example YAML
# ...
DEFAULT_NAMESPACE_MAXIMUM_BUILD_COUNT: 10
CREATE_PRIVATE_REPO_ON_PUSH: true
CREATE_NAMESPACE_ON_PUSH: false
PUBLIC_NAMESPACES:
  - redhat
  - opensource
  - infra-tools
NON_RATE_LIMITED_NAMESPACES:
  - ci-pipeline
  - trusted-partners
DISABLE_PUSHES: false
# ...

Nested repositories configuration fields

Support for nested repository path names has been added by 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.

Table 25. Nested repositories configuration fields
Field Type Description

FEATURE_EXTENDED_REPOSITORY_NAMES

Boolean

Enable support for nested repositories Default: True
Nested repositories example YAML
# ...
FEATURE_EXTENDED_REPOSITORY_NAMES: true
# ...

Additional security configuration fields

The following configuration fields provide additional security controls for your Project Quay deployment. These options allow administrators to enforce authentication practices, control anonymous access to content, require team invitations, and enable FIPS-compliant cryptographic functions for environments with enhanced security requirements.

Table 26. Additional security configuration fields
Feature Type Description

FEATURE_REQUIRE_TEAM_INVITE

Boolean

Whether to require invitations when adding a user to a team

Default: True

FEATURE_REQUIRE_ENCRYPTED_BASIC_AUTH

Boolean

Whether non-encrypted passwords (as opposed to encrypted tokens) can be used for basic auth

Default: False

FEATURE_ANONYMOUS_ACCESS

Boolean

Whether to allow anonymous users to browse and pull public repositories

Default: True

FEATURE_FIPS

Boolean

If set to true, Project Quay will run using FIPS-compliant hash functions

Default: False
Additional security example YAML
# ...
FEATURE_REQUIRE_TEAM_INVITE: true
FEATURE_REQUIRE_ENCRYPTED_BASIC_AUTH: false
FEATURE_ANONYMOUS_ACCESS: true
FEATURE_FIPS: false
# ...

The following configuration fields define how search results are paginated in the Project Quay user interface.

Table 27. Search configuration fields
Field Type Description

SEARCH_MAX_RESULT_PAGE_COUNT

Number

Maximum number of pages the user can paginate in search before they are limited

Default: 10

SEARCH_RESULTS_PER_PAGE

Number

Number of results returned per page by search page

Default: 10
Search example YAML
# ...
SEARCH_MAX_RESULT_PAGE_COUNT: 10
SEARCH_RESULTS_PER_PAGE: 10
# ...

Storage, image management, and metadata configuration fields

Optional configuration fields for storage and data management, image storage features, tag and image management, image activity tracking, tag expiration, immutable tags, repository and organization mirroring, model cache, and model card rendering.

Storage and Data Management

This section describes the configuration fields that govern how Project Quay stores, manages, and audits data.

Image storage features

The following configuration fields enable repository mirroring, storage proxying, and automatic storage replication features. These features allow you to enhance scalability, resilience, and flexibility when managing container image data.

Table 28. Storage configuration features
Field Type Description

FEATURE_REPO_MIRROR

Boolean

If set to true, enables repository mirroring.

Default: False

FEATURE_PROXY_STORAGE

Boolean

Whether to proxy all direct download URLs in storage through NGINX.

Default: False

FEATURE_STORAGE_REPLICATION

Boolean

Whether to automatically replicate between storage engines.

Default: False
Image storage example YAML
# ...
FEATURE_REPO_MIRROR: true
FEATURE_PROXY_STORAGE: false
FEATURE_STORAGE_REPLICATION: true
# ...

Tag and image management

The following configuration fields control how tags and images are managed within Project Quay. These settings help track image activity, automate image cleanup, and enforce tag policies.

You can use these fields to:

  • Track image pull activity and display statistics in the web UI.

  • Define expiration policies for untagged or outdated images.

  • Enable immutable tag policies to prevent tag overwrites.

These options help maintain an up-to-date image registry environment.

Image activity tracking configuration fields

The following configuration fields are available to track image activities. When enabled, clear visibility into how often and when image tags are pulled are provided in the UI.

Table 29. Image activity configuration fields
Field Type Description

FEATURE_IMAGE_PULL_STATS

Boolean

Whether to track and display image pull statistics.

Default: False

REDIS_FLUSH_INTERVAL_SECONDS

Integer

Interval, in seconds, at which the Redis flush worker clears old data. Shorter intervals keep data fresher and help prevent Redis from bloating, while longer intervals reduce flush frequency.

Default: 300 (5 minutes)

PULL_METRICS_REDIS

Object

Connection settings for the Redis database used to store image pull metrics. The host field specifies the Redis server hostname, and the optional db field identifies the Redis database index to use.

Default: {"host": "<redis_host>", "password": "<redis_password>", "port": "<port>", "db": 1}
Image activity tracking example YAML
# ...
FEATURE_IMAGE_PULL_STATS: true
REDIS_FLUSH_INTERVAL_SECONDS: 30
PULL_METRICS_REDIS:
    host: <redis_host>
    password: <redis_password>
    port: 6379
    db: 1
# ...

Tag expiration configuration fields

The following configuration fields are available to automate tag expiration and garbage collection. These features help manage storage usage by enabling cleanup of unused or expired tags based on defined policies.

Table 30. Tag expiration configuration fields
Field Type Description

FEATURE_GARBAGE_COLLECTION

Boolean

Whether garbage collection of repositories is enabled.

Default: True

TAG_EXPIRATION_OPTIONS (Required)

Array of string

If enabled, the options that users can select for expiration of tags in their namespace. Pattern: ^[0-9]+(y|w|m|d|h|s)$

DEFAULT_TAG_EXPIRATION (Required)

String

The default, configurable tag expiration time for time machine. Pattern: ^[0-9]+(y\w|m|d|h|s)$

Default: 2w

FEATURE_CHANGE_TAG_EXPIRATION

Boolean

Whether users and organizations are allowed to change the tag expiration for tags in their namespace.

Default: True

FEATURE_AUTO_PRUNE

Boolean

When set to True, enables functionality related to the auto-pruning of tags.

Default: False

NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES

Integer

The interval, in minutes, that defines the frequency to re-run notifications for expiring images.

Default: 300

DEFAULT_NAMESPACE_AUTOPRUNE_POLICY

Object

The default organization-wide auto-prune policy.

    .method: number_of_tags

Object

The option specifying the number of tags to keep.

    .value: <integer>

Integer

When used with method: number_of_tags, denotes the number of tags to keep. For example, to keep two tags, specify 2.

    .creation_date

Object

The option specifying the duration of which to keep tags.

    .value: <integer>

Integer

When used with creation_date, denotes how long to keep tags. Can be set to seconds (s), days (d), months (m), weeks (w), or years (y). Must include a valid integer. For example, to keep tags for one year, specify 1y.

AUTO_PRUNING_DEFAULT_POLICY_POLL_PERIOD

Integer

The period in which the auto-pruner worker runs at the registry level. By default, it is set to run one time per day (one time per 24 hours). Value must be in seconds.

FEATURE_IMAGE_EXPIRY_TRIGGER

Boolean

Allows users to set up notifications on image expiration. Notifications are only returned on the v2 UI.

Default: False
Example tag expiration example YAML
# ...
FEATURE_GARBAGE_COLLECTION: true
TAG_EXPIRATION_OPTIONS:
  - 1w
  - 2w
  - 1m
  - 90d
DEFAULT_TAG_EXPIRATION: 2w
FEATURE_CHANGE_TAG_EXPIRATION: true
FEATURE_AUTO_PRUNE: true
NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES: 300
DEFAULT_NAMESPACE_AUTOPRUNE_POLICY:
  method: number_of_tags
  value: 10
AUTO_PRUNING_DEFAULT_POLICY_POLL_PERIOD: 86400
FEATURE_IMAGE_EXPIRY_TRIGGER: false
# ...
DEFAULT_NAMESPACE_AUTOPRUNE_POLICY.value

Specifies ten tags to remain.

Registry auto-prune policy by creation date example YAML
# ...
DEFAULT_NAMESPACE_AUTOPRUNE_POLICY:
  method: creation_date
  value: 1y
# ...
DEFAULT_NAMESPACE_AUTOPRUNE_POLICY.value

Specifies tags to be pruned one year after their creation date.

Immutable tags configuration fields

The following configuration field is available to enable immutable tags. Immutable tag policies prevent tags from being overwritten in Project Quay.

Table 31. Immutable tags configuration field
Field Type Description

FEATURE_IMMUTABLE_TAGS

Boolean

Whether to enable immutability policies. Immutability can be set at the individual setting level and via a policy in the repository configuration by an administrator.

Default: False
Immutable tags example YAML
# ...
FEATURE_IMMUTABLE_TAGS: true
# ...

Mirroring configuration fields for repositories

Mirroring in Project Quay enables automatic synchronization of repositories with upstream sources. This feature is useful for maintaining local mirrors of remote container images, ensuring availability in disconnected environments or improving performance through caching.

Additional resources
Table 32. Mirroring configuration
Field Type Description

FEATURE_REPO_MIRROR

Boolean

Enable or disable repository mirroring.

Default: False

REPO_MIRROR_INTERVAL

Number

The number of seconds between checking for repository mirror candidates.

Default: 30

REPO_MIRROR_SERVER_HOSTNAME

String

Replaces the SERVER_HOSTNAME as the destination for mirroring.

Default: None

Example: openshift-quay-service

REPO_MIRROR_TLS_VERIFY

Boolean

Require HTTPS and verify certificates of Quay registry during mirror.

Default: True

REPO_MIRROR_ROLLBACK

Boolean

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

Default: False

FEATURE_SPARSE_INDEX

Boolean

Whether to allow sparse manifest indexes where not all architectures are required to be present.

Default: False

REPO_MIRROR_MAX_MANIFEST_LIST_SIZE

Integer

Maximum size in bytes of manifest list JSON to parse during mirroring. Prevents DoS via oversized manifests.

Default: 10485760 (10MB)

REPO_MIRROR_MAX_MANIFEST_ENTRIES

Integer

Maximum number of manifest entries to process during architecture-filtered mirroring. Prevents DoS via manifest lists with excessive entries. Default: 1000
Mirroring configuration example YAML
# ...
FEATURE_REPO_MIRROR: true
REPO_MIRROR_INTERVAL: 30
REPO_MIRROR_SERVER_HOSTNAME: "openshift-quay-service"
REPO_MIRROR_TLS_VERIFY: true
REPO_MIRROR_ROLLBACK: false
FEATURE_SPARSE_INDEX: true
REPO_MIRROR_MAX_MANIFEST_LIST_SIZE: 10485760
REPO_MIRROR_MAX_MANIFEST_ENTRIES: 1000
# ...

Organization mirroring configuration fields

The following configuration fields are used for organization-level mirroring intervals, batch sizes, and related proxy cache settings.

Table 33. Organization mirroring configuration fields
Field Type Description

FEATURE_ORG_MIRROR

Boolean

Enable or disable organization-level mirroring.

Default: False

ORG_MIRROR_INTERVAL

Integer

Worker processing interval in seconds.

Default: 30

ORG_MIRROR_BATCH_SIZE

Integer

Number of organization mirrors to process for each iteration. Default: 100

ORG_MIRROR_MAX_SYNC_DURATION

Integer

Maximum sync duration in seconds.

Default: 3600

ORG_MIRROR_DEFAULT_SKOPEO_TIMEOUT

Integer

Default skopeo timeout in seconds.

Default: 300

ORG_MIRROR_DISCOVERY_TIMEOUT

Integer

Discovery timeout in seconds.

Default: 600

ORG_MIRROR_MAX_REPOS_PER_ORG

Integer

Maximum repositories to discover for each organization.

Default: 10000

ORG_MIRROR_MAX_RETRIES

Integer

Maximum sync retries for a failure operation.

Default: 3

SSRF_ALLOWED_HOSTS

List

Allowed hosts for the Server Side Request Forgery (SSRF) protection. Use optional field to allow specific hosts to be accessed by the registry.

FEATURE_PROXY_CACHE

Boolean

Enables Project Quay to act as a pull through cache for upstream registries.

FEATURE_REPO_MIRROR

Boolean

Enable or disable repository mirroring.
Organization mirroring configuration example YAML
# ...
FEATURE_ORG_MIRROR: true
ORG_MIRROR_INTERVAL: 60
ORG_MIRROR_BATCH_SIZE: 100
ORG_MIRROR_MAX_SYNC_DURATION: 3600
ORG_MIRROR_DEFAULT_SKOPEO_TIMEOUT: 600
ORG_MIRROR_DISCOVERY_TIMEOUT: 600
ORG_MIRROR_MAX_REPOS_PER_ORG: 5000
ORG_MIRROR_MAX_RETRIES: 3
SSRF_ALLOWED_HOSTS:
    - harbor.example.lab
FEATURE_PROXY_CACHE: true
FEATURE_REPO_MIRROR: true
# ...

ModelCache configuration fields

ModelCache is a caching mechanism used by Project Quay to store accessed data and reduce database load. Quay supports multiple backends for caching, including the default Memcache, as well as Redis and Redis Cluster.

  • Memcache (default): requires no additional configuration.

  • Redis: can be configured as a single instance or with a read-only replica.

  • Redis Cluster: provides high availability and sharding for larger deployments.

Table 34. ModelCache configuration fields
Field Type Description

DATA_MODEL_CACHE_CONFIG.engine

String

The cache backend engine. Values: memcache, redis, rediscluster Default: memcache

.redis_config.primary.host

String

The hostname of the primary Redis instance when using the redis engine.

.redis_config.primary.port

Number

The port used by the primary Redis instance.

.redis_config.primary.password

String

The password for authenticating with the primary Redis instance. Only required if ssl is set to True.

.redis_config.primary.ssl

Boolean

Whether to use SSL/TLS for the primary Redis connection.

.redis_config.startup_nodes

Array of Map

For rediscluster engine. The list of initial Redis cluster nodes with host and port.

redis_config.password

String

Password used for authentication with the Redis cluster. Required if ssl is True.

.redis_config.read_from_replicas

Boolean

Whether to allow read operations from Redis cluster replicas.

.redis_config.skip_full_coverage_check

Boolean

If set to true, skips the Redis cluster full coverage check.

.redis_config.ssl

Boolean

Whether to use SSL/TLS for Redis cluster communication.

.replica.host

String

The hostname of the Redis replica instance. Optional.

.replica.port

Number

The port used by the Redis replica instance.

.replica.password

String

The password for the Redis replica. Required if ssl is True.

.replica.ssl

Boolean

Whether to use SSL/TLS for the Redis replica connection.
Single Redis with optional replica example YAML
# ...
DATA_MODEL_CACHE_CONFIG:
  engine: redis
  redis_config:
    primary:
      host: <redis-primary.example.com>
      port: 6379
      password: <redis_password>>
      ssl: true
    replica:
      host: <redis-replica.example.com>
      port: 6379
      password: <redis_password>
      ssl: true
# ...
Clustered Redis example YAML
# ...
DATA_MODEL_CACHE_CONFIG:
  engine: <rediscluster>
  redis_config:
    startup_nodes:
      - host: <redis-node-1.example.com>
        port: 6379
      - host: <redis-node-2.example.com>
        port: 6379
    password: <cluster_password>
    read_from_replicas: true
    skip_full_coverage_check: true
    ssl: true
# ...

Scanner and Metadata

The following configuration fields connect vulnerability scanning, model card metadata, and OCI artifact referrers in Project Quay.

These settings enable enhanced visibility and security by providing Project Quay with the following options:

  • Integrating with a vulnerability scanner to assess container images for known CVEs.

  • Rendering AI/ML model metadata through model cards stored in the registry.

  • Exposing relationships between container artifacts using the Referrers API, aligning with the OCI artifact specification.

Collectively, these features help improve software supply chain transparency, enforce security policies, and support emerging metadata-driven workflows.

Model card rendering configuration fields

The following configuration fields enable Project Quay to display Model Card metadata in the UI for OCI-compliant machine learning images. Model Cards are a form of metadata documentation commonly used in machine learning workflows to improve the visibility and management of model-related content within OCI-compliant images.

Table 35. Model card rendering configuration fields
Field Type Description

FEATURE_UI_MODELCARD

Boolean

Enables Model Card image tab in UI. Defaults to True.

UI_MODELCARD_ARTIFACT_TYPE

String

Defines the model card artifact type.

UI_MODELCARD_ANNOTATION

Object

This optional field defines the layer annotation of the model card stored in an OCI image.

UI_MODELCARD_LAYER_ANNOTATION

Object

This optional field defines the layer annotation of the model card stored in an OCI image.
Model card example YAML
FEATURE_UI_MODELCARD: true
UI_MODELCARD_ARTIFACT_TYPE: application/x-mlmodel
UI_MODELCARD_ANNOTATION:
  org.opencontainers.image.description: "Model card metadata"
UI_MODELCARD_LAYER_ANNOTATION:
  org.opencontainers.image.title: README.md

where:

FEATURE_UI_MODELCARD

Specifies enabling the Model Card image tab in the UI.

UI_MODELCARD_ARTIFACT_TYPE

Specifies the model card artifact type. In this example, the artifact type is application/x-mlmodel.

UI_MODELCARD_ANNOTATION

Specifies manifest-level annotation lookup when an image does not have an artifactType defined. If a matching annotation is found, the system then searches for a layer with an annotation matching UI_MODELCARD_LAYER_ANNOTATION. This field is optional.

UI_MODELCARD_LAYER_ANNOTATION

Specifies the layer annotation used to locate the specific layer containing the model card when an image has an artifactType defined and multiple layers. This field is optional.

Additional resources

Referrers, quota, proxy, integration, and mail configuration fields

Optional configuration fields for the Referrers API, quota management, proxy cache, third-party integration, and mail notifications.

Open Container Initiative referrers API configuration field

The following configuration field enables the OCI referrers API to retrieve and manage artifact referrers attached to container images. This configuration field can help improve container image management.

Additional resources
Table 36. Referrers API configuration field
Field Type Description

FEATURE_REFERRERS_API

Boolean

Enables OCI 1.1’s referrers API.
OCI referrers enablement example YAML
# ...
FEATURE_REFERRERS_API: True
# ...

Quota management and proxy cache features

The following configuration fields enforce storage quotas and enable proxy caching of upstream registry images in Project Quay.

These features help registry administrators with the following:

  • Controlling how much storage organizations and users consume with configurable quotas.

  • Improving access to upstream images by caching remote content locally via proxy cache.

  • Monitoring and managing resource consumption and availability across distributed environments.

Collectively, these capabilities ensure better performance, governance, and resiliency in managing container image workflows.

Additional resources

Quota management configuration fields

The following configuration fields enable and customize quota management functionality in Project Quay. Quota management helps administrators enforce storage usage policies at the organization level by allowing them to set usage limits, calculate blob sizes, and control tag deletion behavior.

Table 37. Quota management configuration
Field Type Description

FEATURE_QUOTA_MANAGEMENT

Boolean

Enables configuration, caching, and validation for quota management feature.

Default: false

FEATURE_QUOTA_NOTIFICATIONS

Boolean

Enables external notification channels, such as email, for quota threshold alerts. When enabled, namespace owners receive proactive notifications when storage consumption crosses configured warning or critical thresholds.

Default: false

FEATURE_MAILING

Boolean

Enables email delivery features across Project Quay. Must be true with SMTP server settings configured for email quota notifications to be delivered to contact email addresses or administrators.

Default: true

QUOTA_NOTIFICATION_COOLDOWN_SECONDS

Integer

Cooldown period in seconds before re-sending a quota notification for the same threshold (default: 86400 / 24 hours). The system prevents repeated notifications for the same namespace and threshold combination within this window. If storage usage drops below a threshold and later crosses the threshold again, the notification state is cleared and the notification will re-fire upon the new crossing. Notification claims (claim_notification()) are handled atomically in the backend to prevent notification storms caused by concurrent image pushes.

Default: 86400

QUOTA_NOTIFICATION_WORKER_POLL_PERIOD

Integer

How often, in seconds, the quota notification background worker polls for threshold crossings that occur between image pushes—for example, when an administrator lowers a quota limit. Default: 300 (5 minutes).

Default: 300

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: true

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: 1800

PERMANENTLY_DELETE_TAGS

Boolean

Enables functionality related to the removal of tags from the time machine window.

Default: false

RESET_CHILD_MANIFEST_EXPIRATION

Boolean

Resets the expirations of temporary tags targeting the child manifests. With this feature set to True, child manifests are immediately garbage collected.

Default: false
Quota management example YAML
# ...
FEATURE_QUOTA_MANAGEMENT: true
FEATURE_QUOTA_NOTIFICATIONS: true
DEFAULT_SYSTEM_REJECT_QUOTA_BYTES: "100gb"
QUOTA_BACKFILL: true
QUOTA_TOTAL_DELAY_SECONDS: 3600
QUOTA_NOTIFICATION_COOLDOWN_SECONDS: 86400
QUOTA_NOTIFICATION_WORKER_POLL_PERIOD: 300
PERMANENTLY_DELETE_TAGS: true
RESET_CHILD_MANIFEST_EXPIRATION: true
# ...

Proxy cache configuration fields

The following configuration field enables Project Quay to act as a pull-through cache for upstream container registries. When FEATURE_PROXY_CACHE is enabled, Project Quay can cache images that are pulled from external registries, reducing bandwidth consumption and improving image retrieval speed on subsequent requests.

Table 38. Proxy cache configuration fields
Field Type Description

FEATURE_PROXY_CACHE

Boolean

Enables Project Quay to act as a pull through cache for upstream registries.

Default: False
Proxy cache example YAML
# ...
FEATURE_PROXY_CACHE: true
# ...

QuayIntegration configuration fields

The QuayIntegration custom resource enables integration between your OpenShift Container Platform cluster and a Project Quay registry instance.

Additional resources
Table 39. QuayIntegration configuration fields
Name Description Schema

allowlistNamespaces (Optional)

A list of namespaces to include.

Array

clusterID (Required)

The ID associated with this cluster.

String

credentialsSecret.key (Required)

The secret containing credentials to communicate with the Quay registry.

Object

denylistNamespaces (Optional)

A list of namespaces to exclude.

Array

insecureRegistry (Optional)

Whether to skip TLS verification to the Quay registry

Boolean

quayHostname (Required)

The hostname of the Quay registry.

String

scheduledImageStreamImport (Optional)

Whether to enable image stream importing.

Boolean
QuayIntegration example CR
apiVersion: quay.redhat.com/v1
kind: QuayIntegration
metadata:
  name: example-quayintegration
spec:
  clusterID: 1df512fc-bf70-11ee-bb31-001a4a160100
  quayHostname: quay.example.com
  credentialsSecret:
    name: quay-creds-secret
    key: token
  allowlistNamespaces:
    - dev-team
    - prod-team
  denylistNamespaces:
    - test
  insecureRegistry: false
  scheduledImageStreamImport: true

Mail configuration fields

The following configuration fields allow Project Quay to connect to your SMTP server. With these fields, you can send account confirmation, password reset, and security alerts.

Table 40. Mail configuration fields
Field Type Description

FEATURE_MAILING

Boolean

Whether emails are enabled

Default: False

MAIL_DEFAULT_SENDER

String

If specified, the e-mail address used as the from when Project Quay sends e-mails. If none, defaults to support@quay.io

Example: support@example.com

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.

Example: smtp.example.com

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

Default: True
Mail example YAML
# ...
FEATURE_MAILING: true
MAIL_DEFAULT_SENDER: "support@example.com"
MAIL_SERVER: "smtp.example.com"
MAIL_PORT: 587
MAIL_USERNAME: "smtp-user@example.com"
MAIL_PASSWORD: "your-smtp-password"
MAIL_USE_TLS: true
# ...

SSL/TLS configuration fields

Reference SSL and TLS configuration fields for securing Red Hat Quay registry traffic.

SSL/TLS configuration fields

Configure SSL/TLS settings, hostname, cipher suites, and session cookie security for Project Quay.

Table 41. SSL configuration fields
Field Type Description

PREFERRED_URL_SCHEME

String

One of http or https. Note that users only set their PREFERRED_URL_SCHEME to http when there is no TLS encryption in the communication path from the client to Quay. Users must set their PREFERRED_URL_SCHEME`to `https when using a TLS-terminating load balancer, a reverse proxy (for example, Nginx), or when using Quay with custom SSL certificates directly. In most cases, the PREFERRED_URL_SCHEME should be https. Default: http

SERVER_HOSTNAME (Required)

String

The URL at which Project Quay is accessible, without the scheme Example: quay-server.example.com

SSL_CIPHERS

Array of String

If specified, the nginx-defined list of SSL ciphers to enabled and disabled Example: [ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES256-GCM-SHA384, DHE-RSA-AES128-GCM-SHA256, DHE-DSS-AES128-GCM-SHA256, kEDH+AESGCM, ECDHE-RSA-AES128-SHA256, ECDHE-ECDSA-AES128-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-ECDSA-AES128-SHA, ECDHE-RSA-AES256-SHA384, ECDHE-ECDSA-AES256-SHA384, ECDHE-RSA-AES256-SHA, ECDHE-ECDSA-AES256-SHA, DHE-RSA-AES128-SHA256, DHE-RSA-AES128-SHA, DHE-DSS-AES128-SHA256, DHE-RSA-AES256-SHA256, DHE-DSS-AES256-SHA, DHE-DSS-AES256-SHA, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, AES128-SHA, AES256-SHA, AES, !3DES", !aNULL, !eNULL, !EXPORT, DES, !RC4, MD5, !PSK, !aECDH, !EDH-DSS-DES-CBC3-SHA, !EDH-RSA-DES-CBC3-SHA, !KRB5-DES-CBC3-SHA]

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 Project Quay startup. Example: ['TLSv1','TLSv1.1','TLSv1.2', `TLSv1.3]`

SESSION_COOKIE_SECURE

Boolean

Whether the secure property should be set on session cookies Default: False Recommendation: Set to True for all installations using SSL

EXTERNAL_TLS_TERMINATION

Boolean

Set to True if TLS is supported, but terminated at a layer before Quay. Set to False when Quay is running with its own SSL certificates and receiving TLS traffic directly.
SSL configuration example YAML
# ...
PREFERRED_URL_SCHEME: https
SERVER_HOSTNAME: quay-server.example.com
SSL_CIPHERS:
  - ECDHE-RSA-AES128-GCM-SHA256
SSL_PROTOCOLS:
  - TLSv1.3
SESSION_COOKIE_SECURE: true
EXTERNAL_TLS_TERMINATION: true
# ...
Additional resources

Configure networking for Red Hat Quay

Configure IPv6 and dual-stack networking for standalone Project Quay deployments, and manage custom ingress, routes, and SSL/TLS for Operator deployments on OpenShift Container Platform.

IPv6 and dual-stack deployments

You can deploy standalone Project Quay on IPv6-only or dual-stack (IPv4 and IPv6) networks. Set FEATURE_LISTEN_IP_VERSION in your config.yaml file to enable the protocol family that your environment supports.

Some storage backends have known limitations on IPv6-only networks.

Enabling the IPv6 protocol family

To enable IPv6 support on your standalone Project Quay deployment, you can set FEATURE_LISTEN_IP_VERSION to IPv6 in your config.yaml file and restart the registry.

Warning

If your environment is configured for IPv4, but the FEATURE_LISTEN_IP_VERSION configuration field is set to IPv6, Project Quay fails to deploy.
Prerequisites

  • Your host and container software platform (Docker, Podman) must be configured to support IPv6.

Procedure

  1. In your deployment’s config.yaml file, add the FEATURE_LISTEN_IP_VERSION parameter and set it to IPv6, for example:

    FEATURE_GOOGLE_LOGIN: false
FEATURE_INVITE_ONLY_USER_CREATION: false
FEATURE_LISTEN_IP_VERSION: IPv6
FEATURE_MAILING: false
FEATURE_NONSUPERUSER_TEAM_SYNCING_SETUP: false

  2. Start, or restart, your Project Quay deployment.

  3. Check that your deployment is listening to IPv6 by entering the following command:

    $ curl <quay_endpoint>/health/instance
    Example output
    {"data":{"services":{"auth":true,"database":true,"disk_space":true,"registry_gunicorn":true,"service_key":true,"web_gunicorn":true}},"status_code":200}
Results

  • After you enable IPv6 in your deployment’s config.yaml file, you can use all Project Quay features as usual when your environment is configured for IPv6 and is not affected by known IPv6 limitations.

Enabling the dual-stack protocol family

To enable dual-stack (IPv4 and IPv6) support on your standalone Project Quay deployment, you can set FEATURE_LISTEN_IP_VERSION to dual-stack in your config.yaml file and restart the registry.

Prerequisites

  • Your host and container software platform (Docker, Podman) must be configured to support IPv6.

Procedure

  1. In your deployment’s config.yaml file, add the FEATURE_LISTEN_IP_VERSION parameter and set it to dual-stack, for example:

    FEATURE_GOOGLE_LOGIN: false
FEATURE_INVITE_ONLY_USER_CREATION: false
FEATURE_LISTEN_IP_VERSION: dual-stack
FEATURE_MAILING: false
FEATURE_NONSUPERUSER_TEAM_SYNCING_SETUP: false

  2. Start, or restart, your Project Quay deployment.

  3. Check that your deployment is listening on both channels by entering the following commands:

    1. For IPv4, enter the following command:

      $ curl --ipv4 <quay_endpoint>
      Example output
      {"data":{"services":{"auth":true,"database":true,"disk_space":true,"registry_gunicorn":true,"service_key":true,"web_gunicorn":true}},"status_code":200}

    2. For IPv6, enter the following command:

      $ curl --ipv6 <quay_endpoint>
      Example output
      {"data":{"services":{"auth":true,"database":true,"disk_space":true,"registry_gunicorn":true,"service_key":true,"web_gunicorn":true}},"status_code":200}
Results

  • After you enable dual-stack in your deployment’s config.yaml file, you can use all Project Quay features as usual when your environment is configured for dual-stack.

IPv6 and dual-stack limitations

On IPv6 single-stack environments, Azure Blob Storage and Amazon S3 CloudFront endpoints that do not support IPv6 prevent those storage configurations from working with Project Quay.

  • Currently, attempting to configure your Project Quay deployment with the common Azure Blob Storage configuration does not work on IPv6 single-stack environments. Because the endpoint of Azure Blob Storage does not support IPv6, no workaround exists for this issue.

  • Currently, attempting to configure your Project Quay deployment with Amazon S3 CloudFront does not work on IPv6 single-stack environments. Because the endpoint of Amazon S3 CloudFront does not support IPv6, no workaround exists for this issue.

Configuring custom ingress

You can configure custom ingress for Project Quay by disabling the Operator-managed route component and managing your own routes or ingress controllers. This configuration is useful when your environment requires a custom SSL/TLS setup, specific DNS naming conventions, or when Project Quay is deployed behind a load balancer or proxy that handles TLS termination.

The Project Quay Operator separates route management from SSL/TLS configuration by introducing a distinct tls component. You can therefore manage each independently, depending on whether Project Quay or the cluster should handle TLS termination. For more information about using SSL/TLS certificates with your deployment, see "Securing Project Quay".

Note

If you disable the managed route, you are responsible for creating and managing a Route, Ingress, or Service to expose Project Quay. Ensure that your DNS entry matches the SERVER_HOSTNAME configured in config.yaml.

Disabling the Route component

To prevent the Project Quay Operator from creating a route, you can set the route component to unmanaged in the QuayRegistry custom resource. You must then configure SSL/TLS handling in your config.yaml file.

Procedure

  1. In your quayregistry.yaml file, set the route component as managed: false:

    apiVersion: quay.redhat.com/v1
kind: QuayRegistry
metadata:
  name: example-registry
  namespace: quay-enterprise
spec:
  components:
    - kind: route
      managed: false

  2. In your config.yaml file, configure Project Quay to handle SSL/TLS. For example:

    # ...
EXTERNAL_TLS_TERMINATION: false
SERVER_HOSTNAME: example-registry-quay-quay-enterprise.apps.user1.example.com
PREFERRED_URL_SCHEME: https
# ...

    If the configuration is incomplete, the following error might appear:

    {
  "reason":"ConfigInvalid",
  "message":"required component `route` marked as unmanaged, but `configBundleSecret` is missing necessary fields"
}

Configuring SSL/TLS and routes

Configuring SSL/TLS and routes for Project Quay lets you control how TLS termination and route management work together. The tls component provides support for OpenShift Container Platform edge termination routes and enables independent control of route management and TLS certificate handling.

EXTERNAL_TLS_TERMINATION: true is the default, opinionated setting, which assumes the cluster manages TLS termination.

Note

  • When tls is managed, the cluster’s default wildcard certificate is used.

  • When tls is unmanaged, you must supply your own SSL/TLS certificate and key pair.

Multiple valid configurations are possible, as shown in the following table:

Table 42. Valid configuration options for TLS and routes
Option Route TLS Certs provided Result

My own load balancer handles TLS

Managed

Managed

No

Edge route using default cluster wildcard certificate

Project Quay handles TLS

Managed

Unmanaged

Yes

Passthrough route with certificates mounted in the Project Quay pod

Project Quay handles TLS

Unmanaged

Unmanaged

Yes

Certificates set inside the Project Quay pod; user must manually create a route

LDAP configuration fields

Reference LDAP configuration fields for directory authentication, team synchronization, and superuser access in Red Hat Quay.

LDAP configuration fields

The following configuration fields allow administrators to integrate Project Quay with an LDAP-based authentication system. When AUTHENTICATION_TYPE is set to LDAP, Project Quay can authenticate users against an LDAP directory and support additional, optional features such as team synchronization, superuser access control, restricted user roles, and secure connection parameters.

This section provides YAML examples for the following LDAP scenarios:

  • Basic LDAP configuration

  • LDAP restricted user configuration

  • LDAP superuser configuration

Additional resources
Table 43. LDAP configuration
Field Type Description

AUTHENTICATION_TYPE (Required)

String

Must be set to LDAP.

FEATURE_TEAM_SYNCING

Boolean

Whether to allow for team membership to be synced from a backing group in the authentication engine (OIDC, LDAP, or Keystone). Default: True

FEATURE_NONSUPERUSER_TEAM_SYNCING_SETUP

Boolean

If enabled, non-superusers can setup team syncrhonization.

Default: False

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.

LDAP_SECONDARY_USER_RDNS

Array of String

Provide Secondary User Relative DNs if there are multiple Organizational Units where user objects are located.

TEAM_RESYNC_STALE_TIME

String

If team syncing is enabled for a team, how often to check its membership and resync if necessary. Pattern: ^[0-9]+(w|m|d|h|s)$ Example: 2h

Default: 30m

LDAP_SUPERUSER_FILTER

String

Subset of the LDAP_USER_FILTER configuration field. When configured, allows Project Quay administrators the ability to configure Lightweight Directory Access Protocol (LDAP) users as superusers when Project Quay uses LDAP as its authentication provider.

With this field, administrators can add or remove superusers without having to update the Project Quay configuration file and restart their deployment.

This field requires that your AUTHENTICATION_TYPE is set to LDAP.

LDAP_GLOBAL_READONLY_SUPERUSER_FILTER

String

Subset of the LDAP_USER_FILTER configuration field. When configured, grants LDAP users who match this filter read access to all repositories, regardless of whether they are public. Project Quay evaluates this filter separately from LDAP_SUPERUSER_FILTER; matching users do not need to be LDAP superusers.

LDAP_RESTRICTED_USER_FILTER

String

Subset of the LDAP_USER_FILTER configuration field. When configured, allows Project Quay administrators the ability to configure Lightweight Directory Access Protocol (LDAP) users as restricted users when Project Quay uses LDAP as its authentication provider.

This field requires that your AUTHENTICATION_TYPE is set to LDAP.

FEATURE_RESTRICTED_USERS

Boolean

When set to True with LDAP_RESTRICTED_USER_FILTER active, only the listed users in the defined LDAP group are restricted.

Default: False

LDAP_TIMEOUT

Integer

Specifies the time limit, in seconds, for LDAP operations. This limits the amount of time an LDAP search, bind, or other operation can take. Similar to the -l option in ldapsearch, it sets a client-side operation timeout.

Default: 10

LDAP_NETWORK_TIMEOUT

Integer

Specifies the time limit, in seconds, for establishing a connection to the LDAP server. This is the maximum time Project Quay waits for a response during network operations, similar to the -o nettimeout option in ldapsearch.

Default: 10

FEATURE_LDAP_CACHING

Boolean

enable in-memory caching for LDAP permission check results (superuser, restricted user). Reduces LDAP server load.

Default: False

LDAP_CACHE_TTL

Integer

Time-to-live, in seconds, for cached LDAP permission results.

Default: 60
Basic LDAP configuration example YAML
# ...
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:
  - dc=example
  - dc=com
LDAP_EMAIL_ATTR: mail
LDAP_UID_ATTR: uid
LDAP_URI: ldap://<example_url>.com
LDAP_USER_FILTER: (memberof=cn=developers,ou=Users,dc=<domain_name>,dc=com)
LDAP_USER_RDN:
  - ou=people
LDAP_SECONDARY_USER_RDNS:
    - ou=<example_organization_unit_one>
    - ou=<example_organization_unit_two>
    - ou=<example_organization_unit_three>
    - ou=<example_organization_unit_four>
FEATURE_LDAP_CACHING: true
LDAP_CACHE_TTL: 10

where:

AUTHENTICATION_TYPE

Specifies LDAP for LDAP authentication type.

LDAP_ADMIN_DN

Specifies the admin DN for LDAP authentication. This field is required.

LDAP_ADMIN_PASSWD

Specifies the admin password for LDAP authentication. This field is required.

LDAP_ALLOW_INSECURE_FALLBACK

Specifies whether to allow SSL/TLS insecure fallback for LDAP authentication. This field is required.

LDAP_BASE_DN

Specifies the base DN for LDAP authentication. This field is required.

LDAP_EMAIL_ATTR

Specifies the email attribute for LDAP authentication. This field is required.

LDAP_UID_ATTR

Specifies the UID attribute for LDAP authentication. This field is required.

LDAP_URI

Specifies the LDAP URI. This field is required.

LDAP_USER_FILTER

Specifies the user filter for LDAP authentication. This field is required.

LDAP_USER_RDN

Specifies the user RDN for LDAP authentication. This field is required.

LDAP_SECONDARY_USER_RDNS

Specifies secondary User Relative DNs if there are multiple Organizational Units where user objects are located. This field is optional.

FEATURE_LDAP_CACHING

Specifies whether to enable in-memory caching for LDAP permission check results (superuser, restricted user). Reduces LDAP server load. Defaults to False. This field is optional.

LDAP_CACHE_TTL

Specifies the time-to-live, in seconds, for cached LDAP permission results. Defaults to 60.

LDAP restricted user configuration example YAML
# ...
AUTHENTICATION_TYPE: LDAP
# ...
FEATURE_RESTRICTED_USERS: true
# ...
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
FEATURE_LDAP_CACHING: true
LDAP_CACHE_TTL: 10
# ...

where:

FEATURE_RESTRICTED_USERS

Specify True when configuring an LDAP restricted user.

LDAP_RESTRICTED_USER_FILTER

Specifies configured users as restricted users.

LDAP superuser configuration reference example YAML
# ...
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
FEATURE_LDAP_CACHING: true
LDAP_CACHE_TTL: 10
# ...
LDAP_SUPERUSER_FILTER

Specify configured users as superusers.

You can find the full list of LDAP configuration fields for Project Quay in the Configure Project Quay documentation.

Additional resources

OAuth and OIDC configuration fields

Reference OAuth and OIDC configuration fields for external authentication in Red Hat Quay.

OAuth configuration fields

The following configuration fields define the behavior of Project Quay when handling authentication through external identity providers using OAuth. You can configure global OAuth options such as token assignment and whitelisted client IDs, as well as provider-specific settings for GitHub and Google.

Table 44. OAuth 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.

FEATURE_ASSIGN_OAUTH_TOKEN

Boolean

Allows organization administrators to assign OAuth tokens to other users.
Global OAuth example YAML
# ...
DIRECT_OAUTH_CLIENTID_WHITELIST:
  - <quay_robot_client>
  - <quay_app_token_issuer>
FEATURE_ASSIGN_OAUTH_TOKEN: true
# ...
Table 45. GitHub OAuth configuration fields
Field Type Description

FEATURE_GITHUB_LOGIN

Boolean

Whether GitHub login is supported

Default: False

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 Example: https://api.github.com/

   .CLIENT_ID    (Required)

String

The registered client ID for this Project Quay instance; cannot be shared with GITHUB_TRIGGER_CONFIG. Example: <client_id>

   .CLIENT_SECRET    (Required)

String

The registered client secret for this Project Quay instance. Example: <client_secret>

   .GITHUB_ENDPOINT    (Required)

String

The endpoint for GitHub (Enterprise).

Example: https://github.com/

   .ORG_RESTRICT

Boolean

If true, only users within the organization whitelist can login using this provider.
Github OAth example YAML
# ...
FEATURE_GITHUB_LOGIN: true
GITHUB_LOGIN_CONFIG:
  ALLOWED_ORGANIZATIONS:
    - <myorg>
    - <dev-team>
  API_ENDPOINT: <https://api.github.com/>
  CLIENT_ID: <client_id>
  CLIENT_SECRET: <client_secret>
  GITHUB_ENDPOINT: <https://github.com/>
  ORG_RESTRICT: true
# ...
Table 46. Google OAuth configuration fields
Field Type Description

FEATURE_GOOGLE_LOGIN

Boolean

Whether Google login is supported.

Default: False

GOOGLE_LOGIN_CONFIG

Object

Configuration for using Google for external authentication.

   .CLIENT_ID    (Required)

String

The registered client ID for this Project Quay instance.

Example: <client_id>

   .CLIENT_SECRET    (Required)

String

The registered client secret for this Project Quay instance.

Example: <client_secret>
Google OAuth example YAML
# ...
FEATURE_GOOGLE_LOGIN: true
GOOGLE_LOGIN_CONFIG:
  CLIENT_ID: <client_id>
  CLIENT_SECRET: <client_secret>
# ...
Additional resources

OIDC configuration fields

Configure OpenID Connect client credentials, endpoints, and token behavior for Project Quay login.

You can configure Project Quay to authenticate users through any OpenID Connect (OIDC)-compatible identity provider, including Azure Entra ID (formerly Azure AD), Okta, Keycloak, and others. These fields define the necessary client credentials, endpoints, and token behavior used during the OIDC login flow.

Table 47. OIDC fields
Field Type Description

<string>_LOGIN_CONFIG (Required)

String

The parent key that holds the OIDC configuration settings. Typically the name of the OIDC provider, for example, AZURE_LOGIN_CONFIG, however any arbitrary string is accepted.

   .CLIENT_ID (Required)

String

The registered client ID for this Project Quay instance. Example: 0e8dbe15c4c7630b6780

   .CLIENT_SECRET (Required)

String

The registered client secret for this Project Quay instance. Example: e4a58ddd3d7408b7aec109e85564a0d153d3e846

   .LOGIN_BINDING_FIELD

String

Used when the internal authorization is set to LDAP. Project 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

Scopes Project Quay requests during the OIDC login flow. Must include openid. Each scope listed here must also appear in the IdP’s scopes_supported array from /.well-known/openid-configuration.

   .OIDC_ENDPOINT_CUSTOM_PARAMS

String

Support for custom query parameters on OIDC endpoints. The following endpoints are supported: authorization_endpoint, token_endpoint, and user_endpoint.

   .OIDC_ISSUER

String

Allows the user to define the issuer to verify. For example, JWT tokens container a parameter known as iss which defines who issued the token. By default, this is read from the .well-know/openid/configuration endpoint, which is exposed by every OIDC provider. If this verification fails, there is no login.

   .OIDC_ISSUERS

Array of String

Accepted issuer URLs for this provider. When set, Project Quay accepts tokens whose iss claim matches any entry. Use this field to accept multiple issuers, for example Microsoft Entra ID v1.0 and v2.0 URLs during migration. If not set, Project Quay uses OIDC_ISSUER.

   .OIDC_AUDIENCES

Array of String

Accepted audience values for bearer token and On-Behalf-Of (OBO) flows. When set, Project Quay validates the token aud claim against this list. CLIENT_ID is always implicitly included. If not set, audience validation defaults to CLIENT_ID.

   .OIDC_ALLOWED_CLIENTS

Array of String

Optional whitelist of authorized party (azp) client IDs. When set, only tokens from these client applications are accepted. If not set, all clients are accepted. When restricting OBO clients, include your application’s own CLIENT_ID so direct user login continues to work.

   .OIDC_SERVER (Required)

String

The OIDC discovery base URL for authentication. Project Quay uses path joining for OIDC discovery, so the URL must end with a trailing /. Example: https://login.microsoftonline.com/<tenant-id>/v2.0/

   .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 (Required)

String

The name of the service that is being authenticated. Example: Microsoft Entra ID

   .VERIFIED_EMAIL_CLAIM_NAME

String

The name of the claim that is used to verify the email address of the user.

   .PREFERRED_GROUP_CLAIM_NAME

String

The key name within the OIDC token payload that holds information about the user’s group memberships.

   .OIDC_DISABLE_USER_ENDPOINT

Boolean

Whether to allow or disable the /userinfo endpoint. If using Azure Entra ID, this field must be set to True because Azure obtains the user’s information from the token instead of calling the /userinfo endpoint.

Default: False

USE_PKCE

Boolean

Whether to enable support for Proof Key for Code Exchange.

Default: False

PKCE_METHOD

Integer

The code challenge method used to generate the code_challenge sent in the initial authorization request.

Default: S256

PUBLIC_CLIENT

Boolean

Whether to omit client_secret during token request when the client is public.

Default: False
OIDC example YAML
AUTHENTICATION_TYPE: OIDC
# ...
<oidc_provider>_LOGIN_CONFIG:
  CLIENT_ID: <client_id>
  CLIENT_SECRET: <client_secret>
  LOGIN_BINDING_FIELD: <login_binding_field>
  LOGIN_SCOPES:
    - openid
    - email
    - profile
  OIDC_ENDPOINT_CUSTOM_PARAMS:
    authorization_endpoint:
      some: "param"
    token_endpoint:
      some: "param"
    user_endpoint:
      some: "param"
  OIDC_ISSUER: <oidc_issuer_url>
  OIDC_ISSUERS:
    - <issuer_url_1>
    - <issuer_url_2>
  OIDC_AUDIENCES:
    - <client_id>
    - <custom_api_audience>
  OIDC_ALLOWED_CLIENTS:
    - <client_id>
    - <upstream_client_id>
  OIDC_SERVER: <oidc_server_address>
  PREFERRED_USERNAME_CLAIM_NAME: <preferred_username_claim>
  SERVICE_ICON: <service_icon_url>
  SERVICE_NAME: <service_name>
  VERIFIED_EMAIL_CLAIM_NAME: <verified_email_claim>
  PREFERRED_GROUP_CLAIM_NAME: <preferred_group_claim>
  OIDC_DISABLE_USER_ENDPOINT: true
  USE_PKCE: True
  PKCE_METHOD: "S256"
  PUBLIC_CLIENT: True
# ...
Additional resources
OIDC example YAML for Microsoft Entra ID v2 with dual-issuer support
AUTHENTICATION_TYPE: OIDC
# ...
AZURE_LOGIN_CONFIG:
  CLIENT_ID: <quay_app_client_id>
  CLIENT_SECRET: <quay_app_client_secret>
  OIDC_SERVER: https://login.microsoftonline.com/<tenant-id>/v2.0/
  SERVICE_NAME: Microsoft Entra ID
  OIDC_DISABLE_USER_ENDPOINT: true
  OIDC_ISSUERS:
    - https://sts.windows.net/<tenant-id>/
    - https://login.microsoftonline.com/<tenant-id>/v2.0
  OIDC_AUDIENCES:
    - <quay_app_client_id>
    - api://quay-api
  OIDC_ALLOWED_CLIENTS:
    - <quay_app_client_id>
    - <upstream_app_client_id>
  USE_PKCE: true
  PKCE_METHOD: "S256"
  PUBLIC_CLIENT: true
# ...

Configure user access and automation defaults

Configure automation defaults and initial user access settings, including superuser assignment, first-user bootstrap, user creation policy, and API browser restrictions.

Automation configuration options

Project Quay supports various mechanisms for automating deployment and configuration, which allows the integration of Project Quay into GitOps and CI/CD pipelines. By defining these options and leveraging the API, Project Quay can be initialized and managed without using the UI.

Note

Because the Project Quay Operator manages the config.yaml file through the configBundleSecret custom resource (CR), pre-configuring Red Hat Quay on OpenShift Container Platform requires an administrator to manually create a valid config.yaml file with the desired configuration. This file must then be bundled into a new Kubernetes Secret and used to replace the default configBundleSecret CR referenced by the QuayRegistry CR. This allows Red Hat Quay on OpenShift Container Platform to be deployed in a fully automated manner, bypassing the web-based configuration UI. For more information, see "Modifying the QuayRegistry CR after deployment" in Additional resources.

For on-premise Project Quay deployments, pre-configuration is done by manually creating a valid config.yaml file and then deploying the registry.

Automation options are ideal for environments that require declarative Project Quay deployments, such as disconnected or air-gapped clusters.

Additional resources

Pre-configuration options for automation

Project Quay provides configuration options that enable registry administrators to automate early setup tasks and API accessibility. These options are useful for new deployments and controlling how API calls can be made.

The following options support automation and administrative control.

Table 48. Automation configuration fields
Field Type Description

FEATURE_USER_INITIALIZE

Boolean

Enables initial user bootstrapping in a newly deployed Project Quay registry. When this field is set to True in the config.yaml file prior to deployment, it allows an administrator to create the first user by calling the api/v1/user/initialize endpoint.

BROWSER_API_CALLS_XHR_ONLY

Boolean

Controls whether the registry API only accepts calls from browsers. To allow general browser-based access to the API, administrators must set this field to False. If set to True, API calls are blocked, preventing both administrators and users from interacting with the API.

SUPER_USERS

String

Defines a list of administrative users, or superusers, who have full privileges and unrestricted access to the registry. Project Quay administrators should configure SUPER_USERS in the config.yaml before deployment to ensure immediate administrative access without requiring a redeploy. Setting this field post-deployment requires restarting the registry to take effect.

FEATURE_USER_CREATION

Boolean

Relegates the creation of new users to only superusers when this field is set to False. This setting is useful in controlled environments where user access must be provisioned manually by administrators.
Note

Unlike all other registry API calls that require an OAuth 2 access token generated by an OAuth application in an existing organization, the api/v1/user/initialize endpoint does not require authentication. For more information about OAuth 2 access tokens, see "Project Quay API guide" in Additional resources.

The following YAML shows you the suggested configuration for automation:

Suggested configuration for automation
# ...
FEATURE_USER_INITIALIZE: true
BROWSER_API_CALLS_XHR_ONLY: false
SUPER_USERS:
- quayadmin
FEATURE_USER_CREATION: false
# ...
Additional resources

Tune Quay performance with configuration and environment variables

Configure geo-replication storage preferences and database connection pool environment variables during deployment. For rate limits, HTTP and worker tuning, and large artifact settings, see the Optimize documentation.

Environment variable configuration

The following environment variables tune Project Quay runtime behavior for geo-replication, database pooling, HTTP concurrency, and worker scaling.

Use environment variables cautiously. These options typically override or augment existing configuration mechanisms.

This section documents environment variables related to the following components:

  • Geo-replication preferences

  • Database connection pooling

  • HTTP connection concurrency

  • Worker process scaling

Geo-replication storage preference environment variable

Use the QUAY_DISTRIBUTED_STORAGE_PREFERENCE environment variable to set the preferred storage engine for a geo-replicated Project Quay deployment in each region.

Project Quay supports multi-region deployments where multiple instances operate across geographically distributed sites. In these scenarios, each site shares the same configuration and metadata, but storage backends might vary between regions.

To accommodate this, Project Quay allows specifying a preferred storage engine for each deployment using an environment variable. This ensures that while metadata remains synchronized across all regions, each region can use its own optimized storage backend without requiring separate configuration files.

Table 49. Geo-replication configuration
Variable Type Description

QUAY_DISTRIBUTED_STORAGE_PREFERENCE

String

The preferred storage engine (by ID in DISTRIBUTED_STORAGE_CONFIG) to use.

Database connection pooling

Use the DB_CONNECTION_POOLING environment variable and DB_CONNECTION_ARGS settings to control whether Project Quay pools database connections and the maximum pool size per process.

Database connection pooling is enabled by default, and each process that interacts with the database contains a connection pool. These per-process connection pools are configured to maintain a maximum of 20 connections. Under heavy load, it is possible to fill the connection pool for every process within a Project Quay container. Under certain deployments and loads, this might require analysis to ensure that Project Quay does not exceed the configured database’s maximum connection count.

Overtime, the connection pools release idle connections. To release all connections immediately, Project Quay requires a restart.

Table 50. Database connection pooling configuration
Variable Type Description

DB_CONNECTION_POOLING

String

Whether to enable or disable database connection pooling. Defaults to true. Accepted values are "true" or "false"

If database connection pooling is enabled, it is possible to change the maximum size of the connection pool. This can be done through the following config.yaml option:

Database connection pooling example YAML
# ...
DB_CONNECTION_ARGS:
  max_connections: 10
# ...
Disabling database pooling in standalone deployments

For standalone Project Quay deployments, database connection pooling can be toggled off when starting your deployment. For example:

$ sudo podman run -d --rm -p 80:8080 -p 443:8443  \
   --name=quay \
   -v $QUAY/config:/conf/stack:Z \
   -v $QUAY/storage:/datastorage:Z \
   -e DB_CONNECTION_POOLING=false
   registry.redhat.io/quay/quay-rhel8:v3.12.1
Disabling database pooling for Red Hat Quay on OpenShift Container Platform

For Red Hat Quay on OpenShift Container Platform, database connection pooling can be configured by modifying the QuayRegistry custom resource definition (CRD). For example:

Example QuayRegistry CRD
spec:
  components:
  - kind: quay
    managed: true
    overrides:
      env:
      - name: DB_CONNECTION_POOLING
        value: "false"
Additional resources

Configure Elasticsearch and Splunk action log storage

Configure action log storage in Elasticsearch or Splunk, including Splunk installation prerequisites, bearer token generation, Project Quay configuration, and log verification.

Action log storage backends (Elasticsearch and Splunk)

By default, usage logs are stored in the Project Quay database and exposed through the web UI on organization and repository levels.

Appropriate administrative privileges are required to see log entries. For deployments with a large amount of logged operations, you can store the usage logs in Elasticsearch and Splunk instead of the Project Quay database backend.

Configure action log storage for Elasticsearch

To store Project Quay action logs in Elasticsearch, you can update the LOGS_MODEL settings in your config.yaml file and restart the registry. Usage logs remain available in the web UI for repositories and organizations.

Note

To configure action log storage for Elasticsearch, you must provide your own Elasticsearch stack; Project Quay does not include Elasticsearch as a customizable component.
Procedure

  1. Obtain an Elasticsearch account.

  2. Update your Project Quay config.yaml file to include the following information:

    # ...
LOGS_MODEL: elasticsearch
LOGS_MODEL_CONFIG:
    producer: elasticsearch
    elasticsearch_config:
        host: http://<host.elasticsearch.example>:<port>
        port: 9200
        access_key: <access_key>
        secret_key: <secret_key>
        use_ssl: True
        index_prefix: <logentry>
        aws_region: <us-east-1>
# ...

    where:

    LOGS_MODEL

    Specifies the method for handling log data.

    LOGS_MODEL_CONFIG.producer

    Specifies either Elasticsearch or Kinesis to direct logs to an intermediate Kinesis stream on AWS. You need to configure your own pipeline to send logs from Kinesis to Elasticsearch, for example, Logstash.

    LOGS_MODEL_CONFIG.elasticsearch_config.host

    Specifies the hostname or IP address of the system providing the Elasticsearch service.

    LOGS_MODEL_CONFIG.elasticsearch_config.port

    Specifies the port number providing the Elasticsearch service on the host you just entered. Note that the port must be accessible from all systems running the Project Quay registry. The default is TCP port 9200.

    LOGS_MODEL_CONFIG.elasticsearch_config.access_key

    Specifies the access key needed to gain access to the Elasticsearch service, if required.

    LOGS_MODEL_CONFIG.elasticsearch_config.secret_key

    Specifies the secret key needed to gain access to the Elasticsearch service, if required.

    LOGS_MODEL_CONFIG.elasticsearch_config.use_ssl

    Specifies whether to use SSL/TLS for Elasticsearch. Defaults to True.

    LOGS_MODEL_CONFIG.elasticsearch_config.index_prefix

    Specifies a prefix to attach to log entries.

    LOGS_MODEL_CONFIG.elasticsearch_config.aws_region

    Specifies the AWS region if you are running on AWS. Otherwise, leave it blank.

  3. Optional. If you are using Kinesis as your logs producer, you must include the following fields in your config.yaml file:

        kinesis_stream_config:
        stream_name: <kinesis_stream_name>
        access_key: <aws_access_key>
        secret_key: <aws_secret_key>
        aws_region: <aws_region>

    where:

    kinesis_stream_config.stream_name

    Specifies the name of the Kinesis stream.

    kinesis_stream_config.access_key

    Specifies the name of the AWS access key needed to gain access to the Kinesis stream, if required.

    kinesis_stream_config.secret_key

    Specifies the name of the AWS secret key needed to gain access to the Kinesis stream, if required.

    kinesis_stream_config.aws_region

    Specifies the Amazon Web Services (AWS) region.

  4. Save your config.yaml file and restart your Project Quay deployment.

Configure action log storage for Splunk

Splunk is an alternative to Elasticsearch for storing and analyzing Project Quay action logs. You can forward logs directly to Splunk or to the Splunk HTTP Event Collector (HEC) during or after deployment.

Additional resources
Installing and creating a username for Splunk

To prepare Splunk for Project Quay action log storage, you can install Splunk Enterprise and create an administrator username and password.

Procedure

  1. Create a Splunk account by navigating to Splunk and entering the required credentials.

  2. Navigate to the Splunk Enterprise Free Trial page, select your platform and installation package, and then click Download Now.

  3. Install the Splunk software on your machine. When prompted, create a username, for example, splunk_admin and password.

  4. After creating a username and password, a localhost URL will be provided for your Splunk deployment, for example, http://<sample_url>.remote.csb:8000/. Open the URL in your preferred browser.

  5. Log in with the username and password you created during installation. You are directed to the Splunk UI.

Generating a Splunk bearer token

You can generate a Splunk bearer token for Project Quay action log forwarding by using the Splunk UI or the CLI.

Generating a Splunk bearer token using the Splunk UI

To create a Splunk bearer token for Project Quay from the Splunk UI, you can enable token authentication and create a new token.

Prerequisites

  • You have installed Splunk and created a username.

Procedure

  1. On the Splunk UI, navigate to Settings → Tokens.

  2. Click Enable Token Authentication.

  3. Ensure that Token Authentication is enabled by clicking Token Settings and selecting Token Authentication if necessary.

  4. Optional: Set the expiration time for your token. This defaults at 30 days.

  5. Click Save.

  6. Click New Token.

  7. Enter information for User and Audience.

  8. Optional: Set the Expiration and Not Before information.

  9. Click Create. Your token appears in the Token box. Copy the token immediately.

    Important

    If you close out of the box before copying the token, you must create a new token. The token in its entirety is not available after closing the New Token window.
Generating a Splunk bearer token using the CLI

To create a Splunk bearer token for Project Quay from the CLI, you can enable token authentication and request a token with curl.

Prerequisites

  • You have installed Splunk and created a username.

Procedure

  1. In your CLI, enter the following CURL command to enable token authentication, passing in your Splunk username and password:

    $ curl -k -u <username>:<password> -X POST <scheme>://<host>:<port>/services/admin/token-auth/tokens_auth -d disabled=false

  2. Create a token by entering the following CURL command, passing in your Splunk username and password.

    $ curl -k -u <username>:<password> -X POST <scheme>://<host>:<port>/services/authorization/tokens?output_mode=json --data name=<username> --data audience=Users --data-urlencode expires_on=+30d

  3. Save the generated bearer token.

Generating an HEC ingest token

To forward Project Quay action logs to Splunk through the HTTP Event Collector (HEC), you can generate an HEC ingest token in the Splunk web UI or by using the Splunk REST API.

Note

Splunk HEC tokens are ingest-only and cannot search.
Prerequisites

  • You have installed Splunk and created a username.

Procedure

  1. To create an HEC token using the Splunk web UI:

    1. Log in to the Splunk via the web UI.

    2. Click Settings → Data Inputs → HTTP Event Collector.

    3. Click New Token.

    4. Name the token, for example, quay-hec, and select the target index, for example, quay_logs.

    5. Click Submit and copy the token value.

  2. To create an HEC token using the Splunk REST API:

    1. Enable HEC by entering the following command:

      $ curl -k -u <username>:<password> \
 https://<splunk.example.com>:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/http \
 -d "disabled=0"

    2. Create an HEC token by entering the following command:

      $ curl -k -u <username>:<password> \
 "https://<splunk.example.com>:8089/servicesNS/admin/splunk_httpinput/data/inputs/http?output_mode=json" \
 -d "name=quay-hec" -d "index=quay_logs"
      Example output:
      {"entry":[{"content":{"token":"<your_bearer_token>"}}]}
Configuring Project Quay to use Splunk

To send Project Quay action logs to Splunk or the Splunk HTTP Event Collector (HEC), you can add the Splunk settings to your config.yaml file and restart the registry.

Prerequisites

  • You have installed Splunk and created a username.

  • You have generated a Splunk bearer token.

Procedure

  1. Configure Project Quay to use Splunk or the Splunk HTTP Event Collector (HEC).

    1. If opting to use Splunk, open your Project Quay config.yaml file and add the following configuration fields:

      # ...
LOGS_MODEL: splunk
LOGS_MODEL_CONFIG:
    producer: splunk
    splunk_config:
        host: http://<user_name>.remote.csb
        port: 8089
        bearer_token: <bearer_token>
        url_scheme: <http/https>
        verify_ssl: False
        index_prefix: <splunk_log_index_name>
        ssl_ca_path: <location_to_ssl-ca-cert.pem>
        search_timeout: 60
        max_results: 10000
        export_batch_size: 5000
# ...

      where:

      LOGS_MODEL_CONFIG.splunk_config.host

      Specifies the Splunk cluster endpoint.

      LOGS_MODEL_CONFIG.splunk_config.port

      Specifies the Splunk management cluster endpoint port. Differs from the Splunk GUI hosted port. Can be found on the Splunk UI under Settings → Server Settings → General Settings.

      LOGS_MODEL_CONFIG.splunk_config.bearer_token

      Specifies the generated bearer token for Splunk.

      LOGS_MODEL_CONFIG.splunk_config.url_scheme

      Specifies the URL scheme for access the Splunk service. If Splunk is configured to use TLS/SSL, this must be https.

      LOGS_MODEL_CONFIG.splunk_config.verify_ssl

      Specifies whether to enable TLS/SSL. Defaults to True.

      LOGS_MODEL_CONFIG.splunk_config.index_prefix

      Specifies the Splunk index prefix. Can be a new, or used, index. Can be created from the Splunk UI.

      LOGS_MODEL_CONFIG.splunk_config.ssl_ca_path

      Specifies the relative container path to a single .pem file containing a certificate authority (CA) for TLS/SSL validation.

      LOGS_MODEL_CONFIG.splunk_config.search_timeout

      Specifies the timeout for Splunk search queries in seconds. Increase for slow Splunk clusters or complex queries.

      LOGS_MODEL_CONFIG.splunk_config.max_results

      Specifies the maximum number of results to return per search query. Larger values require more memory.

      LOGS_MODEL_CONFIG.splunk_config.export_batch_size

      Specifies the batch size for log export operations.

    2. If opting to use Splunk HEC, open your Project Quay config.yaml file and add the following configuration fields:

      # ...
LOGS_MODEL: splunk
LOGS_MODEL_CONFIG:
  producer: splunk_hec
  splunk_hec_config:
    host: prd-p-aaaaaq.splunkcloud.com
    port: 8088
    hec_token: 12345678-1234-1234-1234-1234567890ab
    url_scheme: https
    verify_ssl: False
    index: quay
    splunk_host: quay-dev
    splunk_sourcetype: quay_logs
    timeout: 10
    search_token: <bearer_token>
    search_host: <splunk.example.com>
    search_port: 8089
    search_timeout: 60
    max_results: 10000
    export_batch_size: 5000
# ...

      where:

      LOGS_MODEL_CONFIG.producer

      Specifies splunk_hec when configuring Splunk HEC.

      LOGS_MODEL_CONFIG.splunk_hec_config

      Specifies the logs model configuration for Splunk HTTP Event Collector action logs configuration.

      LOGS_MODEL_CONFIG.splunk_hec_config.host

      Specifies the Splunk cluster endpoint.

      LOGS_MODEL_CONFIG.splunk_hec_config.port

      Specifies the Splunk management cluster endpoint port.

      LOGS_MODEL_CONFIG.splunk_hec_config.hec_token

      Specifies the HEC token for Splunk.

      LOGS_MODEL_CONFIG.splunk_hec_config.url_scheme

      Specifies the URL scheme for access the Splunk service. If Splunk is behind SSL/TLS, must be https.

      LOGS_MODEL_CONFIG.splunk_hec_config.verify_ssl

      Specifies whether to enable (true) or disable (false) SSL/TLS verification for HTTPS connections.

      LOGS_MODEL_CONFIG.splunk_hec_config.index

      Specifies the Splunk index to use.

      LOGS_MODEL_CONFIG.splunk_hec_config.splunk_host

      Specifies the host name to log this event.

      LOGS_MODEL_CONFIG.splunk_hec_config.splunk_sourcetype

      Specifies the name of the Splunk sourcetype to use.

      LOGS_MODEL_CONFIG.splunk_hec_config.timeout

      Specifies the timeout in seconds for HTTP requests to the Splunk HEC endpoint. Prevents requests from hanging indefinitely when Splunk is unresponsive.

      LOGS_MODEL_CONFIG.splunk_hec_config.search_token

      Specifies an optional bearer token for the Splunk search API. Required because HEC tokens are ingest-only and cannot search.

      LOGS_MODEL_CONFIG.splunk_hec_config.search_host

      Specifies the Splunk management host for the search API. Defaults to the HEC host if not specified.

      LOGS_MODEL_CONFIG.splunk_hec_config.search_port

      Specifies the Splunk management port for the search API. Defaults to 8089 if not specified.

      LOGS_MODEL_CONFIG.splunk_hec_config.search_timeout

      Specifies the timeout for Splunk search queries in seconds. Increase for slow Splunk clusters or complex queries.

      LOGS_MODEL_CONFIG.splunk_hec_config.max_results

      Specifies the maximum number of results to return per search query. Larger values require more memory.

      LOGS_MODEL_CONFIG.splunk_hec_config.export_batch_size

      Specifies the batch size for log export operations.

  2. If you are configuring ssl_ca_path, you must configure the SSL/TLS certificate so that Project Quay trusts it.

    1. If you are using a standalone deployment of Project Quay, SSL/TLS certificates can be provided by placing the certificate file inside of the extra_ca_certs directory, or inside of the relative container path and specified by ssl_ca_path.

    2. If you are using the Project Quay Operator, create a config bundle secret, including the certificate authority (CA) of the Splunk server. For example:

      $ oc create secret generic --from-file config.yaml=./config_390.yaml --from-file extra_ca_cert_splunkserver.crt=./splunkserver.crt config-bundle-secret

      Specify the conf/stack/extra_ca_certs/splunkserver.crt file in your config.yaml. For example:

      # ...
LOGS_MODEL: splunk
LOGS_MODEL_CONFIG:
    producer: splunk
    splunk_config:
        host: ec2-12-345-67-891.us-east-2.compute.amazonaws.com
        port: 8089
        bearer_token: eyJra
        url_scheme: https
        verify_ssl: true
        index_prefix: quay123456
        ssl_ca_path: conf/stack/splunkserver.crt
# ...
Creating an action log

To verify that Project Quay is forwarding action logs to Splunk, you can create a robot account in an organization and search the Splunk index for the forwarded JSON log entries.

Prerequisites

  • You have installed Splunk and created a username.

  • You have generated a Splunk bearer token.

  • You have configured your Project Quay config.yaml file to enable Splunk.

Procedure

  1. Log in to your Project Quay deployment.

  2. Click on the name of the organization that you use to create an action log for Splunk.

  3. In the navigation pane, click Robot Accounts → Create Robot Account.

  4. When prompted, enter a name for the robot account, for example splunkrobotaccount, then click Create robot account.

  5. On your browser, open the Splunk UI.

  6. Click Search and Reporting.

  7. In the search bar, enter the name of your index, for example, <splunk_log_index_name> and press Enter.

    The search results populate on the Splunk UI. Logs are forwarded in JSON format. A response might look similar to the following:

    {
  "log_data": {
    "kind": "authentication",
    "account": "quayuser123",
    "performer": "John Doe",
    "repository": "projectQuay",
    "ip": "192.168.1.100",
    "metadata_json": {...},
    "datetime": "2024-02-06T12:30:45Z"
  }
}

    where:

    kind

    Specifies the type of log event. In this example, authentication indicates that the log entry relates to an authentication event.

    account

    Specifies the user account involved in the event.

    performer

    Specifies the individual who performed the action.

    repository

    Specifies the repository associated with the event.

    ip

    Specifies the IP address from which the action was performed.

    metadata_json

    Specifies additional metadata related to the event, when present.

    datetime

    Specifies the timestamp of when the event occurred.

Action log, Elasticsearch, and Splunk configuration fields

Optional configuration fields for action log storage, rotation, and auditing, and for forwarding action logs to Elasticsearch or Splunk.

Action log storage configuration fields

The following configuration fields control how Project Quay stores, exports, rotates, and audits action logs for registry activity. You can use these fields to export or forward logs to external systems like Elasticsearch or Splunk for advanced analysis, auditing, or compliance.

Table 51. Action log storage configuration fields
Field Type Description

FEATURE_LOG_EXPORT

Boolean

Whether to allow exporting of action logs.

Default: True

LOGS_MODEL

String

Specifies the preferred method for handling log data. Values: One of database, transition_reads_both_writes_es, elasticsearch, splunk

Default: database

LOGS_MODEL_CONFIG

Object

Logs model config for action logs.

ALLOW_WITHOUT_STRICT_LOGGING

Boolean

When set to True, if the external log system like Splunk or ElasticSearch is intermittently unavailable, allows users to push images normally. Events are logged to the stdout instead. Overrides ALLOW_PULLS_WITHOUT_STRICT_LOGGING if set.

Default: False
Action log storage example YAML
# ...
FEATURE_LOG_EXPORT: true
LOGS_MODEL: elasticsearch
LOGS_MODEL_CONFIG:
  elasticsearch:
    endpoint: http://elasticsearch.example.com:9200
    index_prefix: quay-logs
    username: elastic
    password: changeme
ALLOW_WITHOUT_STRICT_LOGGING: true
# ...

Action log rotation and archiving configuration

This section describes configuration fields related to action log rotation and archiving in Project Quay. When enabled, older logs can be automatically rotated and archived to designated storage locations, helping to manage log retention and storage utilization efficiently.

Table 52. 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.

Default: False

ACTION_LOG_ARCHIVE_LOCATION

String

If action log archiving is enabled, the storage engine in which to place the archived data.

Example:: s3_us_east

ACTION_LOG_ARCHIVE_PATH

String

If action log archiving is enabled, the path in storage in which to place the archived data.

Example: archives/actionlogs

ACTION_LOG_ROTATION_THRESHOLD

String

The time interval after which to rotate logs.

Example: 30d
Action log rotation and archiving example YAML
# ...
FEATURE_ACTION_LOG_ROTATION: true
ACTION_LOG_ARCHIVE_LOCATION: s3_us_east
ACTION_LOG_ARCHIVE_PATH: archives/actionlogs
ACTION_LOG_ROTATION_THRESHOLD: 30d
# ...

Action log audit configuration

This section covers the configuration fields for audit logging within Project Quay. When enabled, audit logging tracks detailed user activity such as UI logins, logouts, and Docker logins for regular users, robot accounts, and token-based accounts.

Table 53. Audit logs configuration field
Field Type Description

ACTION_LOG_AUDIT_LOGINS

Boolean

When set to True, tracks advanced events such as logging into, and out of, the UI, and logging in using Docker for regular users, robot accounts, and for application-specific token accounts.

Default: True

ACTION_LOG_AUDIT_LOGIN_FAILURES

Boolean

Whether logging of failed logins attempts is enabled.

Default: False

ACTION_LOG_AUDIT_PULL_FAILURES

Boolean

Whether logging of failed image pull attempts is enabled.

Default: False

ACTION_LOG_AUDIT_PUSH_FAILURES

Boolean

Whether logging of failed image push attempts is enabled.

Default: False

ACTION_LOG_AUDIT_DELETE_FAILURES

Boolean

Whether logging of failed image delete attempts is enabled.

Default: False
Audit logs configuration example YAML
# ...
ACTION_LOG_AUDIT_LOGINS: true
ACTION_LOG_AUDIT_LOGIN_FAILURES: false
ACTION_LOG_AUDIT_PULL_FAILURES: false
ACTION_LOG_AUDIT_PUSH_FAILURES: false
ACTION_LOG_AUDIT_DELETE_FAILURES: false
# ...
Additional resources

Elasticsearch configuration fields

The following configuration fields integrate Project Quay with an external Elasticsearch service. This enables storing and querying structured data such as action logs, repository events, and other operational records outside of the internal database.

Table 54. Logs model configuration (LOGS_MODEL_CONFIG) fields
Field Type Description

LOGS_MODEL_CONFIG.elasticsearch_config.access_key

String

Elasticsearch user (or IAM key for AWS ES).

Example: some_string

.elasticsearch_config.host

String

Elasticsearch cluster endpoint.

Example: host.elasticsearch.example

.elasticsearch_config.index_prefix

String

Prefix for Elasticsearch indexes.

Example: logentry_

.elasticsearch_config.index_settings

Object

Index settings for Elasticsearch.

LOGS_MODEL_CONFIG.elasticsearch_config.use_ssl

Boolean

Whether to use SSL for Elasticsearch.

Default: True

Example: True

.elasticsearch_config.secret_key

String

Elasticsearch password (or IAM secret for AWS ES).

Example: some_secret_string

.elasticsearch_config.aws_region

String

AWS region. Example: us-east-1

.elasticsearch_config.port

Number

Port of the Elasticsearch cluster. Example: 1234

.kinesis_stream_config.aws_secret_key

String

AWS secret key. Example: some_secret_key

.kinesis_stream_config.stream_name

String

AWS Kinesis stream to send action logs to. Example: logentry-kinesis-stream

.kinesis_stream_config.aws_access_key

String

AWS access key. Example: some_access_key

.kinesis_stream_config.retries

Number

Max number of retry attempts for a single request. Example: 5

.kinesis_stream_config.read_timeout

Number

Read timeout in seconds. Example: 5

.kinesis_stream_config.max_pool_connections

Number

Max number of connections in the pool. Example: 10

.kinesis_stream_config.aws_region

String

AWS region. Example: us-east-1

.kinesis_stream_config.connect_timeout

Number

Connection timeout in seconds. Example: 5

.producer

String

Logs producer type. Accepted values: kafka, elasticsearch, kinesis_stream Example: kafka

.kafka_config.topic

String

Kafka topic used to publish log entries. Example: logentry

.kafka_config.bootstrap_servers

Array

List of Kafka brokers used to bootstrap the client.

.kafka_config.max_block_seconds

Number

Max seconds to block during a send() operation. Example: 10
Elasticsearch example YAML
# ...
FEATURE_LOG_EXPORT: true
LOGS_MODEL: elasticsearch
LOGS_MODEL_CONFIG:
  producer: elasticsearch
  elasticsearch_config:
    access_key: elastic_user
    secret_key: elastic_password
    host: es.example.com
    port: 9200
    use_ssl: true
    aws_region: us-east-1
    index_prefix: logentry_
    index_settings:
      number_of_shards: 3
      number_of_replicas: 1
ALLOW_WITHOUT_STRICT_LOGGING: true
# ...

Splunk configuration fields

The following configuration fields export Project Quay action logs to a Splunk endpoint. This configuration allows audit and event logs to be sent to an external Splunk server for centralized analysis, search, and long-term storage.

Table 55. Splunk configuration fields
Field Type Description

producer

String

Must be set to splunk when configuring Splunk as the log exporter.

splunk_config

Object

Logs model configuration for Splunk action logs or Splunk cluster configuration.

.host

String

The Splunk cluster endpoint.

.port

Integer

The port number for the Splunk management cluster endpoint.

.bearer_token

String

The bearer token used for authentication with Splunk.

.verify_ssl

Boolean

Enable (True) or disable (False) TLS/SSL verification for HTTPS connections.

.index_prefix

String

The index prefix used by Splunk.

.ssl_ca_path

String

The relative container path to a .pem file containing the certificate authority (CA) for SSL validation.

.search_timeout

Integer

The timeout for Splunk search queries in seconds. Increase for slow Splunk clusters or complex queries.

.max_results

Integer

The maximum number of results to return per search query. Larger values require more memory.

.export_batch_size

Integer

The batch size for log export operations.
Splunk configuration example YAML
# ...
LOGS_MODEL: splunk
LOGS_MODEL_CONFIG:
    producer: splunk
    splunk_config:
        host: http://<user_name>.remote.csb
        port: 8089
        bearer_token: <bearer_token>
        url_scheme: <http/https>
        verify_ssl: False
        index_prefix: <splunk_log_index_name>
        ssl_ca_path: <location_to_ssl-ca-cert.pem>
        search_timeout: 60
        max_results: 10000
        export_batch_size: 5000
# ...

Splunk HEC configuration fields

The following fields are available when configuring Splunk HTTP Event Collector (HEC) for Project Quay.

Table 56. Splunk HEC configuration fields
Field Type Description

producer

String

Must be set to splunk_hec when configuring Splunk HTTP Event Collector (HEC).

splunk_hec_config

Object

Logs model configuration for Splunk HTTP Event Collector action logs.

.host

String

Splunk cluster endpoint.

.port

Integer

Splunk management cluster endpoint port.

.hec_token

String

HEC token used for authenticating with Splunk.

.url_scheme

String

URL scheme to access the Splunk service. Use https if Splunk is behind SSL/TLS.

.verify_ssl

Boolean

Enable (True) or disable (False) SSL/TLS verification for HTTPS connections.

.index

String

The Splunk index to use for log storage.

.splunk_host

String

The hostname to assign to the logged event.

.splunk_sourcetype

String

The Splunk sourcetype to associate with the event.

.timeout

Integer

Timeout in seconds for HTTP requests to Splunk HEC endpoint. Prevents requests from hanging indefinitely when Splunk is unresponsive.

.search_timeout

Integer

The timeout for Splunk search queries in seconds. Increase for slow Splunk clusters or complex queries.

.max_results

Integer

The maximum number of results to return per search query. Larger values require more memory.

.export_batch_size

Integer

The batch size for log export operations.

.search_host

String

The Splunk management host for search API. Defaults to HEC host if not specified.

.search_port

Integer

The Splunk management port for search API. Defaults to 8089 if not specified.

.search_token (Optional)

String

The bearer token for Splunk search API. Required because HEC tokens are ingest-only and cannot search.
Splunk HEC example YAML
# ...
LOGS_MODEL: splunk
LOGS_MODEL_CONFIG:
  producer: splunk_hec
  splunk_hec_config:
    host: prd-p-aaaaaq.splunkcloud.com
    port: 8088
    hec_token: 12345678-1234-1234-1234-1234567890ab
    url_scheme: https
    verify_ssl: False
    index: quay
    splunk_host: quay-dev
    splunk_sourcetype: quay_logs
    timeout: 10
    search_token: <bearer_token>
    search_host: <splunk.example.com>
    search_port: 8089
    search_timeout: 60
    max_results: 10000
    export_batch_size: 5000
# ...

Configure notifications for registry events

Configure repository event notifications by using the web UI or API, set up quota and image expiration alerts, route email through organization contact addresses, and review repository event payload formats.

Notifications overview

Notifications in Project Quay alert you about repository events such as pushes, builds, and image expiry. You can configure delivery methods for users, teams, or organizations.

Notification entries appear on the repository Events and Notifications page and in the global Notifications panel. Delivery methods include email, webhook POST, Flowdock, HipChat, and Slack.

Creating notifications by using the UI

To alert users to repository events such as pushes or build failures, you can create a notification from the Settings page in the Project Quay v2 UI. You select an event trigger and a delivery method, such as email or Slack.

Prerequisites

  • You have created a repository.

  • You have administrative privileges for the repository.

Procedure

  1. In the navigation pane, click Settings.

  2. In the Events and Notifications category, click Create Notification to add a new notification for a repository event. The Create notification popup box appears.

  3. On the Create repository popup box, click the When this event occurs box to select an event. You can select a notification for the following types of events:

    • Push to Repository

    • Image build failed

    • Image build queued

    • Image build started

    • Image build success

    • Image build cancelled

    • Image expiry trigger

  4. After you have selected the event type, select the notification method. The following methods are supported:

    • Quay Notification

    • E-mail Notification

    • Webhook POST

    • Flowdock Team Notification

    • HipChat Room Notification

    • Slack Notification

      Depending on the method that you choose, you must include additional information. For example, if you select E-mail, you are required to include an e-mail address and an optional notification title.

  5. After selecting an event and notification method, click Create Notification.

Creating an image expiration notification

To create an image expiration notification in Project Quay, you can use the v2 UI or the API. You set how many days before expiry to send the alert.

Triggers can work in conjunction with the auto-pruning feature. You can also create this notification by using the createRepoNotification API endpoint.

Prerequisites

  • FEATURE_GARBAGE_COLLECTION: true is set in your config.yaml file.

  • Optional. FEATURE_AUTO_PRUNE: true is set in your config.yaml file.

Procedure

  1. On the Project Quay v2 UI, click Repositories.

  2. Select the name of a repository.

  3. Click Settings → Events and notifications.

  4. Click Create notification. The Create notification popup box appears.

  5. Click the Select event…​ box, then click Image expiry trigger.

  6. In the When the image is due to expiry in days box, enter the number of days before the image’s expiration when you want to receive an alert. For example, use 1 for 1 day.

  7. In the Select method…​ box, click one of the following:

    • E-mail

    • Webhook POST

    • Flowdock Team Notification

    • HipChat Room Notification

    • Slack Notification

  8. Depending on which method you chose, include the necessary data. For example, if you chose Webhook POST, include the Webhook URL.

  9. Optional. Provide a POST JSON body template.

  10. Optional. Provide a Title for your notification.

  11. Click Submit. You are returned to the Events and notifications page, and the notification now appears.

  12. Optional. You can set the NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES variable in your config.yaml file. with this field set, if there are any expiring images notifications will be sent automatically. By default, this is set to 300, or 5 hours, however it can be adjusted as warranted.

    NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES: 300

    where:

    NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES

    Specifies that by default, this field is set to 300, or 5 hours.

Verification

  1. Click the menu kebab → Test Notification. The following message is returned:

    Test Notification Queued
A test version of this notification has been queued and should appear shortly

  2. Depending on which method you chose, check your e-mail, webhook address, Slack channel, and so on. The information sent should look similar to the following example:

    {
  "repository": "sample_org/busybox",
  "namespace": "sample_org",
  "name": "busybox",
  "docker_url": "quay-server.example.com/sample_org/busybox",
  "homepage": "http://quay-server.example.com/repository/sample_org/busybox",
  "tags": [
    "latest",
    "v1"
  ],
  "expiring_in": "1 days"
}

Creating notifications by using the API

To create, test, reset, or delete repository notifications in Project Quay, you can use the repository notification API endpoints.

Prerequisites

  • You have created a repository.

  • You have administrative privileges for the repository.

  • You have created an OAuth access token.

Procedure

  1. Enter the following POST /api/v1/repository/{repository}/notification command to create a notification on your repository:

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Content-Type: application/json" \
  --data '{
    "event": "<event>",
    "method": "<method>",
    "config": {
      "<config_key>": "<config_value>"
    },
    "eventConfig": {
      "<eventConfig_key>": "<eventConfig_value>"
    }
  }' \
  https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/

    This command does not return output in the CLI. Instead, you can enter the following GET /api/v1/repository/{repository}/notification/{uuid} command to obtain information about the repository notification:

    {"uuid": "240662ea-597b-499d-98bb-2b57e73408d6", "title": null, "event": "repo_push", "method": "quay_notification", "config": {"target": {"name": "quayadmin", "kind": "user", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}}}, "event_config": {}, "number_of_failures": 0}

  2. You can test your repository notification by entering the following POST /api/v1/repository/{repository}/notification/{uuid}/test command:

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>/test
    Example output
    {}

  3. You can reset repository notification failures to 0 by entering the following POST /api/v1/repository/{repository}/notification/{uuid} command:

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>

  4. Enter the following DELETE /api/v1/repository/{repository}/notification/{uuid} command to delete a repository notification:

    $ curl -X DELETE \
  -H "Authorization: Bearer <bearer_token>" \
  https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/<uuid>

    This command does not return output in the CLI. Instead, you can enter the following GET /api/v1/repository/{repository}/notification/ command to retrieve a list of all notifications:

    $ curl -X GET  -H "Authorization: Bearer <bearer_token>"   -H "Accept: application/json"  https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification
    Example output
    {"notifications": []}

Creating quota notifications by using the API

To create quota warning or error notifications for organization and user namespaces in Project Quay, you can use the API. Warning limits trigger quota_warning events and reject limits trigger quota_error events.

Warning-type quota limits trigger quota_warning notifications. Reject-type quota limits trigger quota_error notifications. For organization email notifications, "config": {} is valid because recipients are resolved server-side (organization contact email, or organization administrators if unset). User email notifications are sent to the user account email address.

Project Quay throttles repeated alerts for the same namespace and threshold by using QUOTA_NOTIFICATION_COOLDOWN_SECONDS (default: 86400 / 24 hours). If usage drops below a threshold and later crosses it again, the notification can re-fire. Deleting a quota also removes associated quota_warning and quota_error notification rules for that namespace.

Prerequisites

  • You have created an OAuth access token.

  • FEATURE_QUOTA_MANAGEMENT is enabled in your Project Quay configuration.

  • FEATURE_QUOTA_NOTIFICATIONS is enabled in your Project Quay configuration.

  • Optional: You have established quota limits for your organization or user namespace. You can create notification rules before setting quota limits. Notifications trigger automatically after quotas are configured and thresholds are crossed.

  • You have administrative privileges for the namespace.

Procedure

  1. To create an organization quota notification, enter a command similar to the following example:

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
--data '{
    "event": "quota_warning",
    "method": "email",
    "config": {},
    "eventConfig": {}
}' \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications
    Example output
    {
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": null,
"event": "quota_warning",
"method": "email",
"config": {},
"event_config": {},
"number_of_failures": 0
}

  2. Optional: You can create a quota error notification by changing the event type. To complete this task, run a command similar to the following example:

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
--data '{
    "event": "quota_error",
    "method": "slack",
    "config": {
    "url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
    },
    "eventConfig": {}
}' \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications

  3. To create a user namespace quota notification, enter a command similar to the following example:

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
--data '{
    "event": "quota_warning",
    "method": "email",
    "config": {},
    "eventConfig": {}
}' \
https://<quay-server.example.com>/api/v1/user/namespacenotifications

Configuring email routing with organization contact email

To route quota notification emails to a shared organization contact address in Project Quay, you can set the organization contact email with the API. You can list and test notifications for organizations and user namespaces.

Procedure

  1. Set the organization contact email by entering a command similar to the following example:

    $ curl -X PUT \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
--data '{
    "email": "ops-team@example.com"
}' \
https://<quay-server.example.com>/api/v1/organization/<orgname>
    Note

    Setting the organization contact email requires organization administrator permissions (org:admin scope). If a contact email is not set, quota notifications default to sending to organization administrator email addresses.

  2. List all notifications for an organization by entering a command similar to the following example:

    $ curl -X GET \
-H "Authorization: Bearer <bearer_token>" \
-H "Accept: application/json" \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications
    Example output
    {
"notifications": [
    {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": null,
    "event": "quota_warning",
    "method": "email",
    "config": {},
    "event_config": {},
    "number_of_failures": 0
    }
]
}

  3. List all notifications for your user namespace by entering a command similar to the following example:

    $ curl -X GET \
-H "Authorization: Bearer <bearer_token>" \
-H "Accept: application/json" \
https://<quay-server.example.com>/api/v1/user/namespacenotifications

  4. To test a notification, enter a command similar to the following example:

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications/<uuid>/test
    Example output
    {}
    Note

    For email notifications, if an organization contact email is set, the test notification is routed to that address. Otherwise, email notifications default to organization administrators. For Slack, webhook, and other methods, routing follows the notification config.

Repository events description

Repository events in Project Quay describe the triggers that can generate notifications. You can use these event types when you configure alerts.

Repository Push

A successful push of one or more images was made to the repository:

{
  "name": "repository",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "homepage": "https://quay.io/repository/dgangaia/repository",
  "updated_tags": [
    "latest"
  ]
}
Dockerfile Build Queued

The following example is a response from a Dockerfile Build that has been queued into the Build system.

Note

Responses can differ based on the use of optional attributes.

 
{
  "build_id": "296ec063-5f86-4706-a469-f0a400bf9df2",
  "trigger_kind": "github",                                                       //Optional
  "name": "test",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e",                           //Optional
  "docker_tags": [
    "master",
    "latest"
  ],
  "repo": "test",
  "trigger_metadata": {
    "default_branch": "master",
    "commit": "b7f7d2b948aacbe844ee465122a85a9368b2b735",
    "ref": "refs/heads/master",
    "git_url": "git@github.com:dgangaia/test.git",
    "commit_info": {                                                             //Optional
      "url": "https://github.com/dgangaia/test/commit/b7f7d2b948aacbe844ee465122a85a9368b2b735",
      "date": "2019-03-06T12:48:24+11:00",
      "message": "adding 5",
      "author": {                                                                //Optional
        "username": "dgangaia",
        "url": "https://github.com/dgangaia",                                    //Optional
        "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4"    //Optional
      },
      "committer": {
        "username": "web-flow",
        "url": "https://github.com/web-flow",
        "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4"
      }
    }
  },
  "is_manual": false,
  "manual_user": null,
  "homepage": "https://quay.io/repository/dgangaia/test/build/296ec063-5f86-4706-a469-f0a400bf9df2"
}
Dockerfile Build started

The following example is a response from a Dockerfile Build that has been queued into the Build system.

Note

Responses can differ based on the use of optional attributes.

 
{
  "build_id": "a8cc247a-a662-4fee-8dcb-7d7e822b71ba",
  "trigger_kind": "github",                                                     //Optional
  "name": "test",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e",                         //Optional
  "docker_tags": [
    "master",
    "latest"
  ],
  "build_name": "50bc599",
  "trigger_metadata": {                                                         //Optional
    "commit": "50bc5996d4587fd4b2d8edc4af652d4cec293c42",
    "ref": "refs/heads/master",
    "default_branch": "master",
    "git_url": "git@github.com:dgangaia/test.git",
    "commit_info": {                                                            //Optional
      "url": "https://github.com/dgangaia/test/commit/50bc5996d4587fd4b2d8edc4af652d4cec293c42",
      "date": "2019-03-06T14:10:14+11:00",
      "message": "test build",
      "committer": {                                                            //Optional
        "username": "web-flow",
        "url": "https://github.com/web-flow",                                   //Optional
        "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4"   //Optional
      },
      "author": {                                                               //Optional
        "username": "dgangaia",
        "url": "https://github.com/dgangaia",                                   //Optional
        "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4"   //Optional
      }
    }
  },
  "homepage": "https://quay.io/repository/dgangaia/test/build/a8cc247a-a662-4fee-8dcb-7d7e822b71ba"
}
Dockerfile Build successfully completed

The following example is a response from a Dockerfile Build that has been successfully completed by the Build system.

Note

This event occurs simultaneously with a Repository Push event for the built image or images.

 
{
  "build_id": "296ec063-5f86-4706-a469-f0a400bf9df2",
  "trigger_kind": "github",                                                       //Optional
  "name": "test",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e",                           //Optional
  "docker_tags": [
    "master",
    "latest"
  ],
  "build_name": "b7f7d2b",
  "image_id": "sha256:0339f178f26ae24930e9ad32751d6839015109eabdf1c25b3b0f2abf8934f6cb",
  "trigger_metadata": {
    "commit": "b7f7d2b948aacbe844ee465122a85a9368b2b735",
    "ref": "refs/heads/master",
    "default_branch": "master",
    "git_url": "git@github.com:dgangaia/test.git",
    "commit_info": {                                                              //Optional
      "url": "https://github.com/dgangaia/test/commit/b7f7d2b948aacbe844ee465122a85a9368b2b735",
      "date": "2019-03-06T12:48:24+11:00",
      "message": "adding 5",
      "committer": {                                                              //Optional
        "username": "web-flow",
        "url": "https://github.com/web-flow",                                     //Optional
        "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4"                                                        //Optional
      },
      "author": {                                                                 //Optional
        "username": "dgangaia",
        "url": "https://github.com/dgangaia",                                     //Optional
        "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4"     //Optional
      }
    }
  },
  "homepage": "https://quay.io/repository/dgangaia/test/build/296ec063-5f86-4706-a469-f0a400bf9df2",
  "manifest_digests": [
    "quay.io/dgangaia/test@sha256:2a7af5265344cc3704d5d47c4604b1efcbd227a7a6a6ff73d6e4e08a27fd7d99",
    "quay.io/dgangaia/test@sha256:569e7db1a867069835e8e97d50c96eccafde65f08ea3e0d5debaf16e2545d9d1"
  ]
}
Dockerfile Build failed

The following example is a response from a Dockerfile Build that has failed.

{
  "build_id": "5346a21d-3434-4764-85be-5be1296f293c",
  "trigger_kind": "github",                                                       //Optional
  "name": "test",
  "repository": "dgangaia/test",
  "docker_url": "quay.io/dgangaia/test",
  "error_message": "Could not find or parse Dockerfile: unknown instruction: GIT",
  "namespace": "dgangaia",
  "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e",                           //Optional
  "docker_tags": [
    "master",
    "latest"
  ],
  "build_name": "6ae9a86",
  "trigger_metadata": {                                                           //Optional
    "commit": "6ae9a86930fc73dd07b02e4c5bf63ee60be180ad",
    "ref": "refs/heads/master",
    "default_branch": "master",
    "git_url": "git@github.com:dgangaia/test.git",
    "commit_info": {                                                              //Optional
      "url": "https://github.com/dgangaia/test/commit/6ae9a86930fc73dd07b02e4c5bf63ee60be180ad",
      "date": "2019-03-06T14:18:16+11:00",
      "message": "failed build test",
      "committer": {                                                              //Optional
        "username": "web-flow",
        "url": "https://github.com/web-flow",                                     //Optional
        "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4"     //Optional
      },
      "author": {                                                                 //Optional
        "username": "dgangaia",
        "url": "https://github.com/dgangaia",                                     //Optional
        "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4"     //Optional
      }
    }
  },
  "homepage": "https://quay.io/repository/dgangaia/test/build/5346a21d-3434-4764-85be-5be1296f293c"
}
Dockerfile Build cancelled

The following example is a response from a Dockerfile Build that has been cancelled.

{
  "build_id": "cbd534c5-f1c0-4816-b4e3-55446b851e70",
  "trigger_kind": "github",
  "name": "test",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e",
  "docker_tags": [
    "master",
    "latest"
  ],
  "build_name": "cbce83c",
  "trigger_metadata": {
    "commit": "cbce83c04bfb59734fc42a83aab738704ba7ec41",
    "ref": "refs/heads/master",
    "default_branch": "master",
    "git_url": "git@github.com:dgangaia/test.git",
    "commit_info": {
      "url": "https://github.com/dgangaia/test/commit/cbce83c04bfb59734fc42a83aab738704ba7ec41",
      "date": "2019-03-06T14:27:53+11:00",
      "message": "testing cancel build",
      "committer": {
        "username": "web-flow",
        "url": "https://github.com/web-flow",
        "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4"
      },
      "author": {
        "username": "dgangaia",
        "url": "https://github.com/dgangaia",
        "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4"
      }
    }
  },
  "homepage": "https://quay.io/repository/dgangaia/test/build/cbd534c5-f1c0-4816-b4e3-55446b851e70"
}

Configure build worker environments

Configure TLS, bare metal, and virtual build worker environments for Project Quay on OpenShift Container Platform, including managed-route constraints, optional EC2 builder fallback, and object storage prerequisites for virtual builds.

Configuring the OpenShift Container Platform TLS component for builds

To enable the builds feature with unmanaged TLS in Project Quay, you can add the builder route name to the Subject Alternative Name (SAN) field in your SSL/TLS certificate configuration.

The tls component of the QuayRegistry custom resource definition (CRD) allows you to control whether SSL/TLS are managed by the Project Quay Operator, or self managed. In its current state, Project Quay does not support the builds feature, or the builder workers, when the tls component is managed by the Project Quay Operator.

When setting the tls component to unmanaged, you must supply your own ssl.cert and ssl.key files. Additionally, if you want your cluster to support builders, or the worker nodes that are responsible for building images, you must add both the Quay route and the builder route name to the SAN list in the certificate. Alternatively, however, you could use a wildcard.

Prerequisites

  • You have set the tls component to unmanaged and uploaded custom SSL/TLS certificates to the Project Quay Operator. For more information, see SSL and TLS for Project Quay.

Procedure

  • In the configuration file that defines your SSL/TLS certificate parameters, for example, openssl.cnf, add the following information to the certificate’s Subject Alternative Name (SAN) field. For example:

    # ...
[alt_names]
<quay_registry_name>-quay-builder-<namespace>.<domain-name>:443
# ...

    For example:

    # ...
[alt_names]
example-registry-quay-builder-quay-enterprise.apps.cluster-new.gcp.quaydev.org:443
# ...

Bare metal builds

Bare metal builds run Project Quay build workers on physical Red Hat Quay on OpenShift Container Platform or Kubernetes nodes so you can use existing hardware capacity for Dockerfile builds.

Use bare metal builds when you want builders on dedicated worker nodes and can accept container-level isolation rather than a full virtual machine per build. Plan for labeled worker nodes that can schedule build pods, a builder service account with the required permissions, and network access from builders to the build manager and to your Git sources.

Configure bare metal builder infrastructure when you are ready to implement builds; planning focuses on node capacity, isolation tradeoffs, and whether bare metal or virtual builders better match your security model.

Configuring bare metal builds for Red Hat Quay on OpenShift Container Platform

To configure bare metal builds for Red Hat Quay on OpenShift Container Platform with Project Quay, you can create a build project, configure service accounts, and update your configuration file.

Note

If you are using the Project Quay Operator on OpenShift Container Platform with a managed route component in your QuayRegistry CRD, see "Red Hat Quay on OpenShift Container Platform builds limitations with self-managed routes".
Prerequisites

  • You have an OpenShift Container Platform cluster provisioned with the Project Quay Operator running.

  • You have set the tls component to unmanaged and uploaded custom SSL/TLS certificates to the Project Quay Operator. For more information, see SSL and TLS for Project Quay.

  • You are logged into OpenShift Container Platform as a cluster administrator.

Procedure

  1. Enter the following command to create a project where Builds will be run, for example, bare-metal-builder:

    $ oc new-project bare-metal-builder

  2. Create a new ServiceAccount in the bare-metal-builder namespace by entering the following command:

    $ oc create sa -n bare-metal-builder quay-builder

  3. Enter the following command to grant a user the edit role within the bare-metal-builder namespace:

    $ oc policy add-role-to-user -n bare-metal-builder edit system:serviceaccount:bare-metal-builder:quay-builder

  4. Enter the following command to retrieve a token associated with the quay-builder service account in the bare-metal-builder namespace. This token is used to authenticate and interact with the OpenShift Container Platform cluster’s API server.

    1. If your OpenShift Container Platform cluster is version 4.11+, enter the following command:

      oc create token quay-builder  -n bare-metal-builder --duration 24h

    2. If your OpenShift Container Platform cluster is earlier than version 4.11, for example, version 4.10, enter the following command:

      $ oc sa get-token -n bare-metal-builder quay-builder

  5. Identify the URL for the OpenShift Container Platform cluster’s API server. This can be found in the OpenShift Container Platform web console.

  6. Identify a worker node label to be used when scheduling build jobs. Because build pods must run on bare metal worker nodes, typically these are identified with specific labels.

    Check with your cluster administrator to determine exactly which node label should be used.

  7. Obtain the Kube API Server’s certificate authority (CA) to add to Project Quay’s extra certificates.

    1. On OpenShift Container Platform versions 4.15+, enter the following commands to obtain the name of the secret containing the CA:

      $ oc extract cm/kube-root-ca.crt -n openshift-apiserver
      $ mv ca.crt build_cluster.crt

    2. On OpenShift Container Platform versions earlier than 4.15, for example, 4.14, enter the following command:

      $ oc get sa openshift-apiserver-sa --namespace=openshift-apiserver -o json | jq '.secrets[] | select(.name | contains("openshift-apiserver-sa-token"))'.name

    3. Obtain the ca.crt key value from the secret in the OpenShift Container Platform Web Console. The value begins with "-----BEGIN CERTIFICATE-----"`.

    4. Import the CA to Project Quay. Ensure that the name of this file matches the K8S_API_TLS_CA field used in Step 9.

  8. Create the following SecurityContextConstraints resource for the ServiceAccount:

    apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  name: quay-builder
priority: null
readOnlyRootFilesystem: false
requiredDropCapabilities: null
runAsUser:
  type: RunAsAny
seLinuxContext:
  type: RunAsAny
seccompProfiles:
- '*'
supplementalGroups:
  type: RunAsAny
volumes:
- '*'
allowHostDirVolumePlugin: true
allowHostIPC: true
allowHostNetwork: true
allowHostPID: true
allowHostPorts: true
allowPrivilegeEscalation: true
allowPrivilegedContainer: true
allowedCapabilities:
- '*'
allowedUnsafeSysctls:
- '*'
defaultAddCapabilities: null
fsGroup:
  type: RunAsAny
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: quay-builder-scc
  namespace: bare-metal-builder
rules:
- apiGroups:
  - security.openshift.io
  resourceNames:
  - quay-builder
  resources:
  - securitycontextconstraints
  verbs:
  - use
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: quay-builder-scc
  namespace: bare-metal-builder
subjects:
- kind: ServiceAccount
  name: quay-builder
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: quay-builder-scc

  9. Update the config.yaml file of your Red Hat Quay on OpenShift Container Platform deployment to include an appropriate bare metal builds configuration by using the OpenShift Container Platform web console.

    1. Click Operators → Installed Operators → Red Hat Quay → Quay Registry.

    2. Click the name of your registry, for example, example-registry.

    3. Under Config Bundle Secret, click the name of your configuration bundle, for example, extra-ca-certificate-config-bundle-secret.

    4. Click Actions → Edit Secret.

    5. Add the following information to your Project Quay config.yaml file, replacing each value with information that is relevant to your specific installation:

      FEATURE_USER_INITIALIZE: true
BROWSER_API_CALLS_XHR_ONLY: false
SUPER_USERS:
- <superusername>
FEATURE_USER_CREATION: false
FEATURE_QUOTA_MANAGEMENT: true
FEATURE_BUILD_SUPPORT: True
BUILDMAN_HOSTNAME: ${BUILDMAN_HOSTNAME}:443
BUILD_MANAGER:
- ephemeral
- ALLOWED_WORKER_COUNT: 10
  ORCHESTRATOR_PREFIX: buildman/production/
    ORCHESTRATOR:
      REDIS_HOST: <sample_redis_hostname>
      REDIS_PASSWORD: ""
      REDIS_SSL: false
      REDIS_SKIP_KEYSPACE_EVENT_SETUP: false
  EXECUTORS:
  - EXECUTOR: kubernetes
    BUILDER_NAMESPACE: <sample_builder_namespace>
    K8S_API_SERVER: <sample_k8s_api_server>
    K8S_API_TLS_CA: <sample_crt_file>
    VOLUME_SIZE: 8G
    KUBERNETES_DISTRIBUTION: openshift
    CONTAINER_MEMORY_LIMITS: 1G
    CONTAINER_CPU_LIMITS: 300m
    CONTAINER_MEMORY_REQUEST: 1G
    CONTAINER_CPU_REQUEST: 300m
    NODE_SELECTOR_LABEL_KEY: beta.kubernetes.io/instance-type
    NODE_SELECTOR_LABEL_VALUE: n1-standard-4
    CONTAINER_RUNTIME: podman
    SERVICE_ACCOUNT_NAME: <sample_service_account_name>
    SERVICE_ACCOUNT_TOKEN: <sample_account_token>
    QUAY_USERNAME: <quay_username>
    QUAY_PASSWORD: <quay_password>
    WORKER_IMAGE: <registry>/quay-quay-builder
    WORKER_TAG: <some_tag>
    BUILDER_VM_CONTAINER_IMAGE: registry.redhat.io/quay/quay-builder-qemu-rhcos-rhel8:v3.9.10-4
    SETUP_TIME: 180
    MINIMUM_RETRY_THRESHOLD: 0
    SSH_AUTHORIZED_KEYS:
    - <ssh-rsa 12345 someuser@email.com>
    - <ssh-rsa 67890 someuser2@email.com>
    HTTP_PROXY: <http://10.0.0.1:80>
    HTTPS_PROXY: <http://10.0.0.1:80>
    NO_PROXY: <hostname.example.com>

      where:

      BUILDMAN_HOSTNAME

      Specifies the hostname of the Project Quay registry. Obtain this by running the following command: $ oc get route quayregistry-quay-builder -n ${QUAY_PROJECT} -o jsonpath='{.spec.host}'.

      BUILD_MANAGER.ORCHESTRATOR.REDIS_HOST

      Specifies the hostname for your Redis service.

      BUILD_MANAGER.EXECUTORS.BUILDER_NAMESPACE

      Specifies the name of your bare metal builds namespace. This example used bare-metal-builder.

      BUILD_MANAGER.EXECUTORS.K8S_API_SERVER

      Specifies the K8S_API_SERVER is obtained by running $ oc cluster-info.

      BUILD_MANAGER.EXECUTORS.K8S_API_TLS_CA

      Specifies the name of your custom CA cert, for example, K8S_API_TLS_CA: /conf/stack/extra_ca_certs/build-cluster.crt.

      BUILD_MANAGER.EXECUTORS.CONTAINER_MEMORY_LIMITS

      Specifies the memory limit for your container. Defaults to 5120Mi if left unspecified.

      BUILD_MANAGER.EXECUTORS.CONTAINER_CPU_LIMITS

      Specifies the CPU limit for your container. Defaults to 1000m if left unspecified.

      BUILD_MANAGER.EXECUTORS.CONTAINER_MEMORY_REQUEST

      Specifies the memory request for your container. Defaults to 3968Mi if left unspecified.

      BUILD_MANAGER.EXECUTORS.CONTAINER_CPU_REQUEST

      Specifies the CPU request for your container. Defaults to 500m if left unspecified.

      BUILD_MANAGER.EXECUTORS.SERVICE_ACCOUNT_TOKEN

      Specifies the token for your service account. Obtain this by running $ oc create sa.

      BUILD_MANAGER.EXECUTORS.SSH_AUTHORIZED_KEYS

      Specifies the SSH authorized keys for your build environment. This key, or keys, should correspond to the private key that an admin or developer will use to SSH into the build worker for debugging purposes. This key can be obtained by establishing an SSH connection to the remote host using a specific SSH key and port. For example: $ ssh -i /path/to/ssh/key/set/in/ssh_authorized_keys -p 9999 core@localhost.

  10. Restart your Project Quay registry to enable the builds feature.

Builds limitations with managed routes

Project Quay builds have networking constraints when Red Hat Quay on OpenShift Container Platform uses managed routes. Plan for these constraints so build workers can reach the build manager.

OpenShift Container Platform routes typically serve traffic on a single port. Because builds use gRPC, the Operator creates a dedicated Route that directs that traffic to the build manager.

When you plan builds on OpenShift Container Platform, account for the following:

  • OpenShift ingress must support HTTP/2 for the gRPC protocol used by the build manager.

  • The build manager needs the build cluster CA certificate in the Project Quay configuration so workers can establish a secure connection.

  • Build jobs must resolve the build manager hostname. Custom subdomains require DNS that points to the OpenShift router.

See "Configuring Project Quay builds for managed routes" for implementation steps.

Configuring Project Quay builds for managed routes

To use Project Quay builds with managed routes and custom hostnames, you can configure DNS records and update your registry configuration. This enables gRPC communication between build executors and the build manager.

Prerequisites

  • The Project Quay Operator is installed and a QuayRegistry exists.

  • Your kubectl or oc CLI tool is configured for the target cluster.

Procedure

  1. Enable HTTP/2 ingress on your OpenShift Container Platform cluster to support gRPC.

  2. Retrieve the host address of the generated build-manager route:

    $ kubectl get -n <namespace> route <quayregistry-name>-quay-builder -o jsonpath={.status.ingress[0].host}

  3. Create a CNAME record with your DNS provider that points your custom hostname (for example, builder-registry.example.com) to the route host retrieved in the previous step.

  4. Update the Secret referenced by spec.configBundleSecret in your QuayRegistry to include the build cluster CA certificate. The key must be named extra_ca_cert_build_cluster.cert.

  5. Add the BUILDMAN_HOSTNAME field to your config.yaml and include the port number:

    BUILDMAN_HOSTNAME: builder-registry.example.com:443
BUILD_MANAGER:
- ephemeral
  ALLOWED_WORKER_COUNT: 1
  ...

Virtual builds

Virtual builds in Project Quay run build workers in unprivileged containers on Red Hat Quay on OpenShift Container Platform. This approach provides process isolation without requiring a dedicated virtual machine for each build.

With virtual builds, the build manager creates a Kubernetes Job that starts a pod from the builder image. That image includes the builder binary and Podman. The pod runs unprivileged; the builder builds the image and reports status to the build manager.

Virtual builds limitations

The following limitations apply to virtual builds:

  • Running virtual builds in an unprivileged context might cause some Dockerfile commands that worked under a previous build strategy to fail. Changing build strategy can also affect build performance and reliability.

  • Running virtual builds directly in a container does not provide the same isolation as virtual machines. Changing the build environment might cause builds that previously succeeded to fail.

Configuring virtual builds for Red Hat Quay on OpenShift Container Platform

To configure virtual builds for Red Hat Quay on OpenShift Container Platform with Project Quay, you can create a build project, configure service accounts, and update your configuration file.

Note

  • If you are using Amazon Web Service (AWS) S3 storage, you must modify your storage bucket in the AWS console, prior to running builders. See "Modifying your AWS S3 storage bucket" in the following section for the required parameters.

  • If you are using a Google Cloud Platform (GCP) object bucket, you must configure cross-origin resource sharing (CORS) to enable virtual builds.
Prerequisites

  • You have an OpenShift Container Platform cluster provisioned with the Project Quay Operator running.

  • You have set the tls component to unmanaged and uploaded custom SSL/TLS certificates to the Project Quay Operator. For more information, see SSL and TLS for Project Quay.

  • You have configured the OpenShift Container Platform TLS component for builds.

  • You are logged into OpenShift Container Platform as a cluster administrator.

Procedure

  1. Create a new project where your virtual builders will be run, for example, virtual-builders, by running the following command:

    $ oc new-project virtual-builders

  2. Create a ServiceAccount in the project that will be used to run builds by entering the following command:

    $ oc create sa -n virtual-builders quay-builder
    Example output
    serviceaccount/quay-builder created

  3. Provide the created service account with editing permissions so that it can run a build:

    $ oc adm policy -n virtual-builders add-role-to-user edit system:serviceaccount:virtual-builders:quay-builder
    Example output
    clusterrole.rbac.authorization.k8s.io/edit added: "system:serviceaccount:virtual-builders:quay-builder"

  4. Grant the builder worker anyuid scc permissions by entering the following command. This requires cluster administrator privileges, which is required because builders must run as the Podman user for unprivileged or rootless builds to work.

    $ oc adm policy -n virtual-builders add-scc-to-user anyuid -z quay-builder
    Example output
    clusterrole.rbac.authorization.k8s.io/system:openshift:scc:anyuid added: "quay-builder"

  5. Obtain the token for the builder service account by entering the following command:

    $ oc create token quay-builder -n virtual-builders
    Note

    When the token expires you will need to request a new token. Optionally, you can also add a custom expiration. For example, specify --duration 20160m to retain the token for two weeks.
    Example output
    eyJhbGciOiJSUzI1NiIsImtpZCI6IldfQUJkaDVmb3ltTHZ0dGZMYjhIWnYxZTQzN2dJVEJxcDJscldSdEUtYWsifQ...

  6. Determine the builder route by entering the following command:

    $ oc get route -n quay-enterprise
    Example output
    NAME: example-registry-quay-builder
HOST/PORT: example-registry-quay-builder-quay-enterprise.apps.stevsmit-cluster-new.gcp.quaydev.org
PATH:
SERVICES: example-registry-quay-app
PORT: grpc
TERMINATION: passthrough/Redirect
WILDCARD: None

  7. Generate a self-signed SSL/TLS certificate with the .crt extension by entering the following command:

    $ oc extract cm/kube-root-ca.crt -n openshift-apiserver
    Example output
    ca.crt

  8. Rename the ca.crt file to build-cluster.crt by entering the following command:

    $ mv ca.crt build-cluster.crt

  9. Update the config.yaml file of your Red Hat Quay on OpenShift Container Platform deployment to include an appropriate virtual builds configuration by using the OpenShift Container Platform web console.

    1. Click Operators → Installed Operators → Red Hat Quay → Quay Registry.

    2. Click the name of your registry, for example, example-registry.

    3. Under Config Bundle Secret, click the name of your configuration bundle, for example, extra-ca-certificate-config-bundle-secret.

    4. Click Actions → Edit Secret.

    5. Add an appropriate virtual builds configuration using the following as a reference:

      FEATURE_USER_INITIALIZE: true
BROWSER_API_CALLS_XHR_ONLY: false
SUPER_USERS:
- <superusername>
FEATURE_USER_CREATION: false
FEATURE_QUOTA_MANAGEMENT: true
FEATURE_BUILD_SUPPORT: True
BUILDMAN_HOSTNAME: <sample_build_route>
BUILD_MANAGER:
  - ephemeral
  - ALLOWED_WORKER_COUNT: 1
    ORCHESTRATOR_PREFIX: buildman/production/
    JOB_REGISTRATION_TIMEOUT: 3600
    ORCHESTRATOR:
      REDIS_HOST: <sample_redis_hostname>
      REDIS_PASSWORD: ""
      REDIS_SSL: false
      REDIS_SKIP_KEYSPACE_EVENT_SETUP: false
    EXECUTORS:
      - EXECUTOR: kubernetesPodman
        NAME: openshift
        BUILDER_NAMESPACE: <sample_builder_namespace>
        SETUP_TIME: 180
        MINIMUM_RETRY_THRESHOLD: 0
        BUILDER_CONTAINER_IMAGE: quay.io/projectquay/quay-builder:{producty}
        # Kubernetes resource options
        K8S_API_SERVER: <sample_k8s_api_server>
        K8S_API_TLS_CA: <sample_crt_file>
        VOLUME_SIZE: 8G
        KUBERNETES_DISTRIBUTION: openshift
        CONTAINER_MEMORY_LIMITS: 1G
        CONTAINER_CPU_LIMITS: 300m
        CONTAINER_MEMORY_REQUEST: 1G
        CONTAINER_CPU_REQUEST: 300m
        NODE_SELECTOR_LABEL_KEY: ""
        NODE_SELECTOR_LABEL_VALUE: ""
        SERVICE_ACCOUNT_NAME: <sample_service_account_name>
        SERVICE_ACCOUNT_TOKEN: <sample_account_token>
        HTTP_PROXY: <http://10.0.0.1:80>
        HTTPS_PROXY: <http://10.0.0.1:80>
        NO_PROXY: <hostname.example.com>

      where:

      BUILDMAN_HOSTNAME

      Specifies that the build route is obtained by running $ oc get route -n with the namespace of your Red Hat Quay on OpenShift Container Platform deployment. A port must be provided at the end of the route, and it should use the following format: [quayregistry-cr-name]-quay-builder-[ocp-namespace].[ocp-domain-name]:443.

      BUILD_MANAGER.JOB_REGISTRATION_TIMEOUT

      Specifies that you might receive the following error when set too low: failed to register job to build manager: rpc error: code = Unauthenticated desc = Invalid build token: Signature has expired. This parameter should be set to at least 240.

      BUILD_MANAGER.ORCHESTRATOR.REDIS_HOST

      Specifies that you must update this field accordingly if your Redis host has a password or SSL/TLS certificates.

      BUILD_MANAGER.EXECUTORS.BUILDER_NAMESPACE

      Specifies the name of your virtual builds namespace. This example used virtual-builders.

      BUILD_MANAGER.EXECUTORS.K8S_API_SERVER

      Specifies the value obtained by running $ oc cluster-info.

      BUILD_MANAGER.EXECUTORS.K8S_API_TLS_CA

      Specifies that you must manually create and add your custom CA cert, for example, K8S_API_TLS_CA: /conf/stack/extra_ca_certs/build-cluster.crt.

      BUILD_MANAGER.EXECUTORS.CONTAINER_MEMORY_LIMITS

      Specifies the memory limit. Defaults to 5120Mi if left unspecified.

      BUILD_MANAGER.EXECUTORS.CONTAINER_CPU_LIMITS

      Specifies that for virtual builds, you must ensure that there are enough resources in your cluster. Defaults to 1000m if left unspecified.

      BUILD_MANAGER.EXECUTORS.CONTAINER_MEMORY_REQUEST

      Specifies the memory request. Defaults to 3968Mi if left unspecified.

      BUILD_MANAGER.EXECUTORS.CONTAINER_CPU_REQUEST

      Specifies the CPU request. Defaults to 500m if left unspecified.

      BUILD_MANAGER.EXECUTORS.SERVICE_ACCOUNT_TOKEN

      Specifies the token obtained when running $ oc create sa.

      Example virtual builds configuration
      FEATURE_USER_INITIALIZE: true
BROWSER_API_CALLS_XHR_ONLY: false
SUPER_USERS:
- quayadmin
FEATURE_USER_CREATION: false
FEATURE_QUOTA_MANAGEMENT: true
FEATURE_BUILD_SUPPORT: True
BUILDMAN_HOSTNAME: example-registry-quay-builder-quay-enterprise.apps.docs.quayteam.org:443
BUILD_MANAGER:
  - ephemeral
  - ALLOWED_WORKER_COUNT: 1
    ORCHESTRATOR_PREFIX: buildman/production/
    JOB_REGISTRATION_TIMEOUT: 3600
    ORCHESTRATOR:
      REDIS_HOST: example-registry-quay-redis
      REDIS_PASSWORD: ""
      REDIS_SSL: false
      REDIS_SKIP_KEYSPACE_EVENT_SETUP: false
    EXECUTORS:
      - EXECUTOR: kubernetesPodman
        NAME: openshift
        BUILDER_NAMESPACE: virtual-builders
        SETUP_TIME: 180
        MINIMUM_RETRY_THRESHOLD: 0
        BUILDER_CONTAINER_IMAGE: quay.io/projectquay/quay-builder:{producty}
        # Kubernetes resource options
        K8S_API_SERVER: api.docs.quayteam.org:6443
        K8S_API_TLS_CA: /conf/stack/extra_ca_certs/build-cluster.crt
        VOLUME_SIZE: 8G
        KUBERNETES_DISTRIBUTION: openshift
        CONTAINER_MEMORY_LIMITS: 1G
        CONTAINER_CPU_LIMITS: 300m
        CONTAINER_MEMORY_REQUEST: 1G
        CONTAINER_CPU_REQUEST: 300m
        NODE_SELECTOR_LABEL_KEY: ""
        NODE_SELECTOR_LABEL_VALUE: ""
        SERVICE_ACCOUNT_NAME: quay-builder
        SERVICE_ACCOUNT_TOKEN: "eyJhbGciOiJSUzI1NiIsImtpZCI6IldfQUJkaDVmb3ltTHZ0dGZMYjhIWnYxZTQzN2dJVEJxcDJscldSdEUtYWsifQ"
        HTTP_PROXY: <http://10.0.0.1:80>
        HTTPS_PROXY: <http://10.0.0.1:80>
        NO_PROXY: <hostname.example.com>

    6. Click Save on the Edit Secret page.

  10. Restart your Red Hat Quay on OpenShift Container Platform registry with the new configuration.

Modifying your AWS S3 storage bucket

To enable builds with AWS S3 storage in Project Quay, you can configure cross-origin resource sharing (CORS) settings in your S3 bucket. This allows build workers to access and store build artifacts in your S3 bucket.

Procedure

  1. Log in to your AWS console at s3.console.aws.com.

  2. In the search bar, search for S3 and then click S3.

  3. Click the name of your bucket, for example, myawsbucket.

  4. Click the Permissions tab.

  5. Under Cross-origin resource sharing (CORS), include the following parameters:

      [
      {
          "AllowedHeaders": [
              "Authorization"
          ],
          "AllowedMethods": [
              "GET"
          ],
          "AllowedOrigins": [
              "*"
          ],
          "ExposeHeaders": [],
          "MaxAgeSeconds": 3000
      },
      {
          "AllowedHeaders": [
              "Content-Type",
              "x-amz-acl",
              "origin"
          ],
          "AllowedMethods": [
              "PUT"
          ],
          "AllowedOrigins": [
              "*"
          ],
          "ExposeHeaders": [],
          "MaxAgeSeconds": 3000
      }
  ]
Modifying your Google Cloud Platform object bucket

To enable virtual builds with Google Cloud Platform storage in Project Quay, you can configure cross-origin resource sharing (CORS) settings in your GCP bucket. This allows build workers to upload Dockerfiles and access build artifacts.

Note

Currently, modifying your Google Cloud Platform object bucket is not supported on IBM Power and IBM Z.
Procedure

  1. Use the following reference to create a JSON file for your specific CORS needs. For example:

    $ cat gcp_cors.json
    Example output
    [
    {
      "origin": ["*"],
      "method": ["GET"],
      "responseHeader": ["Authorization"],
      "maxAgeSeconds": 3600
    },
    {
      "origin": ["*"],
      "method": ["PUT"],
      "responseHeader": [
              "Content-Type",
              "x-goog-acl",
              "origin"],
      "maxAgeSeconds": 3600
    }
]

  2. Enter the following command to update your GCP storage bucket:

    $ gcloud storage buckets update gs://<bucket_name> --cors-file=./gcp_cors.json
    Example output
    Updating
  Completed 1

  3. You can display the updated CORS configuration of your GCP bucket by running the following command:

    $ gcloud storage buckets describe gs://<bucket_name>  --format="default(cors)"
    Example output
    cors:
- maxAgeSeconds: 3600
  method:
  - GET
  origin:
  - '*'
  responseHeader:
  - Authorization
- maxAgeSeconds: 3600
  method:
  - PUT
  origin:
  - '*'
  responseHeader:
  - Content-Type
  - x-goog-acl
  - origin

Build automation configuration fields

Optional configuration fields for Dockerfile build triggers, the build manager, and build logs.

Builds and Automation

The following configuration fields manage automated builds within Project Quay. These settings control how Dockerfile builds are triggered, processed, and stored, and how build logs are managed and accessed.

You can use these fields to:

  • Enable or disable automated builds from source repositories.

  • Configure the behavior and resource management of the build manager.

  • Control access to and retention of build logs for auditing or debugging purposes.

These options help you streamline your CI/CD pipeline, enforce build policies, and retain visibility into your build history across the registry.

Additional resources

Dockerfile build triggers fields

The following configuration fields are used to enable and manage automated builds in Project Quay from Dockerfiles and source code repositories. These fields allow you to define build behavior, enable or disable support for GitHub, GitLab, and Bitbucket triggers, and provide OAuth credentials and endpoints for each SCM provider.

Table 57. Dockerfile build support
Field Type Description

FEATURE_BUILD_SUPPORT

Boolean

Whether to support Dockerfile build.

Default: False

SUCCESSIVE_TRIGGER_FAILURE_DISABLE_THRESHOLD

Number

If not set to None, the number of successive failures that can occur before a build trigger is automatically disabled.

Default: 100

SUCCESSIVE_TRIGGER_INTERNAL_ERROR_DISABLE_THRESHOLD

Number

If not set to None, the number of successive internal errors that can occur before a build trigger is automatically disabled

Default: 5
Dockerfile build support example YAML
# ...
FEATURE_BUILD_SUPPORT: true
SUCCESSIVE_TRIGGER_FAILURE_DISABLE_THRESHOLD: 100
SUCCESSIVE_TRIGGER_INTERNAL_ERROR_DISABLE_THRESHOLD: 5
# ...
Table 58. GitHub build triggers
Field Type Description

FEATURE_GITHUB_BUILD

Boolean

Whether to support GitHub build triggers.

Default: False

GITHUB_TRIGGER_CONFIG

Object

Configuration for using GitHub Enterprise for build triggers.

   .GITHUB_ENDPOINT    (Required)

String

The endpoint for GitHub Enterprise. Example: https://github.com/

   .API_ENDPOINT

String

The endpoint of the GitHub Enterprise API to use. Must be overridden for github.com. Example: https://api.github.com/

   .CLIENT_ID    (Required)

String

The registered client ID for this Project Quay instance; this cannot be shared with GITHUB_LOGIN_CONFIG.

   .CLIENT_SECRET    (Required)

String

The registered client secret for this Project Quay instance.
Github build triggers example YAML
# ...
FEATURE_GITHUB_BUILD: true
GITHUB_TRIGGER_CONFIG:
  GITHUB_ENDPOINT: https://github.com/
  API_ENDPOINT: https://api.github.com/
  CLIENT_ID: your-client-id
  CLIENT_SECRET: your-client-secret
# ...
Table 59. BitBucket build triggers
Field Type Description

FEATURE_BITBUCKET_BUILD

Boolean

Whether to support Bitbucket build triggers.

Default: False

BITBUCKET_TRIGGER_CONFIG

Object

Configuration for using BitBucket for build triggers.

   .CONSUMER_KEY    (Required)

String

The registered consumer key (client ID) for this Project Quay instance.

   .CONSUMER_SECRET    (Required)

String

The registered consumer secret (client secret) for this Project Quay instance.
Bitbucket build triggers example YAML
# ...
FEATURE_BITBUCKET_BUILD: true
BITBUCKET_TRIGGER_CONFIG:
  CONSUMER_KEY: <your_consumer_key>
  CONSUMER_SECRET: <your-consumer-secret>
# ...
Table 60. GitLab build triggers
Field Type Description

FEATURE_GITLAB_BUILD

Boolean

Whether to support GitLab build triggers.

Default: False

GITLAB_TRIGGER_CONFIG

Object

Configuration for using Gitlab for build triggers.

   .GITLAB_ENDPOINT    (Required)

String

The endpoint at which Gitlab Enterprise is running.

   .CLIENT_ID    (Required)

String

The registered client ID for this Project Quay instance.

   .CLIENT_SECRET    (Required)

String

The registered client secret for this Project Quay instance.
GitLab build triggers example YAML
# ...
FEATURE_GITLAB_BUILD: true
GITLAB_TRIGGER_CONFIG:
  GITLAB_ENDPOINT: https://gitlab.example.com/
  CLIENT_ID: <your_gitlab_client_id>
  CLIENT_SECRET: <your_gitlab_client_secret>
# ...

Build manager configuration fields

The following configuration fields control how the build manager component of Project Quay orchestrates and manages container image builds. This includes settings for Redis coordination, executor backends such as Kubernetes or EC2, builder image configuration, and advanced scheduling and retry policies.

These fields must be configured to align with your infrastructure environment and workload requirements.

Table 61. Build manager configuration fields
Field Type Description

ALLOWED_WORKER_COUNT

String

Defines how many Build Workers are instantiated per Project Quay pod. Typically set to 1.

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, Project Quay does not set up the keyspace events required for key events at runtime. To do so, set REDIS_SKIP_KEYSPACE_EVENT_SETUP to False.

EXECUTOR

String

Starts a definition of an Executor of this type. Valid values are kubernetes and ec2.

BUILDER_NAMESPACE

String

Kubernetes namespace where Project 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 Quay container of the Build cluster’s CA certificate for the Quay application to trust when making API calls.

KUBERNETES_DISTRIBUTION

String

Indicates which type of Kubernetes is being used. Valid values are openshift and k8s.

CONTAINER_*

Object

Define the resource requests and limits for each build pod.

NODE_SELECTOR_*

Object

Defines the node selector label name-value pair where build Pods should be scheduled.

CONTAINER_RUNTIME

Object

Specifies whether the Builder should run docker or podman. Customers using Red Hat’s quay-builder image should set this to podman.

SERVICE_ACCOUNT_NAME/SERVICE_ACCOUNT_TOKEN

Object

Defines the Service Account name or token that will be used by build pods.

QUAY_USERNAME/QUAY_PASSWORD

Object

Defines the registry credentials needed to pull the Project Quay build worker image that is specified in the WORKER_IMAGE field.

WORKER_IMAGE

Object

Image reference for the Project Quay Builder image.

WORKER_TAG

Object

Tag for the Builder image desired. The latest version is {producty}.

BUILDER_VM_CONTAINER_IMAGE

Object

The full reference to the container image holding the internal VM needed to run each Project 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 500 seconds. Builds that time out are attempted to be restarted three times. If the Build does not register itself after three attempts it is considered failed.

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 0 means there are no restrictions on how many tries the build job needs to have. This value should be kept intentionally small (three or less) to ensure failovers happen quickly during infrastructure failures. You must specify a value for this setting. For example, Kubernetes is set as the first executor and EC2 as the second executor. If you want the last attempt to run a job to always be executed on EC2 and not Kubernetes, you can set the Kubernetes executor’s MINIMUM_RETRY_THRESHOLD to 1 and EC2’s MINIMUM_RETRY_THRESHOLD to 0 (defaults to 0 if not set). In this case, the Kubernetes' MINIMUM_RETRY_THRESHOLD retries_remaining(1) would evaluate to False, therefore falling back to the second executor configured.

SSH_AUTHORIZED_KEYS

Object

List of SSH keys to bootstrap in the ignition config. This allows other keys to be used to SSH into the EC2 instance or QEMU virtual machine (VM).
Build manager configuration fields
# ...
ALLOWED_WORKER_COUNT: "1"
ORCHESTRATOR_PREFIX: "quaybuild:"
REDIS_HOST: redis.example.com
REDIS_PASSWORD: examplepassword
REDIS_SSL: true
REDIS_SKIP_KEYSPACE_EVENT_SETUP: false
EXECUTOR: kubernetes
BUILDER_NAMESPACE: quay-builder
K8S_API_SERVER: https://api.openshift.example.com:6443
K8S_API_TLS_CA: /etc/ssl/certs/ca.crt
KUBERNETES_DISTRIBUTION: openshift
CONTAINER_RUNTIME: podman
CONTAINER_MEMORY_LIMITS: 2Gi
NODE_SELECTOR_ROLE: quay-build-node
SERVICE_ACCOUNT_NAME: quay-builder-sa
QUAY_USERNAME: quayuser
QUAY_PASSWORD: quaypassword
WORKER_IMAGE: quay.io/quay/quay-builder
WORKER_TAG: latest
BUILDER_VM_CONTAINER_IMAGE: quay.io/quay/vm-builder:latest
SETUP_TIME: "500"
MINIMUM_RETRY_THRESHOLD: "1"
SSH_AUTHORIZED_KEYS:
  - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAsomekey user@example.com
  - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAnotherkey user2@example.com
# ...

Build logs configuration fields

The following configuration fields are used for managing build logs in Project Quay. These settings determine where build logs are archived, who can access them, and how they are stored.

Table 62. Build logs configuration fields
Field Type Description

FEATURE_READER_BUILD_LOGS

Boolean

If set to true, build logs can be read by those with read access to the repository, rather than only write access or admin access.

Default: False

LOG_ARCHIVE_LOCATION

String

The storage location, defined in DISTRIBUTED_STORAGE_CONFIG, in which to place the archived build logs. Example: s3_us_east

LOG_ARCHIVE_PATH

String

The path under the configured storage engine in which to place the archived build logs in .JSON format. Example: archives/buildlogs
Build logs example YAML
# ...
FEATURE_READER_BUILD_LOGS: true
LOG_ARCHIVE_LOCATION: s3_us_east
LOG_ARCHIVE_PATH: archives/buildlogs
# ...

Configure Clair database and custom Clair configuration

Configure unmanaged or Operator-managed Clair databases and supply custom clair-config.yaml settings for external databases, SSL/TLS certificates, and managed Clair deployments.

Unmanaged Clair configuration

Unmanaged Clair configuration lets you run a custom Clair deployment or use an external Clair database with the Project Quay Operator. You can use this option for geo-replicated environments or highly available databases outside your cluster.

Running a custom Clair configuration with an unmanaged Clair database

To use an external Clair database with the Project Quay Operator, you can set the clairpostgres component to unmanaged in your QuayRegistry custom resource.

Important

You must not use the same externally managed PostgreSQL database for both Project Quay and Clair deployments. Your PostgreSQL database must also not be shared with other workloads, as it might exhaust the natural connection limit on the PostgreSQL side when connection-intensive workloads, like Project Quay or Clair, contend for resources. Additionally, pgBouncer is not supported with Project Quay or Clair, so pgBouncer is not an option to resolve this issue.
Procedure

  • In the Quay Operator, set the clairpostgres component of the QuayRegistry custom resource to managed: false:

    apiVersion: quay.redhat.com/v1
kind: QuayRegistry
metadata:
  name: quay370
spec:
  configBundleSecret: config-bundle-secret
  components:
    - kind: objectstorage
      managed: false
    - kind: route
      managed: true
    - kind: tls
      managed: false
    - kind: clairpostgres
      managed: false

Configuring a custom Clair database with an unmanaged Clair database

To configure a custom Clair database with SSL/TLS certificates on Project Quay, you can create a Quay configuration bundle secret that includes the clair-config.yaml file.

Note

The following procedure configures Clair with SSL/TLS certificates.
Procedure

  1. Create a Quay configuration bundle secret that includes the clair-config.yaml by entering the following command:

    $ oc create secret generic --from-file config.yaml=./config.yaml --from-file extra_ca_cert_rds-ca-2019-root.pem=./rds-ca-2019-root.pem --from-file clair-config.yaml=./clair-config.yaml --from-file ssl.cert=./ssl.cert --from-file ssl.key=./ssl.key config-bundle-secret
    Example Clair config.yaml file
    indexer:
    connstring: host=quay-server.example.com port=5432 dbname=quay user=quayrdsdb password=quayrdsdb sslrootcert=/run/certs/rds-ca-2019-root.pem sslmode=verify-ca
    layer_scan_concurrency: 6
    migrations: true
    scanlock_retry: 11
log_level: debug
matcher:
    connstring: host=quay-server.example.com port=5432 dbname=quay user=quayrdsdb password=quayrdsdb sslrootcert=/run/certs/rds-ca-2019-root.pem sslmode=verify-ca
    migrations: true
metrics:
    name: prometheus
notifier:
    connstring: host=quay-server.example.com port=5432 dbname=quay user=quayrdsdb password=quayrdsdb sslrootcert=/run/certs/rds-ca-2019-root.pem sslmode=verify-ca
    migrations: true
    Note

    • The database certificate is mounted under /run/certs/rds-ca-2019-root.pem on the Clair application pod in the clair-config.yaml. It must be specified when configuring your clair-config.yaml.

  2. Add the clair-config.yaml file to your bundle secret, for example:

    apiVersion: v1
kind: Secret
metadata:
  name: config-bundle-secret
  namespace: quay-enterprise
data:
  config.yaml: <base64 encoded Quay config>
  clair-config.yaml: <base64 encoded Clair config>
  extra_ca_cert_<name>: <base64 encoded ca cert>
  ssl.crt: <base64 encoded SSL certificate>
  ssl.key: <base64 encoded SSL private key>
    Note

    When updated, the provided clair-config.yaml file is mounted into the Clair pod. Any fields not provided are automatically populated with defaults using the Clair configuration module.

  3. You can check the status of your Clair pod by clicking the commit in the Build History page, or by running oc get pods -n <namespace>. For example:

    $ oc get pods -n <namespace>
    Example output
    NAME                                               READY   STATUS    RESTARTS   AGE
f192fe4a-c802-4275-bcce-d2031e635126-9l2b5-25lg2   1/1     Running   0          7s

Running a custom Clair configuration with a managed Clair database

You can customize Clair settings while the Project Quay Operator manages the Clair database. Use this approach to disable updater resources or configure Clair for disconnected environments.

Note

  • If you are running Project Quay in a disconnected environment, the airgap parameter of your clair-config.yaml must be set to True.

  • If you are running Project Quay in a disconnected environment, you should disable all updater components.

Setting a Clair database to managed

To have the Project Quay Operator manage your Clair database, you can set the clairpostgres component to managed in your QuayRegistry custom resource.

Procedure

  • In the Quay Operator, set the clairpostgres component of the QuayRegistry custom resource to managed: true:

    apiVersion: quay.redhat.com/v1
kind: QuayRegistry
metadata:
  name: quay370
spec:
  configBundleSecret: config-bundle-secret
  components:
    - kind: objectstorage
      managed: false
    - kind: route
      managed: true
    - kind: tls
      managed: false
    - kind: clairpostgres
      managed: true

Configuring a custom Clair database with a managed Clair configuration

To supply a custom clair-config.yaml while the Operator manages Clair on Project Quay, you can create a Quay configuration bundle secret that includes your Clair configuration file.

Procedure

  1. Create a Quay configuration bundle secret that includes the clair-config.yaml by entering the following command:

    $ oc create secret generic --from-file config.yaml=./config.yaml --from-file extra_ca_cert_rds-ca-2019-root.pem=./rds-ca-2019-root.pem --from-file clair-config.yaml=./clair-config.yaml config-bundle-secret
    Example Clair config.yaml file
    indexer:
    connstring: host=quay-server.example.com port=5432 dbname=quay user=quayrdsdb password=quayrdsdb sslmode=disable
    layer_scan_concurrency: 6
    migrations: true
    scanlock_retry: 11
log_level: debug
matcher:
    connstring: host=quay-server.example.com port=5432 dbname=quay user=quayrdsdb password=quayrdsdb sslmode=disable
    migrations: true
metrics:
    name: prometheus
notifier:
    connstring: host=quay-server.example.com port=5432 dbname=quay user=quayrdsdb password=quayrdsdb sslmode=disable
    migrations: true
    Note

    The database certificate is mounted under /run/certs/rds-ca-2019-root.pem on the Clair application pod in the clair-config.yaml. It must be specified when configuring your clair-config.yaml.

  2. Add the clair-config.yaml file to your bundle secret, for example:

    apiVersion: v1
kind: Secret
metadata:
  name: config-bundle-secret
  namespace: quay-enterprise
data:
  config.yaml: <base64 encoded Quay config>
  clair-config.yaml: <base64 encoded Clair config>
    Note

    When updated, the provided clair-config.yaml file is mounted into the Clair pod. Any fields not provided are automatically populated with defaults using the Clair configuration module.

  3. You can check the status of your Clair pod by clicking the commit in the Build History page, or by running oc get pods -n <namespace>. For example:

    $ oc get pods -n <namespace>
    Example output
    NAME                                               READY   STATUS    RESTARTS   AGE
f192fe4a-c802-4275-bcce-d2031e635126-9l2b5-25lg2   1/1     Running   0          7s

Configure Clair updaters and disconnected scanning

Configure Clair updater sets and advanced per-updater settings, disable automatic updaters for disconnected deployments, and set up offline vulnerability data transfer and CPE mapping.

Clair updaters

Clair uses Go packages called updaters to fetch and parse vulnerability databases. You can control which databases Clair imports and how often vulnerability data is updated in Project Quay.

Updaters are usually paired with a matcher to interpret if, and how, any vulnerability is related to a package. Administrators might want to update the vulnerability database less frequently, or not import vulnerabilities from databases that they know are not used.

Selecting updater sets for full Red Hat Enterprise Linux (RHEL) coverage

You can select Clair updater sets to cover vulnerabilities in Red Hat Enterprise Linux (RHEL). Use the rhel, rhcc, clair.cvss, and osv updater sets for full coverage.

For full coverage of vulnerabilities in Red Hat Enterprise Linux (RHEL), you must use the following updater sets:

  • rhel. This updater ensures that you have the latest information on the vulnerabilities that affect RHEL.

  • rhcc. This updater keeps track of vulnerabilities related to Red Hat’s container images.

  • clair.cvss. This updater offers a comprehensive view of the severity and risk assessment of vulnerabilities by providing Common Vulnerabilities and Exposures (CVE) scores.

  • osv. This updater focuses on tracking vulnerabilities in open-source software components. This updater is recommended due to how common the use of Java and Go are in RHEL products.

RHEL updaters example
#...
updaters:
  sets:
    - rhel
    - rhcc
    - clair.cvss
    - osv
#...
Advanced updater configuration

In some cases, users might want to configure updaters for specific behavior, for example, if you want to allowlist specific ecosystems for the Open Source Vulnerabilities (OSV) updaters.

Advanced updater configuration might be useful for proxy deployments or air-gapped deployments. Configuration for specific updaters in these scenarios can be passed by putting a key underneath the config environment variable of the updaters object. Users should examine their Clair logs to double-check names.

The following YAML snippets detail the various settings available to some Clair updaters.

Important

For most users, advanced updater configuration is unnecessary.
Configuring the alpine updater
#...
updaters:
  sets:
    - alpine
  config:
    alpine:
      url: https://secdb.alpinelinux.org/
#...
Configuring the debian updater
#...
updaters:
  sets:
    - debian
  config:
    debian:
      mirror_url: https://deb.debian.org/
      json_url: https://security-tracker.debian.org/tracker/data/json
#...
Configuring the clair.cvss updater
#...
updaters:
  config:
    clair.cvss:
      url: https://nvd.nist.gov/feeds/json/cve/1.1/
#...
Configuring the oracle updater
#...
updaters:
  sets:
    - oracle
  config:
    oracle-2023-updater:
      url:
        - https://linux.oracle.com/security/oval/com.oracle.elsa-2023.xml.bz2
    oracle-2022-updater:
      url:
        - https://linux.oracle.com/security/oval/com.oracle.elsa-2022.xml.bz2
#...
Configuring the photon updater
#...
updaters:
  sets:
    - photon
  config:
    photon:
      url: https://packages.vmware.com/photon/photon_oval_definitions/
#...
Configuring the rhel updater
#...
updaters:
  sets:
    - rhel
  config:
    rhel:
      url: https://access.redhat.com/security/data/oval/v2/PULP_MANIFEST
      ignore_unpatched: true
#...

ignore_unpatched is a Boolean that indicates whether to include information about vulnerabilities that do not have corresponding patches or updates available.

Configuring the rhcc updater
#...
updaters:
  sets:
    - rhcc
  config:
    rhcc:
      url: https://access.redhat.com/security/data/metrics/cvemap.xml
#...
Configuring the suse updater
#...
updaters:
  sets:
    - suse
  config:
    suse:
      url: https://support.novell.com/security/oval/
#...
Configuring the ubuntu updater
#...
updaters:
  config:
    ubuntu:
      url: https://api.launchpad.net/1.0/
      name: ubuntu
      force:
        - name: focal
          version: 20.04
#...

where:

updaters.config.ubuntu.force

Specifies the inclusion of specific distribution and version details in the resulting UpdaterSet, regardless of their status in the API response. Useful when you want to ensure that particular distributions and versions are consistently included in your updater configuration.

updaters.config.ubuntu.force.name

Specifies the distribution name that you want to force to be included in the UpdaterSet.

updaters.config.ubuntu.force.version

Specifies the version of the distribution you want to force into the UpdaterSet.

Configuring the osv updater
#...
updaters:
  sets:
    - osv
  config:
    osv:
      url: https://osv-vulnerabilities.storage.googleapis.com/
      allowlist:
        - npm
        - pypi
#...

allowlist is the list of ecosystems to allow. When left unset, all ecosystems are allowed. Must be lowercase.

Disabling the Clair Updater component

You can disable the Clair updater component when you run Project Quay in a disconnected environment. Set matcher.disable_updaters to true in the Clair configuration.

In the following example, Clair updaters are disabled:

#...
matcher:
  disable_updaters: true
#...

Configuring updaters

You can configure Clair updaters by using the updaters.sets key in clair-config.yaml. Use the following examples to select one or more updater sets for your Project Quay deployment.

Important

  • If the sets field is not populated, it defaults to using all sets. In using all sets, Clair tries to reach the URL or URLs of each updater. If you are using a proxy environment, you must add these URLs to your proxy allowlist.

  • If updaters are being run automatically within the matcher process, which is the default setting, the period for running updaters is configured under the matcher’s configuration field.
Configuring Clair for multiple updaters

.Multiple specific updaters

#...
updaters:
  sets:
    - alpine
    - aws
    - osv
#...
Configuring Clair for Alpine

.Alpine config.yaml example

#...
updaters:
  sets:
    - alpine
#...
Configuring Clair for AWS

.AWS config.yaml example

#...
updaters:
  sets:
    - aws
#...
Configuring Clair for Debian

.Debian config.yaml example

#...
updaters:
  sets:
    - debian
#...
Configuring Clair for Clair CVSS

.Clair CVSS config.yaml example

#...
updaters:
  sets:
    - clair.cvss
#...
Configuring Clair for Oracle

.Oracle config.yaml example

#...
updaters:
  sets:
    - oracle
#...
Configuring Clair for Photon

.Photon config.yaml example

#...
updaters:
  sets:
    - photon
#...
Configuring Clair for SUSE

.SUSE config.yaml example

#...
updaters:
  sets:
    - suse
#...
Configuring Clair for Ubuntu

.Ubuntu config.yaml example

#...
updaters:
  sets:
    - ubuntu
#...
Configuring Clair for OSV

.OSV config.yaml example

#...
updaters:
  sets:
    - osv
#...

Clair in disconnected environments

Clair supports disconnected Project Quay deployments that have no direct internet access. You can use the clairctl tool to transfer vulnerability database updates from an open host so Clair can scan images offline.

Clair uses a set of components called updaters to handle the fetching and parsing of data from various vulnerability databases. By default, updaters pull vulnerability data directly from the internet and work for immediate use.

Note

Currently, Clair enrichment data is CVSS data. Enrichment data is currently unsupported in disconnected environments.

Setting up Clair in a disconnected OpenShift Container Platform cluster

To install the clairctl command-line utility on a disconnected OpenShift Container Platform cluster, you can copy the binary from a running Clair pod and make it executable.

Procedure

  1. Install the clairctl program for a Clair deployment in an OpenShift Container Platform cluster by entering the following command:

    $ oc -n quay-enterprise exec example-registry-clair-app-64dd48f866-6ptgw -- cat /usr/bin/clairctl > clairctl

  2. Set the permissions of the clairctl file so that it can be executed and run by the user, for example:

    $ chmod u+x ./clairctl

Setting up a self-managed deployment of Clair for a disconnected OpenShift Container Platform cluster

To install the clairctl command-line utility for a self-managed Clair deployment on OpenShift Container Platform, you can copy the binary from a Clair container with Podman and make it executable.

Procedure

  1. Install the clairctl program for a self-managed Clair deployment by using the podman cp command, for example:

    $ sudo podman cp clairv4:/usr/bin/clairctl ./clairctl

  2. Set the permissions of the clairctl file so that it can be executed and run by the user, for example:

    $ chmod u+x ./clairctl

Common Product Enumeration mapping in Clair

Clair uses Common Product Enumeration (CPE) mapping files to map RPM packages to security data for Red Hat Enterprise Linux (RHEL) container images. Accurate vulnerability reports depend on these mapping files being available to the Clair scanner.

The scanner requires the CPE file to be present and accessible to process RPM packages properly. If these files are missing or inaccessible, RPM packages installed in the container image are skipped during the scanning process.

By default, the Clair indexer includes the repos2cpe and names2repos data files within the Clair container. This allows you to reference local paths such as /data/repository-to-cpe.json without additional external configuration.

Important

While Red Hat Product Security updates CPE files regularly, the versions bundled within the Clair container are only updated during Project Quay releases. This can lead to temporary discrepancies between the latest security data and the versions bundled with your current installation.
Additional resources
CPE mapping configuration reference

Common Product Enumeration (CPE) mapping configuration defines the fields and file paths used by Clair to associate packages with standardized product identifiers.

Table 63. Clair CPE mapping files
CPE Type Link to JSON mapping file

repos2cpe

Red Hat Repository-to-CPE JSON

names2repos

Red Hat Name-to-Repos JSON
Example configuration
indexer:
  scanner:
    repo:
      rhel-repository-scanner:
        repo2cpe_mapping_file: /data/repository-to-cpe.json
    package:
      rhel_containerscanner:
        name2repos_mapping_file: /data/container-name-repos-map.json

where:

repo2cpe_mapping_file

Specifies the path to the JSON file mapping Red Hat repositories to CPEs.

name2repos_mapping_file

Specifies the path to the JSON file mapping container names to repositories.

Clair core, indexer, matcher, and updater configuration fields

Reference configuration fields for Clair general settings, indexing, matching, matchers, and updaters.

Clair configuration overview

You can configure Clair with a structured YAML file and run each node in indexer, matcher, or combo mode. Use this overview to understand Clair configuration, proxy requirements, and the configuration reference for Project Quay.

Each Clair node needs to specify what mode it runs in and a path to a configuration file through CLI flags or environment variables. For example:

$ clair -conf ./path/to/config.yaml -mode indexer

or

$ clair -conf ./path/to/config.yaml -mode matcher

The aforementioned commands each start two Clair nodes using the same configuration file. One runs the indexing facilities, while other runs the matching facilities.

If you are running Clair in combo mode, you must supply the indexer, matcher, and notifier configuration blocks in the configuration.

Information about using Clair in a proxy environment

Environment variables respected by the Go standard library can be specified if needed, for example:

  • HTTP_PROXY

    $ export HTTP_PROXY=http://<user_name>:<password>@<proxy_host>:<proxy_port>

  • HTTPS_PROXY.

    $ export HTTPS_PROXY=https://<user_name>:<password>@<proxy_host>:<proxy_port>

  • SSL_CERT_DIR

    $ export SSL_CERT_DIR=/<path>/<to>/<ssl>/<certificates>

  • NO_PROXY

    $ export NO_PROXY=<comma_separated_list_of_hosts_and_domains>

If you are using a proxy server in your environment with Clair’s updater URLs, you must identify which URL needs to be added to the proxy allowlist to ensure that Clair can access them unimpeded. For example, the osv updater requires access to https://osv-vulnerabilities.storage.googleapis.com to fetch ecosystem data dumps. In this scenario, the URL must be added to the proxy allowlist.

You must also ensure that the standard Clair URLs are added to the proxy allowlist:

  • https://search.maven.org/solrsearch/select

  • https://catalog.redhat.com/api/containers/

  • https://access.redhat.com/security/data/metrics/repository-to-cpe.json

  • https://access.redhat.com/security/data/metrics/container-name-repos-map.json

When configuring the proxy server, take into account any authentication requirements or specific proxy settings needed to enable seamless communication between Clair and these URLs. By thoroughly documenting and addressing these considerations, you can ensure that Clair functions effectively while routing its updater traffic through the proxy.

Clair configuration reference

The following YAML shows an example Clair configuration:

http_listen_addr: ""
introspection_addr: ""
log_level: ""
tls: {}
indexer:
    connstring: ""
    scanlock_retry: 0
    layer_scan_concurrency: 5
    migrations: false
    scanner: {}
    airgap: false
matcher:
    connstring: ""
    indexer_addr: ""
    migrations: false
    period: ""
    disable_updaters: false
    update_retention: 2
matchers:
    names: nil
    config: nil
updaters:
    sets: nil
    config: nil
notifier:
    connstring: ""
    migrations: false
    indexer_addr: ""
    matcher_addr: ""
    poll_interval: ""
    delivery_interval: ""
    disable_summary: false
    webhook: null
    amqp: null
    stomp: null
auth:
  psk: nil
trace:
    name: ""
    probability: null
    jaeger:
        agent:
            endpoint: ""
        collector:
            endpoint: ""
            username: null
            password: null
        service_name: ""
        tags: nil
        buffer_max: 0
metrics:
    name: ""
    prometheus:
        endpoint: null
    dogstatsd:
        url: ""
Note

The above YAML file lists every key for completeness. Using this configuration file as-is results in some options not having their defaults set normally.

Clair general fields

You can use the general Clair configuration fields to set the HTTP API listen address, introspection endpoints, log level, and TLS options for Clair in Project Quay.

Field Type Description

http_listen_addr

String

Configures where the HTTP API is exposed.

Default: :6060

introspection_addr

String

Configures where Clair’s metrics and health endpoints are exposed.

log_level

String

Sets the logging level. Requires one of the following strings: debug-color, debug, info, warn, error, fatal, panic

tls

String

A map containing the configuration for serving the HTTP API of TLS/SSL and HTTP/2.

.cert

String

The TLS certificate to be used. Must be a full-chain certificate.
Example configuration for general Clair fields

The following example shows a Clair configuration.

Example configuration for general Clair fields
# ...
http_listen_addr: 0.0.0.0:6060
introspection_addr: 0.0.0.0:8089
log_level: info
# ...

Clair indexer configuration fields

You can use the Clair indexer configuration fields to control database connections, scan concurrency, air-gap mode, and scanner options in Project Quay.

Field Type Description

indexer

Object

Provides Clair indexer node configuration.

.airgap

Boolean

Disables HTTP access to the internet for indexers and fetchers. Private IPv4 and IPv6 addresses are allowed. Database connections are unaffected.

.connstring

String

A Postgres connection string. Accepts format as a URL or libpq connection string.

.index_report_request_concurrency

Integer

Rate limits the number of index report creation requests. Setting this to 0 attemps to auto-size this value. Setting a negative value means unlimited. The auto-sizing is a multiple of the number of available cores.

The API returns a 429 status code if concurrency is exceeded.

.scanlock_retry

Integer

A positive integer representing seconds. Concurrent indexers lock on manifest scans to avoid clobbering. This value tunes how often a waiting indexer polls for the lock.

.layer_scan_concurrency

Integer

Positive integer limiting the number of concurrent layer scans. Indexers will match a manifest’s layer concurrently. This value tunes the number of layers an indexer scans in parallel.

.migrations

Boolean

Whether indexer nodes handle migrations to their database.

.scanner

String

Indexer configuration.

Scanner allows for passing configuration options to layer scanners. The scanner will have this configuration pass to it on construction if designed to do so.

.scanner.dist

String

A map with the name of a particular scanner and arbitrary YAML as a value.

.scanner.package

String

A map with the name of a particular scanner and arbitrary YAML as a value.

.scanner.repo

String

A map with the name of a particular scanner and arbitrary YAML as a value.
Example indexer configuration

The following example shows a hypothetical indexer configuration for Clair.

Example indexer configuration
# ...
indexer:
  connstring: host=quay-server.example.com port=5433 dbname=clair user=clairuser password=clairpass sslmode=disable
  scanlock_retry: 10
  layer_scan_concurrency: 5
  migrations: true
# ...

Clair matcher configuration fields

You can use the Clair matcher configuration fields to control database connections, update periods, and indexer addresses for Clair in Project Quay.

Note

Differs from matchers configuration fields.
Field Type Description

matcher

Object

Provides Clair matcher node configuration.

.cache_age

String

Controls how long users should be hinted to cache responses for.

.connstring

String

A Postgres connection string. Accepts format as a URL or libpq connection string.

.max_conn_pool

Integer

Limits the database connection pool size.

Clair allows for a custom connection pool size. This number directly sets how many active database connections are allowed concurrently.

This parameter will be ignored in a future version. Users should configure this through the connection string.

.indexer_addr

String

A matcher contacts an indexer to create a vulnerability report. The location of this indexer is required.

Defaults to 30m.

.migrations

Boolean

Whether matcher nodes handle migrations to their databases.

.period

String

Determines how often updates for new security advisories take place.

Defaults to 6h.

.disable_updaters

Boolean

Whether to run background updates or not.

Default: False

.update_retention

Integer

Sets the number of update operations to retain between garbage collection cycles. This should be set to a safe MAX value based on database size constraints.

Defaults to 10m.

If a value of less than 0 is provided, garbage collection is disabled. 2 is the minimum value to ensure updates can be compared to notifications.
Example matcher configuration
Example matcher configuration
# ...
matcher:
  connstring: >-
    host=<DB_HOST> port=5432 dbname=<matcher> user=<DB_USER> password=D<B_PASS>
    sslmode=verify-ca sslcert=/etc/clair/ssl/cert.pem sslkey=/etc/clair/ssl/key.pem
    sslrootcert=/etc/clair/ssl/ca.pem
  indexer_addr: http://clair-v4/
  disable_updaters: false
  migrations: true
  period: 6h
  update_retention: 2
# ...

Clair matchers configuration fields

You can use the Clair matchers configuration fields to enable specific in-tree matchers and pass matcher-specific options in Project Quay.

Note

Differs from matcher configuration fields.
Table 64. Matchers configuration fields
Field Type Description

matchers

Array of strings

Provides configuration for the in-tree matchers.

.names

String

A list of string values informing the matcher factory about enabled matchers. If value is set to null, the default list of matchers run. The following strings are accepted: alpine-matcher, aws-matcher, debian-matcher, gobin, java-maven, oracle, photon, python, rhel, rhel-container-matcher, ruby, suse, ubuntu-matcher

.config

String

Provides configuration to a specific matcher.

A map keyed by the name of the matcher containing a sub-object which will be provided to the matchers factory constructor. For example:
Example matchers configuration

The following example shows a hypothetical Clair deployment that only requires only the alpine, aws, debian, oracle matchers.

Example matchers configuration
# ...
matchers:
  names:
  - "alpine-matcher"
  - "aws"
  - "debian"
  - "oracle"
# ...

Clair updaters configuration fields

You can use the Clair updaters configuration fields to select which updater sets run and to pass updater-specific options in Project Quay.

Table 65. Updaters configuration fields
Field Type Description

updaters

Object

Provides configuration for the matcher’s update manager.

.sets

String

A list of values informing the update manager which updaters to run.

If value is set to null, the default set of updaters runs the following: alpine, aws, clair.cvss, debian, oracle, photon, osv, rhel, rhcc suse, ubuntu

If left blank, zero updaters run.

.config

String

Provides configuration to specific updater sets.

A map keyed by the name of the updater set containing a sub-object which will be provided to the updater set’s constructor. For a list of the sub-objects for each updater, see "Advanced updater configuration".
Example updaters configuration

In the following configuration, only the rhel set is configured. The ignore_unpatched variable, which is specific to the rhel updater, is also defined.

Example updaters configuration
# ...
updaters:
  sets:
    - rhel
  config:
    rhel:
      ignore_unpatched: false
# ...

Clair notifier, authorization, trace, metrics, and scanner configuration fields

Reference configuration fields for Clair notifiers, authorization, tracing, metrics, and the security scanner.

Clair notifier configuration fields

You can use the Clair notifier configuration fields to set database connections, polling intervals, and webhook, AMQP, or STOMP delivery options in Project Quay.

Field Type Description

notifier

Object

Provides Clair notifier node configuration.

.connstring

String

Postgres connection string. Accepts format as URL, or libpq connection string.

.migrations

Boolean

Whether notifier nodes handle migrations to their database.

.indexer_addr

String

A notifier contacts an indexer to create or obtain manifests affected by vulnerabilities. The location of this indexer is required.

.matcher_addr

String

A notifier contacts a matcher to list update operations and acquire diffs. The location of this matcher is required.

.poll_interval

String

The frequency at which the notifier will query a matcher for update operations.

.delivery_interval

String

The frequency at which the notifier attempts delivery of created, or previously failed, notifications.

.disable_summary

Boolean

Controls whether notifications should be summarized to one per manifest.

Example notifier configuration

The following notifier snippet is for a minimal configuration.

Example notifier configuration
# ...
notifier:
  connstring: >-
    host=DB_HOST port=5432 dbname=notifier user=DB_USER password=DB_PASS
    sslmode=verify-ca sslcert=/etc/clair/ssl/cert.pem sslkey=/etc/clair/ssl/key.pem
    sslrootcert=/etc/clair/ssl/ca.pem
  indexer_addr: http://clair-v4/
  matcher_addr: http://clair-v4/
  delivery_interval: 5s
  migrations: true
  poll_interval: 15s
  webhook:
    target: "http://webhook/"
    callback: "http://clair-notifier/notifier/api/v1/notifications"
    headers: ""
  amqp: null
  stomp: null
# ...

Clair webhook configuration fields

The following webhook fields are available for the Clair notifier environment.

Table 66. Clair webhook fields

.webhook

Object

Configures the notifier for webhook delivery.

.webhook.target

String

URL where the webhook will be delivered.

.webhook.callback

String

The callback URL where notifications can be retrieved. The notification ID will be appended to this URL.

This will typically be where the Clair notifier is hosted.

.webhook.headers

String

A map associating a header name to a list of values.

Example webhook configuration

Example webhook configuration
# ...
notifier:
# ...
  webhook:
    target: "http://webhook/"
    callback: "http://clair-notifier/notifier/api/v1/notifications"
# ...

Clair amqp configuration fields

The following Advanced Message Queuing Protocol (AMQP) fields are available for the Clair notifier environment.

.amqp

Object

Configures the notifier for AMQP delivery.

[NOTE] ==== Clair does not declare any AMQP components on its own. All attempts to use an exchange or queue are passive only and will fail. Broker administrators should setup exchanges and queues ahead of time. ====

.amqp.direct

Boolean

If True, the notifier will deliver individual notifications (not a callback) to the configured AMQP broker.

.amqp.rollup

Integer

When amqp.direct is set to True, this value informs the notifier of how many notifications to send in a direct delivery. For example, if direct is set to True, and amqp.rollup is set to 5, the notifier delivers no more than 5 notifications in a single JSON payload to the broker. Setting the value to 0 effectively sets it to 1.

.amqp.exchange

Object

The AMQP exchange to connect to.

.amqp.exchange.name

String

The name of the exchange to connect to.

.amqp.exchange.type

String

The type of the exchange. Typically one of the following: direct, fanout, topic, headers.

.amqp.exchange.durability

Boolean

Whether the configured queue is durable.

.amqp.exchange.auto_delete

Boolean

Whether the configured queue uses an auto_delete_policy.

.amqp.routing_key

String

The name of the routing key each notification is sent with.

.amqp.callback

String

If amqp.direct is set to False, this URL is provided in the notification callback sent to the broker. This URL should point to Clair’s notification API endpoint.

.amqp.uris

String

A list of one or more AMQP brokers to connect to, in priority order.

.amqp.tls

Object

Configures TLS/SSL connection to an AMQP broker.

.amqp.tls.root_ca

String

The filesystem path where a root CA can be read.

.amqp.tls.cert

String

The filesystem path where a TLS/SSL certificate can be read.

[NOTE] ==== Clair also allows SSL_CERT_DIR, as documented for the Go crypto/x509 package. ====

.amqp.tls.key

String

The filesystem path where a TLS/SSL private key can be read.

Example AMQP configuration

The following example shows a hypothetical AMQP configuration for Clair.

Example AMQP configuration
# ...
notifier:
# ...
  amqp:
    exchange:
        name: ""
        type: "direct"
        durable: true
        auto_delete: false
    uris: ["amqp://user:pass@host:10000/vhost"]
    direct: false
    routing_key: "notifications"
    callback: "http://clair-notifier/notifier/api/v1/notifications"
    tls:
     root_ca: "optional/path/to/rootca"
     cert: "madatory/path/to/cert"
     key: "madatory/path/to/key"
# ...

Clair STOMP configuration fields

The following Simple Text Oriented Message Protocol (STOMP) fields are available for the Clair notifier environment.

.stomp Object Configures the notifier for STOMP delivery.

.stomp.direct

Boolean

If True, the notifier delivers individual notifications (not a callback) to the configured STOMP broker.

.stomp.rollup

Integer

If stomp.direct is set to True, this value limits the number of notifications sent in a single direct delivery. For example, if direct is set to True, and rollup is set to 5, the notifier delivers no more than 5 notifications in a single JSON payload to the broker. Setting the value to 0 effectively sets it to 1.

.stomp.callback

String

If stomp.callback is set to False, the provided URL in the notification callback is sent to the broker. This URL should point to Clair’s notification API endpoint.

.stomp.destination

String

The STOMP destination to deliver notifications to.

.stomp.uris

String

A list of one or more STOMP brokers to connect to in priority order.

.stomp.tls

Object

Configured TLS/SSL connection to STOMP broker.

.stomp.tls.root_ca

String

The filesystem path where a root CA can be read.

[NOTE] ==== Clair also respects SSL_CERT_DIR, as documented for the Go crypto/x509 package. ====

.stomp.tls.cert

String

The filesystem path where a TLS/SSL certificate can be read.

.stomp.tls.key

String

The filesystem path where a TLS/SSL private key can be read.

.stomp.user

String

Configures login details for the STOMP broker.

.stomp.user.login

String

The STOMP login to connect with.

.stomp.user.passcode

String

The STOMP passcode to connect with.

Example STOMP configuration

The following example shows a hypothetical STOMP configuration for Clair.

Example STOMP configuration
# ...
notifier:
# ...
  stomp:
    desitnation: "notifications"
    direct: false
    callback: "http://clair-notifier/notifier/api/v1/notifications"
    login:
      login: "username"
      passcode: "passcode"
    tls:
     root_ca: "optional/path/to/rootca"
     cert: "madatory/path/to/cert"
     key: "madatory/path/to/key"
# ...

Clair authorization configuration fields

You can use the Clair authorization configuration fields to configure JWT authentication with a pre-shared key for Clair in Project Quay.

Field Type Description

auth

Object

Defines Clair’s external and intra-service JWT based authentication. If multiple auth mechanisms are defined, Clair picks one. Currently, multiple mechanisms are unsupported.

.psk

String

Defines pre-shared key authentication.

.psk.key

String

A shared base64 encoded key distributed between all parties signing and verifying JWTs.

.psk.iss

String

A list of JWT issuers to verify. An empty list accepts any issuer in a JWT claim.
Example authorization configuration

The following authorization snippet is for a minimal configuration.

Example authorization configuration
# ...
auth:
  psk:
    key: MTU5YzA4Y2ZkNzJoMQ==
    iss: ["quay"]
# ...

Clair trace configuration fields

You can use the Clair trace configuration fields to configure OpenTelemetry and Jaeger distributed tracing for Clair in Project Quay.

Field Type Description

trace

Object

Defines distributed tracing configuration based on OpenTelemetry.

.name

String

The name of the application traces will belong to.

.probability

Integer

The probability a trace will occur.

.jaeger

Object

Defines values for Jaeger tracing.

.jaeger.agent

Object

Defines values for configuring delivery to a Jaeger agent.

.jaeger.agent.endpoint

String

An address in the <host>:<post> syntax where traces can be submitted.

.jaeger.collector

Object

Defines values for configuring delivery to a Jaeger collector.

.jaeger.collector.endpoint

String

An address in the <host>:<post> syntax where traces can be submitted.

.jaeger.collector.username

String

A Jaeger username.

.jaeger.collector.password

String

A Jaeger password.

.jaeger.service_name

String

The service name registered in Jaeger.

.jaeger.tags

String

Key-value pairs to provide additional metadata.

.jaeger.buffer_max

Integer

The maximum number of spans that can be buffered in memory before they are sent to the Jaeger backend for storage and analysis.
Example trace configuration

The following example shows a hypothetical trace configuration for Clair.

Example trace configuration
# ...
trace:
  name: "jaeger"
  probability: 1
  jaeger:
    agent:
      endpoint: "localhost:6831"
    service_name: "clair"
# ...

Clair metrics configuration fields

You can use the Clair metrics configuration fields to configure Prometheus metrics export for Clair in Project Quay.

Field Type Description

metrics

Object

Defines distributed tracing configuration based on OpenTelemetry.

.name

String

The name of the metrics in use.

.prometheus

String

Configuration for a Prometheus metrics exporter.

.prometheus.endpoint

String

Defines the path where metrics are served.
Example metrics configuration

The following example shows a hypothetical metrics configuration for Clair.

Example metrics configuration
# ...
metrics:
  name: "prometheus"
  prometheus:
    endpoint: "/metricsz"
# ...

Clair security scanner configuration fields

The following configuration fields control how the Clair security scanner is enabled, how frequently it indexes new content, which endpoints are used, and how notifications are handled.

Table 67. Security scanner configuration
Field Type Description

FEATURE_SECURITY_SCANNER

Boolean

Enable or disable the security scanner Default: False

FEATURE_SECURITY_NOTIFICATIONS

Boolean

If the security scanner is enabled, turn on or turn off security notifications Default: False

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 last_indexed datetime in the manifestsecuritystatus table. This parameter is used to avoid trying to re-index every failed manifest on every indexing run. The default time to re-index is 300 seconds.

SECURITY_SCANNER_V4_ENDPOINT

String

The endpoint for the V4 security scanner Pattern: ^http(s)?://(.)+$ Example: http://192.168.99.101:6060

SECURITY_SCANNER_V4_PSK

String

The generated pre-shared key (PSK) for Clair // TODO 36 Check that SECURITY_SCANNER_NOTIFICATIONS can be dropped //

SECURITY_SCANNER_NOTIFICATIONS

String

SECURITY_SCANNER_ENDPOINT

String

The endpoint for the V2 security scanner Pattern: ^http(s)?://(.)+$ Example: http://192.168.99.100:6060

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, Project 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: True

SECURITY_SCANNER_V4_MANIFEST_CLEANUP

Boolean

Whether the Project Quay garbage collector removes manifests that are not referenced by other tags or manifests.

Default: True

NOTIFICATION_MIN_SEVERITY_ON_NEW_INDEX

String

Set minimal security level for new notifications on detected vulnerabilities. Avoids creation of large number of notifications after first index. If not defined, defaults to High. Available options include Critical, High, Medium, Low, Negligible, and Unknown.

SECURITY_SCANNER_V4_INDEX_MAX_LAYER_SIZE

String

The maximum layer size allowed for indexing. If the layer size exceeds the configured size, the Project Quay UI returns the following message: The manifest for this tag has layer(s) that are too large to index by the Quay Security Scanner. The default is 8G, and the maximum recommended is 10G. Accepted values are B, K, M, T, and G.

Default: 8G
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_MANIFEST_CLEANUP: true
SECURITY_SCANNER_V4_ENDPOINT: http://quay-server.example.com:8081
SECURITY_SCANNER_V4_PSK: MTU5YzA4Y2ZkNzJoMQ==
SERVER_HOSTNAME: quay-server.example.com
SECURITY_SCANNER_V4_INDEX_MAX_LAYER_SIZE: 8G
# ...

Recommended maximum is 10G.

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.

Project 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, Project 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 Project Quay database.