SupportConsoleDevelopersStart a trialContact

Chapter 1. Getting started with configuration

Red Hat Quay can be deployed in a standalone manner, or on an existing OpenShift cluster using the Operator. The methods you use to create, retrieve, update and validate the Red Hat Quay configuration vary slightly, depending on the type of deployment you are using. However, the core configuration options are fundamentally the same for all types of deployment, and these options can be manipulated:

You can install Quay on OpenShift using the Operator, without the need to supply any initial configuration, as the Operator will supply sensible defaults to deploy the registry. For a standalone deployment, however, you must supply a minimal level of configuration before the registry can be started. The minimal requirements can be determined using the configuration API and are documented in the section

Once you have Quay deployed with your initial configuration, you should retrieve and save the full configuration from the running system as it may contain extra, generated values that you will need in future when restarting or upgrading your system.

1.1. Configuration updates for Quay 3.6

1.1.1. New configuration fields

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

1.1.2. Deprecated configuration fields

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

1.2. Editing the configuration file

Deploying the registry in standalone mode requires a minimal configuration - see section Section 1.5, “Minimal configuration”.

The configuration file is validated on startup of the registry, and any issue will be highlighted in the output:

It is possible to use the configuration API to validate the configuration, but this requires starting the Quay container in config mode

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

1.3. Location of configuration file in a standalone deployment

For a standalone deployment, the config.yaml file must be specified when starting the Quay registry. This file is located in the config volume, so in the following example, the config file is located at $QUAY/config/config.yaml: 

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

1.4. Configuring Quay on OpenShift using the command line and API

Once deployed, you can configure the Quay application by editing the Quay configuration bundle secret spec.configBundleSecret and you can also change the managed status of components in the spec.components object of the QuayRegistry resource

The Operator does not watch the spec.configBundleSecret resource for changes, so it is recommended that configuration changes be made to a new Secret resource and that the spec.configBundleSecret field is updated to reflect the change. In the event there are issues with the new configuration, it is simple to revert the value of spec.configBundleSecret to the older Secret.

The procedure for changing the configuration involves:

  1. Determining the current endpoints and secrets
  2. Downloading the existing configuration bundle, if Red Hat Quay has already been deployed on OpenShift
  3. Creating or updating the config.yaml configuration file
  4. Assembling any SSL certs required for Quay, or custom SSL certs needed for services
  5. Creating a new config bundle secret, using the config file and any certs
  6. Creating or updating the registry, referencing the new config bundle secret and specifying any over-rides for managing components
  7. Monitoring the deployment to ensure successful completion and that the configuration changes have taken effect

Alternatively, you can use the config editor UI to configure the Quay application, as described in the section Chapter 4, Using the config tool to reconfigure Quay on OpenShift.

1.4.1. Determining QuayRegistry endpoints and secrets

You can examine the QuayRegistry resource, using oc describe quayregistry or oc get quayregistry -o yaml, to determine the current endpoints and secrets: 

$ oc get quayregistry example-registry -n quay-enterprise -o yaml

apiVersion: quay.redhat.com/v1
kind: QuayRegistry
metadata:
  ...
  name: example-registry
  namespace: quay-enterprise
  ...
spec:
  components:
  ...
  configBundleSecret: example-registry-quay-config-bundle-fjpnm
status:
  configEditorCredentialsSecret: example-registry-quay-config-editor-credentials-kk55dc7299
  configEditorEndpoint: https://example-registry-quay-config-editor-quay-enterprise.apps.docs.quayteam.org
  currentVersion: 3.6.0
  lastUpdated: 2021-09-21 11:18:13.285192787 +0000 UTC
  registryEndpoint: https://example-registry-quay-quay-enterprise.apps.docs.quayteam.org
  unhealthyComponents: {}

The relevant fields are:

  • registryEndpoint: The URL for your registry, for browser access to the registry UI, and for the registry API endpoint
  • configBundleSecret: The config bundle secret, containing the config.yaml file and any SSL certs
  • configEditorEndpoint: The URL for the config editor tool, for browser access to the config tool, and for the configuration API
  • configEditorCredentialsSecret: The secret containing the username (typically quayconfig) and the password for the config editor tool

To determine the username and password for the config editor tool:

  1. Retrieve the secret: 

    $ oc get secret -n quay-enterprise example-registry-quay-config-editor-credentials-kk55dc7299 -o yaml

apiVersion: v1
data:
  password: SkZwQkVKTUN0a1BUZmp4dA==
  username: cXVheWNvbmZpZw==
kind: Secret

  2. Decode the username: 

    $ echo 'cXVheWNvbmZpZw==' | base64 --decode

quayconfig

  3. Decode the password: 

    $ echo 'SkZwQkVKTUN0a1BUZmp4dA==' | base64 --decode

JFpBEJMCtkPTfjxt

1.4.2. Downloading the existing configuration

