Search
SupportConsoleDevelopersStart a trialContact

Chapter 1. Advanced Red Hat Quay configuration

download PDF

You can configure your Red Hat Quay after initial deployment using one of the following interfaces:

  • The Red Hat Quay Config Tool. With this tool, a web-based interface for configuring the Red Hat Quay cluster is provided when running the Quay container in config mode. This method is recommended for configuring the Red Hat Quay service.
  • Editing the config.yaml. The config.yaml file contains most configuration information for the Red Hat Quay cluster. Editing the config.yaml file directly is possible, but it is only recommended for advanced tuning and performance features that are not available through the Config Tool.
  • Red Hat Quay API. Some Red Hat Quay features can be configured through the API.

This content in this section describes how to use each of the aforementioned interfaces and how to configure your deployment with advanced features.

1.1. Using Red Hat Quay Config Tool to modify Red Hat Quay

The Red Hat Quay Config Tool is made available by running a Quay container in config mode alongside the regular Red Hat Quay service.

Use the following sections to run the Config Tool from the Red Hat Quay Operator, or to run the Config Tool on host systems from the command line interface (CLI).

1.1.1. Running the Config Tool from the Red Hat Quay Operator

When running the Red Hat Quay Operator on OpenShift Container Platform, the Config Tool is readily available to use. Use the following procedure to access the Red Hat Quay Config Tool.

Prerequisites

  1. You have deployed the Red Hat Quay Operator on OpenShift Container Platform.

Procedure.

  1. On the OpenShift console, select the Red Hat Quay project, for example, quay-enterprise.

  2. In the navigation pane, select Networking Routes. You should see routes to both the Red Hat Quay application and Config Tool, as shown in the following image:

    View the route to the Red Hat Quay Config Tool

  3. Select the route to the Config Tool, for example, example-quayecosystem-quay-config. The Config Tool UI should open in your browser.

  4. Select Modify configuration for this cluster to bring up the Config Tool setup, for example:

    Modify Red Hat Quay cluster settings from the Config Tool

  5. Make the desired changes, and then select Save Configuration Changes.
  6. Make any corrections needed by clicking Continue Editing, or, select Next to continue.
  7. When prompted, select Download Configuration. This will download a tarball of your new config.yaml, as well as any certificates and keys used with your Red Hat Quay setup. The config.yaml can be used to make advanced changes to your configuration or use as a future reference.
  8. Select Go to deployment rollout Populate the configuration to deployments. Wait for the Red Hat Quay pods to restart for the changes to take effect.

1.1.2. Running the Config Tool from the command line

If you are running Red Hat Quay from a host system, you can use the following procedure to make changes to your configuration after the initial deployment.

  1. Prerequisites

    • You have installed either podman or docker.
  2. Start Red Hat Quay in configuration mode.

  3. On the first Quay node, enter the following command: 

    $ podman run --rm -it --name quay_config -p 8080:8080 \
    -v path/to/config-bundle:/conf/stack \
    registry.redhat.io/quay/quay-rhel8:v3.8.15 config <my_secret_password>
    Note

    To modify an existing config bundle, you can mount your configuration directory into the Quay container.

  4. When the Red Hat Quay configuration tool starts, open your browser and navigate to the URL and port used in your configuration file, for example, quay-server.example.com:8080.
  5. Enter your username and password.
  6. Modify your Red Hat Quay cluster as desired.

1.1.3. Deploying the config tool using TLS certificates

You can deploy the config tool with secured TLS certificates by passing environment variables to the runtime variable. This ensures that sensitive data like credentials for the database and storage backend are protected.

The public and private keys must contain valid Subject Alternative Names (SANs) for the route that you deploy the config tool on.

The paths can be specified using CONFIG_TOOL_PRIVATE_KEY and CONFIG_TOOL_PUBLIC_KEY.

If you are running your deployment from a container, the CONFIG_TOOL_PRIVATE_KEY and CONFIG_TOOL_PUBLIC_KEY values the locations of the certificates inside of the container. For example: 

$ podman run --rm -it --name quay_config -p 7070:8080 \

