Chapter 6. Mirroring images with Red Hat Quay

Procedure

1. To enable organization mirroring, set the following configuration fields in your config.yaml file:

   # ...
   FEATURE_PROXY_CACHE: true
   FEATURE_REPO_MIRROR: true
   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
   # ...

   where:

   FEATURE_PROXY_CACHE

   Specifies whether to enable or disable proxy caching. This field must be set to true to use the organization mirroring feature.

   FEATURE_REPO_MIRROR

   Specifies whether to enable or disable repository-level mirroring. This field must be set to true to use the organization mirroring feature.

   FEATURE_ORG_MIRROR

   Specifies whether to enable or disable organization-level mirroring.

   ORG_MIRROR_INTERVAL

   Specifies the worker processing interval in seconds.

   ORG_MIRROR_BATCH_SIZE

   Specifies the number of organization mirrors to process for each iteration.

   ORG_MIRROR_MAX_SYNC_DURATION

   Specifies the maximum sync duration in seconds.

   ORG_MIRROR_DEFAULT_SKOPEO_TIMEOUT

   Specifies the default skopeo timeout in seconds.

   ORG_MIRROR_DISCOVERY_TIMEOUT

   Specifies the discovery timeout in seconds.

   ORG_MIRROR_MAX_REPOS_PER_ORG

   Specifies the maximum repositories to discover for each organization.

   ORG_MIRROR_MAX_RETRIES

   Specifies the maximum sync retries for a failure operation.

   SSRF_ALLOWED_HOSTS

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

2. Restart your Red Hat Quay registry.

Procedure

1. On the Red Hat Quay v2 UI, click Organizations in the navigation pane.
2. Find your organization listed under the Name column and then click the name of the organization.
3. Click Settings Organization state.
4. Click the Mirror radio button to set the organization state to mirroring.
5. Click Submit. Completion of this step takes you to the Mirroring tab.

6. Under the Source Registry section, complete the following settings:

   • For Source Registry Type, select Quay or Harbor.
   • In the Source Registry URL field, enter a valid URL, for example, https://registry.example.com.
   • For Source Namespace, enter the namespace or project name on the source registry. For example, my-project.
   • Select Private or Public for Repository Visibility.
   • For Start Date, set the date in yyyy-mm-dd format and set the time.
   • Set the Sync interval. Set the integer in the box and select seconds, minutes, hours, days, or weeks from the drop-down menu.
   • Set the Skopeo Timeout value for Skopeo operations.
   • Select a Robot User from the drop-down menu.
   • Set any desired Filter Patterns.

7. In the Credentials section, do one of the following actions:

   • If you specified Harbor for Source Registry Type, enter your username and password for the source registry.
   • If you specified Quay for Source Registry Type, enter $oauthtoken for the Username field and your OAuth token for the Password field.

8. Optional: In Advanced Settings, complete any of the following options:

   • For Verify TLS, select the checkbox to verify certificates.
   • Set an HTTP Proxy URL.
   • Set an HTTPS Proxy URL.
   • Set a No Proxy URL.
9. When you have configured the desired settings, click Enable Organization Mirror.

Verification

1. On the Red Hat Quay web console, click Organizations the organization name Mirroring.
2. Scroll to the Status section to view the status and verify the connection.

Procedure

1. Use the POST /api/v1/organization/{orgname}/mirror endpoint to create a new organization-level mirroring configuration:

   $ curl -X POST "https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror" \
     -H "Authorization: Bearer <access_token>" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
       "external_registry_type": "quay",
       "external_registry_url": "https://quay.io",
       "external_namespace": "<external_namespace>",
       "robot_username": "<orgname>+<robot_account>",
       "visibility": "private",
       "sync_interval": 3600,
       "sync_start_date": "2025-01-01T00:00:00Z",
       "is_enabled": true
     }'

2. Use the GET /api/v1/organization/{orgname}/mirror endpoint to retrieve the organization-level mirroring configuration:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror

   Example output

   {"is_enabled": true, "external_registry_type": "quay", "external_registry_url": "http://quay.io", "external_namespace": "test", "external_registry_username": null, "external_registry_config": {}, "repository_filters": [], "robot_username": "example+test", "visibility": "private", "sync_interval": 3600, "sync_start_date": "2025-01-01T00:00:00Z", "sync_expiration_date": null, "sync_status": "NEVER_RUN", "sync_retries_remaining": 3, "skopeo_timeout": 300, "creation_date": "2026-03-09T18:39:21.993431Z"}

