A registry mirror allows users to cache Docker images locally, reducing reliance on external registries like Docker Hub. This is especially important for avoiding Docker Hub’s rate limits, which can disrupt workflows. By configuring a registry mirror, you ensure more reliable and faster builds while mitigating issues related to external service outages.
Prerequisite considerations
Before configuring a registry mirror, ensure the following:
-
Administrative rights: To create and manage integrations, you must have administrative rights at the organization level.
-
Existing Docker registry: You must have an existing Docker registry that can act as a mirror, or the ability to set one up. This can be a private registry hosted within your infrastructure.
-
Network configuration: Ensure that your network configuration allows communication between the CloudBees platform and the custom registry mirror. This includes opening necessary ports and configuring firewall rules.
-
Registry prefixes: Understand the registry prefixes (for example,
docker.io/library) used in your Docker images. This knowledge is crucial for correctly routing image pulls through the mirror. -
Authentication: If your custom registry mirror or source registry requires authentication, ensure you have the necessary credentials (username, password, and/or token) ready for the configuration process.
-
Monitoring tools: Set up monitoring tools to track the performance and usage of your registry mirror. This helps manage the mirror effectively and identify issues early. Refer to Analytics or CI insights for Jenkins® for more information.
-
Backup plan: Have a backup plan in case the registry mirror fails, ensuring that your builds can continue to run without disruption.
Important configuration considerations
Review these considerations before configuring a registry mirror.
-
Unique prefixes: Ensure each prefix is unique across all configured rules, as this determines how the platform selects the appropriate mirror.
-
Handling multiple mirrors: While the platform currently supports only one mirror, future updates may allow for multiple mirrors to be configured.
-
Suffix appending: When rewriting an image reference based on a matching mapping rule, the suffix (the string after the matched prefix) of the given container image reference is appended to the registry mirror URL.
-
Mirror fallback: If the image is not found on the mirror, CloudBees pulls from the original
docker.ioregistry (depending on the configuration and fallback settings).
Configure a registry mirror
This setup uses the Create integration function. It allows you to cache Docker images locally.
To configure a registry mirror in the CloudBees platform
-
Navigate to .
-
Select an organization, and then select Create integration.
-
Select CI tools.
-
Select Container Registry Mirror integrations.
-
Enter a Name. For example,
docker-hub. -
(Optional) Enter a Description.
-
Enter the Prefix, such as the registry server or path, to specify where images are routed through the mirror. For example,
docker.io.If for example,
docker.iois entered for the Prefix, the CloudBees platform first attempts to pull the image reference fromregistry.example.com/mirror/dockerhub/library/ubuntu:latest. If the image is not found within the mirror, or the mirror is unavailable, the platform falls back to using the original path:docker.io/library/ubuntu:latest. -
Enter the URLs of your custom registry Mirrors, using Enter as a delimiter. For example,
https://registry.example.com/mirror/dockerhub.
Figure 1. Registry mirror configuration example.
-
The registry mirror integration is created accordingly.
Verify the integration
To verify that the registry mirror is correctly configured:
-
Navigate to .
-
Confirm the registry mirror integration you created is listed under your integrations.
If configured correctly, Docker image pulls are routed through your specified registry mirror, helping to avoid rate limits and improve build reliability.
Use the registry mirror in workflows
By default, the CloudBees platform applies the configured registry mirror to all workflows that require Docker images. The platform automatically uses the specified mirror for image pulls and pushes.
Automatic image reference rewriting:
-
Image references are automatically rewritten based on your organization’s global registry mirror configuration. This ensures all Docker image requests within your workflows are directed to the configured mirror without additional manual intervention.
Explicit authentication required:
-
Despite the registry mirror’s automatic application, users must explicitly authenticate with each mirror used within their workflows. This is necessary to ensure secure and authorized access to the images stored in these mirrors.
-
To handle authentication, users can employ actions such as
configure-oci-credentialsorconfigure-ecr-credentials, depending on the type of registry mirror they are using. These actions allow you to log in to the registries.