-v ${PRIVATE_KEY_PATH}:/tls/localhost.key \
-v ${PUBLIC_KEY_PATH}:/tls/localhost.crt \
-e CONFIG_TOOL_PRIVATE_KEY=/tls/localhost.key \
-e CONFIG_TOOL_PUBLIC_KEY=/tls/localhost.crt \
-e DEBUGLOG=true \
-ti config-app:dev

1.2. Using the API to modify Red Hat Quay

See the Red Hat Quay API Guide for information on how to access Red Hat Quay API.

1.3. Editing the config.yaml file to modify Red Hat Quay

Some advanced configuration features that are not available through the Config Tool can be implemented by editing the config.yaml file directly. Available settings are described in the Schema for Red Hat Quay configuration

The following examples are settings you can change directly in the config.yaml file.

1.3.1. Add name and company to Red Hat Quay sign-in

By setting the following field, users are prompted for their name and company when they first sign in. This is an optional field, but can provide your with extra data about your Red Hat Quay users. 

---
FEATURE_USER_METADATA: true
---

1.3.2. Disable TLS Protocols

You can change the SSL_PROTOCOLS setting to remove SSL protocols that you do not want to support in your Red Hat Quay instance. For example, to remove TLS v1 support from the default SSL_PROTOCOLS:['TLSv1','TLSv1.1','TLSv1.2'], change it to the following: 

---
SSL_PROTOCOLS : ['TLSv1.1','TLSv1.2']
---

1.3.3. Rate limit API calls

Adding the FEATURE_RATE_LIMITS parameter to the config.yaml file causes nginx to limit certain API calls to 30-per-second. If FEATURE_RATE_LIMITS is not set, API calls are limited to 300-per-second, effectively making them unlimited.

Rate limiting is important when you must ensure that the available resources are not overwhelmed with traffic.

Some namespaces might require unlimited access, for example, if they are important to CI/CD and take priority. In that scenario, those namespaces might be placed in a list in the config.yaml file using the NON_RATE_LIMITED_NAMESPACES.

1.3.4. Adjust database connection pooling

Red Hat Quay is composed of many different processes which all run within the same container. Many of these processes interact with the database.

With the DB_CONNECTION_POOLING parameter, each process that interacts with the database will contain a connection pool These per-process connection pools are configured to maintain a maximum of 20 connections. When under heavy load, it is possible to fill the connection pool for every process within a Red Hat Quay container. Under certain deployments and loads, this might require analysis to ensure that Red Hat Quay does not exceed the database’s configured maximum connection count.

Over time, the connection pools will release idle connections. To release all connections immediately, Red Hat Quay must be restarted.

Database connection pooling can be toggled by setting the DB_CONNECTION_POOLING to true or false. For example: 

---
DB_CONNECTION_POOLING: true
---

When DB_CONNECTION_POOLING is enabled, you can change the maximum size of the connection pool with the DB_CONNECTION_ARGS in your config.yaml. For example: 

---
DB_CONNECTION_ARGS:
  max_connections: 10
---

1.3.4.1. Database connection arguments

You can customize your Red Hat Quay database connection settings within the config.yaml file. These are dependent on your deployment’s database driver, for example, psycopg2 for Postgres and pymysql for MySQL. You can also pass in argument used by Peewee’s connection pooling mechanism. For example: 

---
DB_CONNECTION_ARGS:
  max_connections: n  # Max Connection Pool size. (Connection Pooling only)
  timeout: n  # Time to hold on to connections. (Connection Pooling only)
  stale_timeout: n  # Number of seconds to block when the pool is full. (Connection Pooling only)
---

1.3.4.2. Database SSL configuration

Some key-value pairs defined under the DB_CONNECTION_ARGS field are generic, while others are specific to the database. In particular, SSL configuration depends on the database that you are deploying.

1.3.4.2.1. PostgreSQL SSL connection arguments

The following YAML shows a sample PostgreSQL SSL configuration: 

---
DB_CONNECTION_ARGS:
  sslmode: verify-ca
  sslrootcert: /path/to/cacert
