From f10061fa14d0c513fa26d48225736efe0ff77f38 Mon Sep 17 00:00:00 2001 From: pandemicsyn Date: Tue, 29 Oct 2024 11:13:19 -0500 Subject: [PATCH 1/6] Add Harbor/Artificatory documentation --- docs/vendor/helm-install-airgap.mdx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/vendor/helm-install-airgap.mdx b/docs/vendor/helm-install-airgap.mdx index 07c70d273c..d8af178d06 100644 --- a/docs/vendor/helm-install-airgap.mdx +++ b/docs/vendor/helm-install-airgap.mdx @@ -101,3 +101,19 @@ 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. + +## Pull through registry proxies and mirrors + +The Replicated proxy registry supports additional functionality that can help streamline the air gap installation and update process for customers. For authenticated users, the Replicated proxy registry exposes standard catalog and tag listing endpoints that can be used to generate a list of images required for installation. These endpoints will list images for the last 10 releases. + +### Integration with Harbor + +[Harbor](https://goharbor.io) is a popular open-source container registry that supports both pull through proxy caching and repository mirroring (via pull based replication rules). Customers can use Harbor to cache images on demand and set up replication rules to proactively mirror images. + +The first step is simply adding the Replicated proxy registry with the customer's credentials (the `license_id`) as a standard Docker Registry ([Harbor - Configure Proxy Cache](https://goharbor.io/docs/2.11.0/administration/configure-proxy-cache/)). That alone will allow the customer to pull images through harbor on demand and utilize Harbor's caching, security, and other features. + +The second optional step is to set up a **pull based** replication rule in Harbor to mirror the images that are required for installation or update automatically ([Harbor - Creating a replication rule](https://goharbor.io/docs/2.11.0/administration/configuring-replication/create-replication-rules/)). This will periodically (or when manually triggered) pull images from the Replicated proxy registry and store them in Harbor. + +### Integration with Artifactory + +Artifactory support's a pull through caching mode for Docker registries but does not support Docker registry mirroring or replication. For information on setting up a pull through cache with Artifactory, see [Artifactory - Remote Repository](https://jfrog.com/help/r/jfrog-artifactory-documentation/configure-a-remote-repository). \ No newline at end of file From 173d46b679248d61f981f95d4b1b02b6c67d6b07 Mon Sep 17 00:00:00 2001 From: pandemicsyn Date: Tue, 29 Oct 2024 11:26:52 -0500 Subject: [PATCH 2/6] typos --- docs/vendor/helm-install-airgap.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/vendor/helm-install-airgap.mdx b/docs/vendor/helm-install-airgap.mdx index d8af178d06..82b33d0f1e 100644 --- a/docs/vendor/helm-install-airgap.mdx +++ b/docs/vendor/helm-install-airgap.mdx @@ -110,9 +110,9 @@ The Replicated proxy registry supports additional functionality that can help st [Harbor](https://goharbor.io) is a popular open-source container registry that supports both pull through proxy caching and repository mirroring (via pull based replication rules). Customers can use Harbor to cache images on demand and set up replication rules to proactively mirror images. -The first step is simply adding the Replicated proxy registry with the customer's credentials (the `license_id`) as a standard Docker Registry ([Harbor - Configure Proxy Cache](https://goharbor.io/docs/2.11.0/administration/configure-proxy-cache/)). That alone will allow the customer to pull images through harbor on demand and utilize Harbor's caching, security, and other features. +The first step is simply adding the Replicated proxy registry with the customer's credentials (the `license_id`) as a standard Docker Registry ([Harbor - Configure Proxy Cache](https://goharbor.io/docs/2.11.0/administration/configure-proxy-cache/)). That alone will allow the customer to pull images through Harbor on demand and utilize Harbor's caching, security, and other features. -The second optional step is to set up a **pull based** replication rule in Harbor to mirror the images that are required for installation or update automatically ([Harbor - Creating a replication rule](https://goharbor.io/docs/2.11.0/administration/configuring-replication/create-replication-rules/)). This will periodically (or when manually triggered) pull images from the Replicated proxy registry and store them in Harbor. +The second optional step is to set up a **pull based** replication rule in Harbor to mirror images needed proactively ([Harbor - Creating a replication rule](https://goharbor.io/docs/2.11.0/administration/configuring-replication/create-replication-rules/)). This will periodically (or when manually triggered) pull images from the Replicated proxy registry to store them in Harbor. ### Integration with Artifactory From aa5f140c12745a8cfc2c6c04ae6675890436681b Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 29 Oct 2024 19:49:27 -0600 Subject: [PATCH 3/6] docs edits part 1 --- docs/vendor/helm-install-airgap.mdx | 41 +++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/docs/vendor/helm-install-airgap.mdx b/docs/vendor/helm-install-airgap.mdx index 82b33d0f1e..2133716ce6 100644 --- a/docs/vendor/helm-install-airgap.mdx +++ b/docs/vendor/helm-install-airgap.mdx @@ -102,18 +102,43 @@ With the list of images the provided `bash` script will automate the process of 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. -## Pull through registry proxies and mirrors +## Using a Pull-Through Proxy -The Replicated proxy registry supports additional functionality that can help streamline the air gap installation and update process for customers. For authenticated users, the Replicated proxy registry exposes standard catalog and tag listing endpoints that can be used to generate a list of images required for installation. These endpoints will list images for the last 10 releases. +For authenticated users, the [Replicated proxy registry](/vendor/private-images-about) exposes standard catalog and tag listing endpoints that are used during Helm installations in air-gapped environments to generate the list of images required for installation. These endpoints are provided in the Helm air gap installation instructions in the Replicated Download Portal. For example, an `'updates.wp-e.10/my-app/1.2.3/images'` endpoint would return images for version 1.2.3 of an application from the proxy registry. -### Integration with Harbor +Users can optionally connect the Replicated proxy registry with [Harbor](https://goharbor.io) or Artifactory in order to use these endpoints to cache images. Integrating with Harbor also allows users to set up replicated rules for mirroring. -[Harbor](https://goharbor.io) is a popular open-source container registry that supports both pull through proxy caching and repository mirroring (via pull based replication rules). Customers can use Harbor to cache images on demand and set up replication rules to proactively mirror images. +### Limitations -The first step is simply adding the Replicated proxy registry with the customer's credentials (the `license_id`) as a standard Docker Registry ([Harbor - Configure Proxy Cache](https://goharbor.io/docs/2.11.0/administration/configure-proxy-cache/)). That alone will allow the customer to pull images through Harbor on demand and utilize Harbor's caching, security, and other features. +Connecting the Replicated proxy registry with Harbor and Artifactory has the following limitations: -The second optional step is to set up a **pull based** replication rule in Harbor to mirror images needed proactively ([Harbor - Creating a replication rule](https://goharbor.io/docs/2.11.0/administration/configuring-replication/create-replication-rules/)). This will periodically (or when manually triggered) pull images from the Replicated proxy registry to store them in Harbor. +* Neither the catalog or tags listing endpoints respect pagination requests yet but harbor requests 1000 items at a time. (Documented in "Harbor _catalog use": https://docs.google.com/document/d/1Ece7PaFOV12EVhMWFMHkrVZLDHFQfWUv4rWzi_wRjAM/edit#heading=h.wxiwuxpqb3pw) +* Only authenticated users can perform catalog calls or list tags +* Artifactory does not support Docker registry mirroring or replication. -### Integration with Artifactory +### Integrate With Harbor -Artifactory support's a pull through caching mode for Docker registries but does not support Docker registry mirroring or replication. For information on setting up a pull through cache with Artifactory, see [Artifactory - Remote Repository](https://jfrog.com/help/r/jfrog-artifactory-documentation/configure-a-remote-repository). \ No newline at end of file +[Harbor](https://goharbor.io) is a popular open-source container registry that supports both pull-through proxy caching and repository mirroring through pull based replication rules. Users can add the Replicated proxy registry to Harbor in order to cache images on demand and set up replication rules to proactively mirror images. It also allows customers use Harbor's caching, security, and other features. + +To connect the Replicated proxy registry with Harbor: + +1. Log in to Harbor and create a new registry endpoint. You will configure this endpoint to connect to the Replicated proxy registry. + +1. Enter the following details for the registry endpoint: + + * For the provider field, choose Docker Registry + * For the URL field, enter `https://proxy.replicated.com` or the custom domain that you configured for the 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 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. + +After connecting the Replicated proxy registry with Harbor, users can set up a proxy cache. For more information, see [Configure Proxy Cache](https://goharbor.io/docs/2.11.0/administration/configure-proxy-cache/) + +Users can also optionally set up a **pull based** replication rule in Harbor to mirror images proactively. This periodically (or when manually triggered) pulls images from the Replicated proxy registry to store them in Harbor. 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. + +### Integrate With Artifactory + +Artifactory supports a pull-through caching mode 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 From d78c550fdee5b21e5f512c1972d7f77bd84cf1f1 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 30 Oct 2024 10:26:16 -0600 Subject: [PATCH 4/6] docs edits part 2 --- .../helm-install-airgap-registry-proxy.mdx | 52 +++++++++++++++++++ docs/vendor/helm-install-airgap.mdx | 43 ++------------- sidebars.js | 1 + 3 files changed, 56 insertions(+), 40 deletions(-) create mode 100644 docs/vendor/helm-install-airgap-registry-proxy.mdx diff --git a/docs/vendor/helm-install-airgap-registry-proxy.mdx b/docs/vendor/helm-install-airgap-registry-proxy.mdx new file mode 100644 index 0000000000..eaa9a28ae0 --- /dev/null +++ b/docs/vendor/helm-install-airgap-registry-proxy.mdx @@ -0,0 +1,52 @@ +# Using a Registry Proxy for Helm Air Gap Installations (Alpha) + +This topic describes how enterprise users can configure a registry proxy using Harbor or jFrog Artifactory in order to proxy and cache images for Helm air gap installations. + +## Overview + +When installing with Helm in air-gapped environments, authenticated users must first pull the images that are required for installation from the [Replicated proxy registry](/vendor/private-images-about) using an internet-connected machine. + +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 in order to set up a registry proxy. The Replicated proxy regsitry exposes standard catalog and tag listing endpoints that can be used by authenticated users to proxy and cache images on demand from a Harbor or Artifactory instance: +* 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. + +In addition to on-demand image caching, using a registry proxy also has the following benefits: +* Registry proxies typically support access controls as well as scanning images for security vulnerabilities +* With Harbor, users can set up replicated rules for mirroring to improve the availability and reliability of the data + +## Limitations + +Using Harbor or Artifactory as a registry proxy 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. + +* Artifactory does not support mirroring or replication for Docker registries. + +## Connect the Replicated Proxy Registry to Harbor + +[Harbor](https://goharbor.io) is a popular open-source container registry that supports both pull-through proxy caching and repository mirroring through pull based replication rules. Users can add the Replicated proxy registry to Harbor in order to cache images on demand and set up replication rules to proactively mirror images. This also allows customers use Harbor's caching, security, and other features. + +To connect the Replicated proxy registry to Harbor: + +1. Log in to Harbor and create a new replication endpoint. You will configure this endpoint to connect to the Replicated proxy registry. 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 you configured for the 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 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. Configuring a proxy cache allows users to pull images through Harbor on demand and also use Harbor's caching, security, and other features. For more information, see [Configure Proxy Cache](https://goharbor.io/docs/2.11.0/administration/configure-proxy-cache/) in the Harbor documentation. + +1. (Optional) Set up a **pull based** replication rule in Harbor to mirror images proactively. This periodically (or when manually triggered) pulls images from the Replicated proxy registry to store them in Harbor. 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. + +## Connect the Replicated Proxy Registry to Artifactory + +[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/docs/vendor/helm-install-airgap.mdx b/docs/vendor/helm-install-airgap.mdx index 2133716ce6..312ac4963d 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 @@ -102,43 +102,6 @@ With the list of images the provided `bash` script will automate the process of 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. -## Using a Pull-Through Proxy +## Use a Harbor or Artifactory Registry Proxy -For authenticated users, the [Replicated proxy registry](/vendor/private-images-about) exposes standard catalog and tag listing endpoints that are used during Helm installations in air-gapped environments to generate the list of images required for installation. These endpoints are provided in the Helm air gap installation instructions in the Replicated Download Portal. For example, an `'updates.wp-e.10/my-app/1.2.3/images'` endpoint would return images for version 1.2.3 of an application from the proxy registry. - -Users can optionally connect the Replicated proxy registry with [Harbor](https://goharbor.io) or Artifactory in order to use these endpoints to cache images. Integrating with Harbor also allows users to set up replicated rules for mirroring. - -### Limitations - -Connecting the Replicated proxy registry with Harbor and Artifactory has the following limitations: - -* Neither the catalog or tags listing endpoints respect pagination requests yet but harbor requests 1000 items at a time. (Documented in "Harbor _catalog use": https://docs.google.com/document/d/1Ece7PaFOV12EVhMWFMHkrVZLDHFQfWUv4rWzi_wRjAM/edit#heading=h.wxiwuxpqb3pw) -* Only authenticated users can perform catalog calls or list tags -* Artifactory does not support Docker registry mirroring or replication. - -### Integrate With Harbor - -[Harbor](https://goharbor.io) is a popular open-source container registry that supports both pull-through proxy caching and repository mirroring through pull based replication rules. Users can add the Replicated proxy registry to Harbor in order to cache images on demand and set up replication rules to proactively mirror images. It also allows customers use Harbor's caching, security, and other features. - -To connect the Replicated proxy registry with Harbor: - -1. Log in to Harbor and create a new registry endpoint. You will configure this endpoint to connect to the Replicated proxy registry. - -1. Enter the following details for the registry endpoint: - - * For the provider field, choose Docker Registry - * For the URL field, enter `https://proxy.replicated.com` or the custom domain that you configured for the 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 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. - -After connecting the Replicated proxy registry with Harbor, users can set up a proxy cache. For more information, see [Configure Proxy Cache](https://goharbor.io/docs/2.11.0/administration/configure-proxy-cache/) - -Users can also optionally set up a **pull based** replication rule in Harbor to mirror images proactively. This periodically (or when manually triggered) pulls images from the Replicated proxy registry to store them in Harbor. 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. - -### Integrate With Artifactory - -Artifactory supports a pull-through caching mode 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 +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)](helm-install-airgap-registry-proxy). \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 6d837d7818..f9ea5e7d34 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/helm-install-airgap-registry-proxy', ], }, { From 681661b03c16b73c7cf6c182fda93c8dbebfd1cd Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 30 Oct 2024 11:57:43 -0600 Subject: [PATCH 5/6] edits --- .../helm-install-airgap-registry-proxy.mdx | 52 ------------- .../using-third-party-registry-proxy.mdx | 74 +++++++++++++++++++ sidebars.js | 2 +- 3 files changed, 75 insertions(+), 53 deletions(-) delete mode 100644 docs/vendor/helm-install-airgap-registry-proxy.mdx create mode 100644 docs/vendor/using-third-party-registry-proxy.mdx diff --git a/docs/vendor/helm-install-airgap-registry-proxy.mdx b/docs/vendor/helm-install-airgap-registry-proxy.mdx deleted file mode 100644 index eaa9a28ae0..0000000000 --- a/docs/vendor/helm-install-airgap-registry-proxy.mdx +++ /dev/null @@ -1,52 +0,0 @@ -# Using a Registry Proxy for Helm Air Gap Installations (Alpha) - -This topic describes how enterprise users can configure a registry proxy using Harbor or jFrog Artifactory in order to proxy and cache images for Helm air gap installations. - -## Overview - -When installing with Helm in air-gapped environments, authenticated users must first pull the images that are required for installation from the [Replicated proxy registry](/vendor/private-images-about) using an internet-connected machine. - -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 in order to set up a registry proxy. The Replicated proxy regsitry exposes standard catalog and tag listing endpoints that can be used by authenticated users to proxy and cache images on demand from a Harbor or Artifactory instance: -* 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. - -In addition to on-demand image caching, using a registry proxy also has the following benefits: -* Registry proxies typically support access controls as well as scanning images for security vulnerabilities -* With Harbor, users can set up replicated rules for mirroring to improve the availability and reliability of the data - -## Limitations - -Using Harbor or Artifactory as a registry proxy 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. - -* Artifactory does not support mirroring or replication for Docker registries. - -## Connect the Replicated Proxy Registry to Harbor - -[Harbor](https://goharbor.io) is a popular open-source container registry that supports both pull-through proxy caching and repository mirroring through pull based replication rules. Users can add the Replicated proxy registry to Harbor in order to cache images on demand and set up replication rules to proactively mirror images. This also allows customers use Harbor's caching, security, and other features. - -To connect the Replicated proxy registry to Harbor: - -1. Log in to Harbor and create a new replication endpoint. You will configure this endpoint to connect to the Replicated proxy registry. 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 you configured for the 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 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. Configuring a proxy cache allows users to pull images through Harbor on demand and also use Harbor's caching, security, and other features. For more information, see [Configure Proxy Cache](https://goharbor.io/docs/2.11.0/administration/configure-proxy-cache/) in the Harbor documentation. - -1. (Optional) Set up a **pull based** replication rule in Harbor to mirror images proactively. This periodically (or when manually triggered) pulls images from the Replicated proxy registry to store them in Harbor. 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. - -## Connect the Replicated Proxy Registry to Artifactory - -[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/docs/vendor/using-third-party-registry-proxy.mdx b/docs/vendor/using-third-party-registry-proxy.mdx new file mode 100644 index 0000000000..7dfbfe7a0c --- /dev/null +++ b/docs/vendor/using-third-party-registry-proxy.mdx @@ -0,0 +1,74 @@ +# 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 that supports both pull-through proxy caching and repository mirroring through _pull based_ replication rules. + +Users can add the Replicated proxy registry to Harbor in order to cache images on demand and set up 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 f9ea5e7d34..750a89698b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -494,7 +494,7 @@ const sidebars = { 'vendor/helm-install-overview', 'vendor/install-with-helm', 'vendor/helm-install-airgap', - 'vendor/helm-install-airgap-registry-proxy', + 'vendor/using-third-party-registry-proxy', ], }, { From 54475d2e934d2294bb1aa4a5b1303129cb873a99 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 30 Oct 2024 12:02:42 -0600 Subject: [PATCH 6/6] minor edits --- docs/vendor/helm-install-airgap.mdx | 2 +- docs/vendor/using-third-party-registry-proxy.mdx | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/vendor/helm-install-airgap.mdx b/docs/vendor/helm-install-airgap.mdx index 312ac4963d..e5100b389c 100644 --- a/docs/vendor/helm-install-airgap.mdx +++ b/docs/vendor/helm-install-airgap.mdx @@ -104,4 +104,4 @@ Unless the customer has set up the `values` to preserve the updated tag (for exa ## 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)](helm-install-airgap-registry-proxy). \ No newline at end of file +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 index 7dfbfe7a0c..c8c8b06fb5 100644 --- a/docs/vendor/using-third-party-registry-proxy.mdx +++ b/docs/vendor/using-third-party-registry-proxy.mdx @@ -18,9 +18,7 @@ Artifactory does not support mirroring or replication for Docker registries. If ## Connect the Replicated Proxy Registry to Harbor -[Harbor](https://goharbor.io) is a popular open-source container registry that supports both pull-through proxy caching and repository mirroring through _pull based_ replication rules. - -Users can add the Replicated proxy registry to Harbor in order to cache images on demand and set up replication rules to proactively mirror images. Connecting the Replicated proxy registry to Harbor also allows customers use Harbor's security features. +[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}