Merge pull request #3141 from replicatedhq/121666

Update steps for using the proxy registry in Helm installs

Author: paigecalvert

docs/partials/proxy-service/_step-creds.mdx

@@ -1 +1,3 @@
-Provide read-only credentials for the external private registry in your Replicated account. This allows Replicated to access the images through the proxy registry. See [Add Credentials for an External Registry](packaging-private-images#add-credentials-for-an-external-registry) in _Connecting to an External Registry_.
+In the Vendor Portal, go to **Images > Add external registry** and provide read-only credentials for your registry. This allows Replicated to access the images through the proxy registry. See [Add Credentials for an External Registry](packaging-private-images#add-credentials-for-an-external-registry) in _Connecting to an External Registry_.
+
+<img alt="Link a new registry in the Vendor Portal" src="../images/add-external-registry.png" width="500"/>

docs/partials/proxy-service/_step-custom-domain.mdx

@@ -1 +1 @@
-(Optional) Add a custom domain for the proxy registry instead of `proxy.replicated.com`. See [Use Custom Domains](custom-domains-using).
+(Recommended) Go to **Custom Domains > Add custom domain** and add a custom domain for the proxy registry. See [Use Custom Domains](custom-domains-using).

docs/vendor/helm-image-registry.mdx

@@ -7,127 +7,96 @@ This topic describes how to use the Replicated proxy registry to proxy images fo
 
 ## Overview
 
-With the Replicated proxy registry, each customer's unique license can grant proxy access to images in an external private registry. To enable the proxy registry for Helm installations, you must create a Secret with `type: kubernetes.io/dockerconfigjson` to authenticate with the proxy registry.
+With the Replicated proxy registry, each customer's unique license can grant proxy access to images in an external private registry.
 
-During Helm installations, after customers provide their license ID, a `global.replicated.dockerconfigjson` field that contains a base64 encoded Docker configuration file is automatically injected in the Helm chart values. You can use this `global.replicated.dockerconfigjson` field to create the required pull secret.
+During Helm installations, after customers provide their license ID, a `global.replicated.dockerconfigjson` field that contains a base64 encoded Docker configuration file is automatically injected in the Helm chart values. You can use this `global.replicated.dockerconfigjson` field to create the pull secret required to authenticate with the proxy registry.
 
-For information about how Kubernetes uses the `kubernetes.io/dockerconfigjson` Secret type to authenticate to a private image registry, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) in the Kubernetes documentation.
+## Pull Private Images Through the Proxy Registry in Helm Installations
 
-## Enable the Proxy Registry
-
-This section describes how to enable the proxy registry for applications deployed with Helm, including how to use the `global.replicated.dockerconfigjson` field that is injected during application deployment to create the required pull secret.
-
-To enable the proxy registry:
+To use the Replicated proxy registry for applications installed with Helm:
 
 1. <StepCreds/>
 
 1. <StepCustomDomain/>
 
-1. In your Helm chart templates, create a Kubernetes Secret to evaluate if the `global.replicated.dockerconfigjson` value is set, and then write the rendered value into a Secret on the cluster:
+1. In your Helm chart values file, set your image repository URL to the location of the image on the proxy registry. If you added a custom domain, use your custom domain. Otherwise, use `proxy.replicated.com`.
+
+      The proxy registry URL has the following format: `DOMAIN/proxy/APP_SLUG/EXTERNAL_REGISTRY_IMAGE_URL`
+      
+      Where:
+      * `DOMAIN` is either `proxy.replicated.com` or your custom domain.
+      * `APP_SLUG` is the unique slug of your application.
+      * `EXTERNAL_REGISTRY_IMAGE_URL` is the path to the private image on your external registry.
+      
+      **Example:**
+
+      ```yaml
+      # values.yaml
+      api:
+        image:
+          # proxy.registry.com or your custom domain
+          registry: ghcr.io
+          repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg
+          tag: catalog-1.24.0
+      ```
+
+1. Ensure that any references to the image in your Helm chart access the field from your values file.  
+
+   **Example**:
+
+    ```yaml
+    apiVersion: v1
+    kind: Pod
+    spec:
+      containers:
+        - name: api 
+            # Access the registry, repository, and tag fields from the values file
+            image: {{ .Values.images.api.registry }}/{{ .Values.images.api.repository }}:{{ .Values.images.api.tag }}
+    ```
+
+1. In your Helm chart templates, create a Kubernetes Secret to evaluate if the `global.replicated.dockerconfigjson` value is set and then write the rendered value into a Secret on the cluster, as shown below.
+
+   This Secret is used to authenticate with the proxy registry. For information about how Kubernetes uses the `kubernetes.io/dockerconfigjson` Secret type to provide authentication for a private registry, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) in the Kubernetes documentation. 
+
+   :::note
+   Do not use `replicated` for the name of the image pull secret because the Replicated SDK automatically creates a Secret named `replicated`. Using the same name causes an error.
+   :::
 
    ```yaml
-   # /templates/replicated-pull-secret.yaml
+   # templates/replicated-pull-secret.yaml
 
    {{ if .Values.global.replicated.dockerconfigjson }}
    apiVersion: v1
    kind: Secret
    metadata:
+     # Note: Do not use "replicated" for the name of the pull secret
      name: replicated-pull-secret
    type: kubernetes.io/dockerconfigjson
    data:
      .dockerconfigjson: {{ .Values.global.replicated.dockerconfigjson }}
    {{ end }}
    ```