There are a number of methods for accessing the current configuration:

  1. Using the config editor endpoint, specifying the username and password for the config editor: 

    $ curl -k -u quayconfig:JFpBEJMCtkPTfjxt https://example-registry-quay-config-editor-quay-enterprise.apps.docs.quayteam.org/api/v1/config
    {
    "config.yaml": {
        "ALLOW_PULLS_WITHOUT_STRICT_LOGGING": false,
        "AUTHENTICATION_TYPE": "Database",
        ...
        "USER_RECOVERY_TOKEN_LIFETIME": "30m"
    },
    "certs": {
        "extra_ca_certs/service-ca.crt": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURVVENDQWptZ0F3SUJBZ0lJRE9kWFhuUXFjMUF3RFFZSktvWklodmNOQVFFTEJRQXdOakUwTURJR0ExVUUKQXd3cmIzQmxibk5vYVdaMExYTmxjblpwWTJVdGMyVnlkbWx1WnkxemFXZHVaWEpBTVRZek1UYzNPREV3TXpBZQpGdzB5TVRBNU1UWXdOelF4TkRKYUZ..."
    }
}

  2. Using the config bundle secret

    1. Get the secret data: 

      $ oc get secret -n quay-enterprise example-registry-quay-config-bundle-jkfhs -o jsonpath='{.data}'
      {
    "config.yaml": "QUxMT1dfUFVMTFNfV0lUSE9VVF9TVFJJQ1RfTE9HR0lORzogZmFsc2UKQVVUSEVOVElDQVRJT05fVFlQRTogRGF0YWJhc2UKQVZBVEFSX0tJTkQ6IGxvY2FsCkRBVEFCQVNFX1NFQ1JFVF9LRVk6IHhlOEc1VDBNbkllaGxNQzNkTjd3MWR5WWxwVmo0a0R2enlxZ3l6Ulp5ZjFpODBmWWU3VDUxU1FPZ3hXelpocFlqYlVxNzRKaDllVVVEVWpyCkRFR
...
OgotIDJ3ClRFQU1fUkVTWU5DX1NUQUxFX1RJTUU6IDYwbQpURVNUSU5HOiBmYWxzZQpVU0VSX1JFQ09WRVJZX1RPS0VOX0xJRkVUSU1FOiAzMG0K",
    "extra_ca_cert_service-ca.crt": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURVVENDQWptZ0F3SUJBZ0lJRE9kWFhuUXFjMUF3RFFZSktvWklodmNOQVFFTEJRQXdOakUwTURJR0ExVUUKQXd3cmIzQmxibk5vYVdaMExYTmxjblpwWTJVdGMyVnlkbWx1WnkxemFXZHVaWEpBTVRZek1UYzNPREV3TXpBZQpGdzB5TVRBNU1UWXdOelF4TkRKYUZ3MHl
...
XSW1jaApkQXZTWGpFUnZOZEZzN3pHK1VzTmZwN0ZIQkJVWkY4L2RZNWJCR2MwWTVaY0J6bFNjQT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K"
}

    2. Decode the data: 

      $ echo 'QUxMT1dfUFVMTFN...U1FOiAzMG0K' | base64 --decode
      ALLOW_PULLS_WITHOUT_STRICT_LOGGING: false
AUTHENTICATION_TYPE: Database
...
TAG_EXPIRATION_OPTIONS:
- 2w
TEAM_RESYNC_STALE_TIME: 60m
TESTING: false
USER_RECOVERY_TOKEN_LIFETIME: 30m

1.4.3. Using the config bundle to configure custom SSL certs

You can configure custom SSL certs either before initial deployment or after Red Hat Quay is deployed on OpenShift, by creating a new config bundle secret. If you are adding the cert(s) to an existing deployment, you must include the complete existing config.yaml in the new config bundle secret, even if you are not making any configuration changes.

  1. Create the secret using embedded data or using files:

    1. Embed the configuration details directly in the Secret resource YAML file, for example:

      custom-ssl-config-bundle.yaml

      apiVersion: v1
kind: Secret
metadata:
  name: custom-ssl-config-bundle-secret
  namespace: quay-enterprise
data:
  config.yaml: |
    ALLOW_PULLS_WITHOUT_STRICT_LOGGING: false
    AUTHENTICATION_TYPE: Database
    ...
  extra_ca_cert_my-custom-ssl.crt: |
    -----BEGIN CERTIFICATE-----
    MIIDsDCCApigAwIBAgIUCqlzkHjF5i5TXLFy+sepFrZr/UswDQYJKoZIhvcNAQEL
    BQAwbzELMAkGA1UEBhMCSUUxDzANBgNVBAgMBkdBTFdBWTEPMA0GA1UEBwwGR0FM
    ....
    -----END CERTIFICATE-----

      Next, create the secret from the YAML file: 

      $ oc create  -f custom-ssl-config-bundle.yaml

    2. Alternatively, you can create files containing the desired information, and then create the secret from those files: 

      $ oc create secret generic custom-ssl-config-bundle-secret \
  --from-file=config.yaml \
  --from-file=extra_ca_cert_my-custom-ssl.crt=my-custom-ssl.crt

  2. Create or update the QuayRegistry YAML file quayregistry.yaml, referencing the created Secret, for example:

    quayregistry.yaml

    apiVersion: quay.redhat.com/v1
kind: QuayRegistry
metadata:
  name: example-registry
  namespace: quay-enterprise
spec:
  configBundleSecret: custom-ssl-config-bundle-secret

  3. Deploy or update the registry using the YAML file: 

    oc apply -f quayregistry.yaml

1.5. Minimal configuration

For a standalone deployment, configuration options are required for the following features:

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

1.5.1. Sample minimal configuration file

A sample minimal config file, using local storage for images, is shown below:

$QUAY/config/config.yaml

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

Note

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

1.5.2. Local storage

Using local storage for images is only recommended when deploying a registry for proof of concept purposes. In this case, storage is specified on the command line when starting the registry, mapping a local directory $QUAY/storage to the /datastorage path in the container: 

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

1.5.3. Cloud storage

Storage configuration is detailed in the section Image storage. It is useful to compare the difference when using cloud storage, for example, on Google Cloud Platform:

$QUAY/config/config.yaml

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

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

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

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.