Chapter 7. Repository Mirroring in Red Hat Quay
Red Hat Quay repository mirroring lets you mirror images from external container registries (or the local registry) into your local Red Hat Quay cluster. Using repository mirroring you can synchronize images to Red Hat Quay based on repository names and tags.
7.1. Overview of repository mirroring
From your Red Hat Quay cluster with repository mirroring enabled, you can:
- Choose a repository from an external registry to mirror
- Add credentials to access the external registry
- Set intervals at which a repository is synced
- Identify specific container image repository names and tags to sync
- Check the current state of synchronization
With repository mirroring, you mirror a specific subset of content, between two or more distinct registries, to selected datacenters, clusters, or regions. By contrast, Georeplication provides a single, globally distributed Red Hat Quay to serve container images from localized storage. The two approaches to sharing content differ in the following ways:
| Feature / Capability | Georeplication | Repository Mirroring |
| What is the feature designed to do? | A shared, global registry | Distinct, different registries |
| What happens if replication or mirroring hasn’t been completed yet? | The remote copy is used (slower) | No image is served |
| Is access to all storage backends in both regions required? | Yes (all Red Hat Quay nodes) | No (distinct storage) |
| Can users push images from both sites to the same repository? | Yes | No |
| Is all registry content and configuration identical across all regions (shared database) | Yes | No |
| Can users select individual namespaces or repositories to be mirrored? | No,by default | Yes |
| Can users apply filters to synchronization rules? | No | Yes |
Here are a few tips for using Red Hat Quay repository mirroring:
- With repository mirroring, you can mirror an entire repository or selectively limit which images are synced based on a comma-separated list of tags, a range of tags, or other means of identifying tags through regular expressions and globs.
- Once set as a mirrored repository, you cannot manually add other images to that repository.
- Because the mirrored repository is based on the repository and tags you set, it will hold only the content represented by the repo/tag pair. In other words, if you change the tag so that some images in the repository don’t match any more, those images will be deleted.
- Only the designated robot can push images to a mirrored repository, superseding any role-based access control permissions set on the repository.
- With a mirrored repository, a user can pull images (given read permission) from the repository but not push images to the repository.
- Changing setting on your mirrored repository is done from a Mirrors tab on the Repositories page for the mirrored repository you create.
- Images are synced at set intervals, but can also be synced on demand.
7.2. Prerequisites
Before you can use repository mirroring, you must enable repository mirroring from the Red Hat Quay configuration screen and start the repository mirroring worker. Ways of starting up this service are described in the Red Hat Quay deployment guides:
The steps shown in the following section assumes you already have the repository mirroring service running and that you have enabled repository mirroring on your Red Hat Quay cluster.
7.3. Create a mirrored repository
To mirror an external repository from an external container registry, do the following:
- Log into your Red Hat Quay registry.
Create a robot account to pull images for the mirrored repository:
- Select Account Settings from the drop-down in the upper right corner.
- Select the Robot Accounts button in the left column.
- Select Create Robot Account.
- Add the name and description of the robot account and select Create robot account.
- Select Close, since the mirrored repository you are adding does not exist yet.
- Select the ROBOT ACCOUNT NAME from the listing.
- When prompted, add the credentials needed by the robot to access the external registry of the repository you want to mirror, then close the Credentials window.
- Select REPOSITORIES.
- Select Create New Repository and give it a name.
- Fill in a repository name, select Public or Private, and select Create Repository.
- Select the Settings button and change the repository state to MIRROR.
- Open the new repository and select the Mirroring button in the left column.
Fill in the fields to identify the repository you are mirroring in your new repository:
- Registry URL: Location of the container registry you want to mirror from.
- User or Organization: Typically, the account name associated with the content you are mirroring. For example, with the image registry.example.com/jsmith/myimage:latest, jsmith would be entered here.
- Repository Name: The name identifying the name of the set of images. For example, with the image registry.example.com/jsmith/myimage:latest, myimage would be entered here.
- Sync Interval: Defaults to syncing every 24 hours. You can change that based on hours or days.
- Robot User: Select the robot account you created earlier to do the mirroring.
- Username: The username for logging into 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 (\).
- Start Date: The date on which mirroring begins. The current date and time used by default.
- Verify TLS: Check this box if you want to verify the authenticity of the external registry. Uncheck this box if, for example, you set up Red Hat Quay for testing with a self-signed certificate or no certificate.
- HTTP Proxy: Identify the proxy server needed to access the remote site, if one is required.
Tags: This field is required. You may enter a comma-separated list of individual tags or tag patterns. (See Tag Patterns section for details.)
NoteAt least one Tag must be explicitly entered (ie. not a tag pattern) or the tag "latest" must exist in the remote repository. This is required for Quay to get the list of tags in the remote repository to compare to the specified list to mirror.
Here is an example of a completed Repository Mirroring screen:
Select the Enable Mirror button. Here’s the resulting Repository Mirroring page:
You can return to this page later to change any of those settings.
7.4. Working with mirrored repositories
Once you have created a mirrored repository, there are several ways you can work with that repository. Select your mirrored repository from the Repositories page and do any of the following:
- Enable/disable the repository: Select the Mirroring button in the left column, then toggle the Enabled check box to enable or disable the repository temporarily.
Check mirror logs: To make sure the mirrored repository is working properly, you can check the mirror logs. To do that, select the Usage Logs button in the left column. Here’s an example:
- Sync mirror now: To immediately sync the images in your repository, select the Sync Now button.
- Change credentials: To change the username and password, select DELETE from the Credentials line. Then select None and add the username and password needed to log into the external registry when prompted.
- Cancel mirroring: To stop mirroring, which keeps the current images available but stops new ones from being synced, select the CANCEL button.
Set robot permissions: Red Hat Quay robot accounts are named tokens that hold credentials for accessing external repositories. By assigning credentials to a robot, that robot can be used across multiple mirrored repositories that need to access the same external registry.
You can assign an existing robot to a repository by going to Account Settings, then selecting the Robot Accounts icon in the left column. For the robot account, choose the link under the REPOSITORIES column. From the pop-up window, you can:
- Check which repositories are assigned to that robot.
-
Assign read, write or Admin privileges to that robot from the PERMISSION field shown in this figure:
Change robot credentials: Robots can hold credentials such as Kubernetes secrets, Docker login information, and Mesos bundles. To change robot credentials, select the Options gear on the robot’s account line on the Robot Accounts window and choose View Credentials. Add the appropriate credentials for the external repository the robot needs to access.
- Check and change general setting: Select the Settings button (gear icon) from the left column on the mirrored repository page. On the resulting page, you can change settings associated with the mirrored repository. In particular, you can change User and Robot Permissions, to specify exactly which users and robots can read from or write to the repo.
7.5. Tag Patterns
As noted above, at least one Tag must be explicitly entered (ie. not a tag pattern) or the tag "latest" must exist in the report repository. (The tag "latest" will not be synced unless specified in the tag list.). This is required for Quay to get the list of tags in the remote repository to compare to the specified list to mirror.
Pattern syntax
| Pattern | Description |
| * | Matches all characters |
| ? | Matches any single character |
| [seq] | Matches any character in seq |
| [!seq] | Matches any character not in seq |
Example tag patterns
| Example Pattern | Example Matches |
| v3* | v32, v3.1, v3.2, v3.2-4beta, v3.3 |
| v3.* | v3.1, v3.2, v3.2-4beta |
| v3.? | v3.1, v3.2, v3.3 |
| v3.[12] | v3.1, v3.2 |
| v3.[12]* | v3.1, v3.2, v3.2-4beta |
| v3.[!1]* | v3.2, v3.2-4beta, v3.3 |
