Skip to main content

Use a registry proxy for Helm air gap installations

This topic describes how to connect the Replicated proxy registry to a Harbor or jFrog Artifactory instance to support pull-through image caching. It also includes information about how to set up replication rules in Harbor for image mirroring.

Overview​

For applications distributed with Replicated, the Replicated proxy registry grants proxy, or pull-through, access to application images without exposing registry credentials to customers.

Users can optionally connect the Replicated proxy registry with their own Harbor or jFrog Artifactory instance to proxy and cache the images that are required for installation on demand. This can be particularly helpful in Helm installations in air-gapped environments because it allows users to pull and cache images from an internet-connected machine, then access the cached images during installation from a machine with limited or no outbound internet access.

In addition to the support for on-demand pull-through caching, connecting the Replicated proxy registry to a Harbor or Artifactory instance also has the following benefits:

  • Registries like Harbor or Artifactory typically support access controls as well as scanning images for security vulnerabilities
  • With Harbor, users can optionally set up replication rules for image mirroring, which can be used to improve data availability and reliability

Limitations​

  • Artifactory does not support mirroring or replication for Docker registries. If you need to set up image mirroring, use Harbor. See Set Up Mirroring in Harbor below.

  • The Harbor proxy cache trims a multi-architecture manifest list down to the platforms that it has already cached, and stores the result under a digest that differs from the one in the source registry. This has two effects. An image reference that is pinned to a specific digest does not resolve through the cache, and any platform that was not cached is missing from the manifest list that Harbor serves. If your application uses digest-pinned or multi-architecture images, verify that they pull correctly through the cache before you rely on it for an installation. For more information, see Fix proxy cache manifest list reconcile in the Harbor repository.

Connect the Replicated proxy registry to Harbor​

Harbor is a popular open-source container registry. Users can connect the Replicated proxy registry to Harbor in order to cache images on demand and set up pull-based replication rules to proactively mirror images. Connecting the Replicated proxy registry to Harbor also allows customers use Harbor's security features.

Use Harbor for pull-through proxy caching​

To connect the Replicated proxy registry to Harbor for pull-through proxy caching:

  1. Log in to Harbor and create a new replication endpoint. This endpoint connects the Replicated proxy registry to the Harbor instance. For more information, see Creating Replication Endpoints in the Harbor documentation.

  2. Enter the following details for the endpoint:

    • For the provider field, choose Docker Registry.
    • For the URL field, enter https://proxy.replicated.com or the custom domain that is configured for the Replicated proxy registry. For more information about configuring custom domains in the Vendor Portal, see Use Custom Domains.
    • For the access ID, enter the email address associated with the customer in the Vendor Portal. This field is not validated, so any value is accepted.
    • For the access secret, enter the customer's credential. For customers using the Download Portal or the Classic Enterprise Portal, this is the customer's unique license ID, which you can find in the Vendor Portal by going to Customers > [Customer Name]. For customers using the new Enterprise Portal, this is a service account token. Service accounts have a token and no username, which is why there is no separate value for the access ID. Customer team admins create service accounts from Team Settings > Service Accounts in the Enterprise Portal. For more information, see Enable customer automation.

  3. Verify your configuration by testing the connection and then save the endpoint.

  4. After adding the Replicated proxy registry as a replication endpoint in Harbor, set up a proxy cache. This allows for pull-through image caching with Harbor. For more information, see Configure Proxy Cache in the Harbor documentation.

  5. (Optional) Add a pull-based replication rule to support image mirroring. See Configure Image Mirroring in Harbor below.

Configure image mirroring in Harbor​

To enable image mirroring with Harbor, users create a pull-based replication rule. This periodically (or when manually triggered) pulls images from the Replicated proxy registry to store them in Harbor.

The Replicated proxy regsitry exposes standard catalog and tag listing endpoints that are used by Harbor to support image mirroring:

  • The catalog endpoint returns a list of repositories built from images of the last 10 releases.
  • The tags listing endpoint lists the tags available in a given repository for those same releases.

When image mirroring is enabled, Harbor uses these endpoints to build a list of images to cache and then serve.

Limitations​

Image mirroring with Harbor has the following limitations:

  • Neither the catalog or tags listing endpoints exposed by the Replicated proxy service respect pagination requests. However, Harbor requests 1000 items at a time.

  • Only authenticated users can perform catalog calls or list tags. Authenticated users are those with an email address and license ID associated with a customer in the Vendor Portal.

Create a pull-based replication rule in Harbor for image mirroring​

To configure image mirroring in Harbor:

  1. Follow the steps in Use Harbor for Pull-Through Proxy Caching above to add the Replicated proxy registry to Harbor as a replication endpoint.

  2. Create a pull-based replication rule in Harbor to mirror images proactively. For more information, see Creating a replication rule in the Harbor documentation.

Use Artifactory for pull-through proxy caching​

jFrog Artifactory supports pull-through caching for Docker registries.

Create a Docker remote repository with the following settings:

  • URL: https://proxy.replicated.com, or the custom domain configured for the Replicated proxy registry.
  • Username: not validated. Enter any value.
  • Password: the customer's license ID, or a service account token for customers using the new Enterprise Portal.

Artifactory sends Basic credentials to the /v2/ endpoint to validate the configuration, so the connection test succeeds when the credential is valid.

Images on the Replicated proxy registry use the path proxy.replicated.com/proxy/<app-slug>/<registry-slug>/<repo>:<tag>. Through Artifactory the same image is available at <artifactory-host>/<repo-key>/proxy/<app-slug>/<registry-slug>/<repo>:<tag>. If you use a custom domain for the proxy registry, the host changes and the rest of the path is the same.

note

Customers pulling through Artifactory need to override the image repository values in your chart to point at the Artifactory host, and supply an image pull secret for Artifactory using their own Artifactory credentials rather than the Replicated credential above. The values to override depend on how your chart is structured.

For more information about how to configure a pull-through cache with Artifactory, see Remote Repository in the Artifactory documentation.

On this page