diff --git a/docs/vendor/helm-install-airgap.mdx b/docs/vendor/helm-install-airgap.mdx index 07c70d273c..e5100b389c 100644 --- a/docs/vendor/helm-install-airgap.mdx +++ b/docs/vendor/helm-install-airgap.mdx @@ -72,7 +72,7 @@ To install with Helm in an air gap environment: Replicated recommends that vendors provide detailed documentation that describes the values that customers need to configure. ::: -1. Finally, use the commands provided and the edited `values.yaml` to run preflight checks and install the release with Helm. +1. Use the commands provided and the edited `values.yaml` to run preflight checks and install the release with Helm. ## Perform Updates @@ -101,3 +101,7 @@ After logging into the registry, the customer exports their current version and With the list of images the provided `bash` script will automate the process of pulling updated images from the repository, tagging them with a name for an internal registry, and then pushing the newly tagged images to their internal registry. Unless the customer has set up the `values` to preserve the updated tag (for example, by using the `latest` tag), they need to edit the `values.yaml` to reference the new image tags. After doing so, they can log in to the OCI registry and perform the commands to install the updated chart. + +## Use a Harbor or Artifactory Registry Proxy + +You can integrate the Replicated proxy registry with an existing Harbor or jFrog Artifactory instance to proxy and cache images on demand. For more information, see [Using a Registry Proxy for Helm Air Gap Installations (Alpha)](using-third-party-registry-proxy). \ No newline at end of file diff --git a/docs/vendor/using-third-party-registry-proxy.mdx b/docs/vendor/using-third-party-registry-proxy.mdx new file mode 100644 index 0000000000..c8c8b06fb5 --- /dev/null +++ b/docs/vendor/using-third-party-registry-proxy.mdx @@ -0,0 +1,72 @@ +# Using a Registry Proxy for Helm Air Gap Installations (Alpha) + +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](/vendor/private-images-about) 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](https://goharbor.io) or [jFrog Artifactory](https://jfrog.com/help/r/jfrog-artifactory-documentation) 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 + +## Limtiation + +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](#harbor-mirror) below. + +## Connect the Replicated Proxy Registry to Harbor + +[Harbor](https://goharbor.io) 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 {#harbor-proxy-cache} + +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](https://goharbor.io/docs/2.11.0/administration/configuring-replication/create-replication-endpoints/) in the Harbor documentation. + +1. 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 [Using Custom Domains](/vendor/custom-domains-using). + * For the access ID, enter the email address associated with the customer in the Vendor Portal. + * For the access secret, enter the customer's unique license ID. You can find the license ID in the Vendor Portal by going to **Customers > [Customer Name]**. + +1. Verify your configuration by testing the connection and then save the endpoint. + +1. 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](https://goharbor.io/docs/2.11.0/administration/configure-proxy-cache/) in the Harbor documentation. + +1. (Optional) Add a pull-based replication rule to support image mirroring. See [Configure Image Mirroring in Harbor](#harbor-mirror) below. + +### Configure Image Mirroring in Harbor {#harbor-mirror} + +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](#harbor-proxy-cache) above to add the Replicated proxy registry to Harbor as a replication endpoint. + +1. Create a **pull-based** replication rule in Harbor to mirror images proactively. For more information, see [Creating a replication rule](https://goharbor.io/docs/2.11.0/administration/configuring-replication/create-replication-rules/) in the Harbor documentation. + +## Use Artifactory for Pull-Through Proxy Caching + +[jFrog Artifactory](https://jfrog.com/help/r/jfrog-artifactory-documentation) supports pull-through caching for Docker registries. + +For information about how to configure a pull-through cache with Artifactory, see [Remote Repository](https://jfrog.com/help/r/jfrog-artifactory-documentation/configure-a-remote-repository) in the Artifactory documentation. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 6d837d7818..750a89698b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -494,6 +494,7 @@ const sidebars = { 'vendor/helm-install-overview', 'vendor/install-with-helm', 'vendor/helm-install-airgap', + 'vendor/using-third-party-registry-proxy', ], }, {