Chapter 8. Repository mirroring

• Choose a repository from an external registry to mirror
• Add credentials to access the external registry
• Identify specific container image repository names and tags to sync
• Set intervals at which a repository is synced
• Check the current state of synchronization

• Enable repository mirroring in the Red Hat Quay configuration file
• Run a repository mirroring worker
• Create mirrored repositories

• Speeding up access to the binary blobs for geographically dispersed setups
• Guaranteeing that the image content is the same across regions

• Independent registry deployments in different data centers or regions, where a certain subset of the overall content is supposed to be shared across the data centers and regions
• Automatic synchronization or mirroring of selected (allowlisted) upstream repositories from external registries into a local Red Hat Quay deployment

• With repository mirroring, you can mirror an entire repository or selectively limit which images are synced. Filters can be based on a comma-separated list of tags, a range of tags, or other means of identifying tags through Unix shell-style wildcards. For more information, see the documentation for wildcards.
• When a repository is set as mirrored, 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 repository and tag pair. For example if you change the tag so that some images in the repository no longer match, 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.
• Mirroring can be configured to rollback on failure, or to run on a best-effort basis.
• With a mirrored repository, a user with read permissions can pull images from the repository but cannot push images to the repository.
• Changing settings on your mirrored repository can be performed in the Red Hat Quay user interface, using the Repositories Mirrors tab for the mirrored repository you create.
• Images are synced at set intervals, but can also be synced on demand.

Procedure

• If you have not configured TLS communications using a /root/ca.crt certificate, enter the following command to start a Quay pod with the repomirror option:

  $ sudo podman run -d --name mirroring-worker \
    -v $QUAY/config:/conf/stack:Z \
    registry.redhat.io/quay/quay-rhel8:v3.13.1 repomirror

• If you have configured TLS communications using a /root/ca.crt certificate, enter the following command to start the repository mirroring worker:

  $ sudo podman run -d --name mirroring-worker \
    -v $QUAY/config:/conf/stack:Z \
    -v /root/ca.crt:/etc/pki/ca-trust/source/anchors/ca.crt:Z \
    registry.redhat.io/quay/quay-rhel8:v3.13.1 repomirror

• Repository Mirror Started
• Repository Mirror Success
• Repository Mirror Unsuccessful

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

• Repository mirroring pods can run on any node. This means that you can run mirroring on nodes where Red Hat Quay is already running.
• Repository mirroring is scheduled in the database and runs in batches. As a result, repository workers check each repository mirror configuration file and reads when the next sync needs to be. More mirror workers means more repositories can be mirrored at the same time. For example, running 10 mirror workers means that a user can run 10 mirroring operators in parallel. If a user only has 2 workers with 10 mirror configurations, only 2 operators can be performed.

• The optimal number of mirroring pods depends on the following conditions:

  • The total number of repositories to be mirrored
  • The number of images and tags in the repositories and the frequency of changes

  • Parallel batching

    For example, if a user is mirroring a repository that has 100 tags, the mirror will be completed by one worker. Users must consider how many repositories one wants to mirror in parallel, and base the number of workers around that.

    Multiple tags in the same repository cannot be mirrored in parallel.