3. Use the GET /api/v1/organization/{orgname}/mirror/repositories endpoint to obtain a list of repositories that are being mirrored in the organization:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     "https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror/repositories?page=1&limit=100"

   Example output

   {"repositories": [], "page": 1, "limit": 100, "total": 0, "has_next": false}

4. Use the POST /api/v1/organization/{orgname}/mirror/sync-now endpoint to trigger an immediate sync of all repositories in the organization:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror/sync-now

   This command does not return output in the CLI.

5. Use the POST /api/v1/organization/{orgname}/mirror/sync-cancel endpoint to cancel a pending sync of all repositories in the organization:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror/sync-cancel

   This command does not return output in the CLI.

6. Use the PUT /api/v1/organization/{orgname}/mirror endpoint to update the organization-level mirroring configuration:

   $ curl -X PUT \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"is_enabled": true, "sync_interval": 7200}' \
     https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror

   Example output

   " "

7. Use the POST /api/v1/organization/{orgname}/mirror/verify endpoint to verify the connection to the external registry for the organization-level mirroring configuration:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror/verify

   Example output

   {"success": false, "message": "Unexpected response: 301"}

8. Use the DELETE /api/v1/organization/{orgname}/mirror endpoint to delete the organization-level mirroring configuration:

   $ curl -X DELETE \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror

   This command does not return output in the CLI.

Procedure

1. To enable mirroring for repositories, set FEATURE_REPO_MIRROR: true in your config.yaml file:

   # ...
   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
   # ...

   where:

   FEATURE_REPO_MIRROR

   Specifies whether to enable or disable repository-level mirroring.

   REPO_MIRROR_INTERVAL

   Specifies the worker processing interval in seconds.

   REPO_MIRROR_SERVER_HOSTNAME

   Specifies the hostname of the server hosting the mirrored repository.

   REPO_MIRROR_TLS_VERIFY

   Specifies whether to verify the TLS certificate of the mirrored repository.

   REPO_MIRROR_ROLLBACK

   Specifies whether to roll back the repository if a mirroring operation fails.

   FEATURE_SPARSE_INDEX

   Specifies whether to allow sparse manifest indexes.

   REPO_MIRROR_MAX_MANIFEST_LIST_SIZE

   Specifies the maximum size of the manifest list in bytes.

   REPO_MIRROR_MAX_MANIFEST_ENTRIES

   Specifies the maximum number of manifest entries to process.

2. Restart your Red Hat Quay registry.

Procedure

1. Navigate to the Repositories page of your registry and click the name of a repository, for example, test-mirror.
2. Click Settings Repository state.
3. Click Mirror.
4. Click the Mirroring tab and enter the details for connecting to the external registry, along with the tags, scheduling, and access information.

5. Enter the details as required in the following fields:

   • Registry Location: The external repository you want to mirror, for example, registry.redhat.io/quay/quay-rhel8.
   • Tags: Enter a comma-separated list of individual tags or tag patterns. You can use Unix shell-style wildcards.
   • Architecture Filter: Select the architectures that you want to mirror. For example, select AMD64 (x86_64) to mirror only the x86_64 architecture. By default, all architectures are mirrored.
   • Start Date: The date on which mirroring begins. By default, the current date and time are used.
   • Sync Interval: Defaults to syncing every 24 hours. You can change that based on hours or days.
   • Skopeo timeout interval: Defaults to 300 seconds (5 minutes). The maximum timeout length is 43200 seconds (12 hours).
   • Robot User: Create a new robot account or choose an existing robot account to do the mirroring.
   • Username: The username for accessing the external registry holding the repository you are mirroring.
   • Password: The password associated with the username. Note that the password cannot include characters that require an escape character (\).

6. In the Advanced Settings section, you can optionally configure SSL/TLS and proxy with the following options:

   • Verify TLS: Select this option if you want to require HTTPS and to verify certificates when communicating with the target remote registry.
   • Accept Unsigned Images: Selecting this option allows unsigned images to be mirrored.
   • HTTP Proxy: Identify the HTTP proxy server needed to access the remote site, if a proxy server is needed.
   • HTTPS Proxy: Identify the HTTPS proxy server needed to access the remote site, if a proxy server is needed.
   • No Proxy: List of locations that do not require a proxy.
7. After filling out all information, click Enable Mirror.

Procedure

1. Navigate to the Mirroring tab of your repository or organization.
2. Click Sync Now.

Verification

1. Click the Logs tab to view available logs.
2. When mirroring is complete, the images appear in the Tags tab.