+   
 
-   :::note
-   If you use the Replicated SDK, do not use `replicated` for the name of the image pull secret because the SDK automatically creates a Secret named `replicated`. Using the same name causes an error.
-   :::
-
-1. Ensure that you have a field in your Helm chart values file for your image repository URL, and that any references to the image in your Helm chart access the field from your values file.  
-
-   **Example**:
-
-   ```yaml
-   # values.yaml
-   ...
-   dockerconfigjson: '{{ .Values.global.replicated.dockerconfigjson }}'
-   images:
-     myapp:
-       # Add image URL in the values file
-       apiImageRepository: quay.io/my-org/api
-       apiImageTag: v1.0.1
-   ```
-   ```yaml
-   # /templates/deployment.yaml
-
-   apiVersion: apps/v1
-   kind: Deployment
-   metadata:
-    name: example
-   spec:
-     template:
-       spec:
-         containers:
-           - name: api
-             # Access the apiImageRepository field from the values file
-             image: {{ .Values.images.myapp.apiImageRepository }}:{{ .Values.images.myapp.apiImageTag }}
-   ```
-
-1. In your Helm chart templates, add the image pull secret that you created to any manifests that reference the private image:
-
-   ```yaml
-   # /templates/example.yaml
-   ...
-   {{ if .Values.global.replicated.dockerconfigjson }}
-   imagePullSecrets:
-     - name: replicated-pull-secret
-   {{ end }}
-   ```
+1. Add the image pull secret that you created to any manifests that reference the image:
 
    **Example:**
 
     ```yaml
-    # /templates/deployment.yaml
-    ...
-    image: "{{ .Values.images.myapp.apiImageRepository }}:{{ .Values.images.myapp.apiImageTag }}"
-    {{ if .Values.global.replicated.dockerconfigjson }}
-    imagePullSecrets:
-      - name: replicated-pull-secret
-    {{ end }}
-    name: myapp
-    ports:
-    - containerPort: 3000
-      name: http
+    apiVersion: v1
+    kind: Pod
+    spec:
+      containers:
+        - name: api 
+      # Access the registry, repository, and tag fields from the values file
+            image: {{ .Values.images.api.registry }}/{{ .Values.images.api.repository }}:{{ .Values.images.api.tag }}
+            # Add the pull secret
+            {{ if .Values.global.replicated.dockerconfigjson }}
+            imagePullSecrets:
+              - name: replicated-pull-secret
+            {{ end }}
     ```
 
 1. Package your Helm chart and add it to a release. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases).
 
-1. Install the chart in a development environment to test your changes:
-
-   1. Create a local `values.yaml` file to override the default external registry image URL with the URL for the image on `proxy.replicated.com`.
-   
-      The proxy registry URL has the following format: `proxy.replicated.com/proxy/APP_SLUG/EXTERNAL_REGISTRY_IMAGE_URL`
-      
-      Where:
-      * `APP_SLUG` is the slug of your Replicated application.
-      * `EXTERNAL_REGISTRY_IMAGE_URL` is the path to the private image on your external registry.
-
-      **Example**
-      ```yaml
-      # A local values.yaml file
-      ...
-      images:
-        myapp:
-          apiImageRepository: proxy.replicated.com/proxy/my-app/quay.io/my-org/api
-          apiImageTag: v1.0.1
-
-      ```
-
-      :::note
-      If you configured a custom domain for the proxy registry, use the custom domain instead of `proxy.replicated.com`. For more information, see [Use Custom Domains](custom-domains-using).
-      :::
-   
-   1. Log in to the Replicated registry and install the chart, passing the local `values.yaml` file you created with the `--values` flag. See [Install with Helm](install-with-helm).
-
-
-    
+1. Install in a development environment to test your changes. See [Install with Helm](/vendor/install-with-helm).