---

The sslmode parameter determines whether, or with, what priority a secure SSL TCP/IP connection will be negotiated with the server. There are six modes for the sslmode parameter:

  • disabl:: Only try a non-SSL connection.
  • allow: Try a non-SSL connection first. Upon failure, try an SSL connection.
  • prefer: Default. Try an SSL connection first. Upon failure, try a non-SSL connection.
  • require: Only try an SSL connection. If a root CA file is present, verify the connection in the same way as if verify-ca was specified.
  • verify-ca: Only try an SSL connection, and verify that the server certificate is issued by a trust certificate authority (CA).
  • verify-full: Only try an SSL connection. Verify that the server certificate is issued by a trust CA, and that the requested server host name matches that in the certificate.

For more information about the valid arguments for PostgreSQL, see Database Connection Control Functions.

1.3.4.2.2. MySQL SSL connection arguments

The following YAML shows a sample MySQL SSL configuration: 

---
DB_CONNECTION_ARGS:
  ssl:
    ca: /path/to/cacert
---

For more information about the valid connection arguments for MySQL, see Connecting to the Server Using URI-Like Strings or Key-Value Pairs.

1.3.4.3. HTTP connection counts

You can specify the quantity of simultaneous HTTP connections using environment variables. The environment variables can be specified as a whole, or for a specific component. The default for each is 50 parallel connections per process. See the following YAML for example environment variables; 

---
WORKER_CONNECTION_COUNT_REGISTRY=n
WORKER_CONNECTION_COUNT_WEB=n
WORKER_CONNECTION_COUNT_SECSCAN=n
WORKER_CONNECTION_COUNT=n
---
Note

Specifying a count for a specific component will override any value set in the WORKER_CONNECTION_COUNT configuration field.

1.3.4.4. Dynamic process counts

To estimate the quantity of dynamically sized processes, the following calculation is used by default.

Note

Red Hat Quay queries the available CPU count from the entire machine. Any limits applied using kubernetes or other non-virtualized mechanisms will not affect this behavior. Red Hat Quay makes its calculation based on the total number of processors on the Node. The default values listed are simply targets, but shall not exceed the maximum or be lower than the minimum.

Each of the following process quantities can be overridden using the environment variable specified below:

  • registry - Provides HTTP endpoints to handle registry action

    • minimum: 8
    • maximum: 64
    • default: $CPU_COUNT x 4
    • environment variable: WORKER_COUNT_REGISTRY

  • web - Provides HTTP endpoints for the web-based interface

    • minimum: 2
    • maximum: 32
    • default: $CPU_COUNT x 2
    • environment_variable: WORKER_COUNT_WEB

  • secscan - Interacts with Clair

    • minimum: 2
    • maximum: 4
    • default: $CPU_COUNT x 2
    • environment variable: WORKER_COUNT_SECSCAN

1.3.4.5. Environment variables

Red Hat Quay allows overriding default behavior using environment variables. The following table lists and describes each variable and the values they can expect.

Table 1.1. Worker count environment variables
VariableDescriptionValues

WORKER_COUNT_REGISTRY

Specifies the number of processes to handle registry requests within the Quay container.

Integer between 8 and 64

WORKER_COUNT_WEB

Specifies the number of processes to handle UI/Web requests within the container.

Integer between 2 and 32

WORKER_COUNT_SECSCAN

Specifies the number of processes to handle Security Scanning (for example, Clair) integration within the container.

Integer between 2 and 4

DB_CONNECTION_POOLING

Toggle database connection pooling.

"true" or "false"

1.3.4.6. Turning off connection pooling

Red Hat Quay deployments with a large amount of user activity can regularly hit the 2k maximum database connection limit. In these cases, connection pooling, which is enabled by default for Red Hat Quay, can cause database connection count to rise exponentially and require you to turn off connection pooling.

If turning off connection pooling is not enough to prevent hitting the 2k database connection limit, you need to take additional steps to deal with the problem. If this happens, you might need to increase the maximum database connections to better suit your workload.

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.