Redistribute helmchart v2 topic

docs/enterprise/image-registry-kurl.md

@@ -16,7 +16,7 @@ To keep the registry from running out of storage, images that are no longer used
 For more information about the kURL Registry add-on, see [Registry Add-On](https://kurl.sh/docs/add-ons/registry) in the kURL documentation.
 
 :::note
-Users can also configure their own private registry for kURL installations instead of using the kURL registry. For more information, see [Configure Local Image Registries](/enterprise/image-registry-settings).
+Users can also configure their own private registry for kURL installations instead of using the kURL registry. For more information, see [Configure Local Image Registries in the Admin Console](/enterprise/image-registry-settings).
 :::
 
 ## Trigger Garbage Collection
@@ -66,6 +66,6 @@ The kURL registry image garbage collection feature has following limitations:
 
 * **Shared Image Registries**: The image garbage collection process assumes that the registry is not shared with any other instances of Replicated KOTS, nor shared with any external applications. If the built-in kURL registry is used by another external application, disable garbage collection to prevent image loss.
 
-* **Customer-Supplied Registries**: Image garbage collection is supported only when used with the built-in kURL registry. If the KOTS instance is configured to use a different registry, disable garbage collection to prevent image loss. For more information about configuring an image registry in the Admin Console, see [Configure Local Image Registries](/enterprise/image-registry-settings).
+* **Customer-Supplied Registries**: Image garbage collection is supported only when used with the built-in kURL registry. If the KOTS instance is configured to use a different registry, disable garbage collection to prevent image loss. For more information about configuring an image registry in the Admin Console, see [Configure Local Image Registries in the Admin Console](/enterprise/image-registry-settings).
 
 * **Application Rollbacks**: Image garbage collection has no effect when the `allowRollback` field in the KOTS Application custom resource is set to `true`. For more information, see [Application](/reference/custom-resource-application) in _KOTS Custom Resources_.

docs/enterprise/image-registry-rate-limits.md

@@ -1,6 +1,6 @@
 # Avoid Docker Hub Rate Limits
 
-This topic describes how to avoid rate limiting for anonymous and free authenticated use of Docker Hub by providing a Docker Hub username and password to the `kots docker ensure-secret` command.
+This topic describes how to avoid rate limiting for anonymous and free authenticated use of Docker Hub. The information in this topic applies to applications deployed with Replicated KOTS that have public Docker Hub images that are rate limited.
 
 ## Overview
 
@@ -10,20 +10,47 @@ Docker Pro and Docker Team accounts continue to have unlimited access to pull co
 
 For more information on rate limits, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website.
 
-If the application that you are installing or upgrading has public Docker Hub images that are rate limited, then an error occurs when the rate limit is reached.
+If your application has public Docker Hub images that are rate limited, then an error occurs when the rate limit is reached.
 
-## Provide Docker Hub Credentials
+## Prerequisite
 
-To avoid errors caused by reaching the Docker Hub rate limit, a Docker Hub username and password can be passed to the `kots docker ensure-secret` command. The Docker Hub username and password are used only to increase rate limits and do not need access to any private repositories on Docker Hub.
+For any Helm charts in your application that are deployed with the KOTS HelmChart v2 custom resource, configure the HelmChart v2 custom resource `values` key to add an image pull secret named `APP_SLUG-kotsadm-dockerhub` (where `APP_SLUG` is your application slug) to any Docker images that could be rate-limited. This pull secret allows your users to run the `kots docker ensure-secret` command for their installation.
 
-Example:
+The HelmChart `values` key creates a mapping between KOTS and the `values.yaml` file for your Helm chart. This allows you to set or delete Helm values during installation or upgrade with KOTS, without having to make any changes to the Helm chart itself. For more information about working with the `values` key, see [Set Helm Values with KOTS](/vendor/helm-optional-value-keys).
 
-```bash
-kubectl kots docker ensure-secret --dockerhub-username sentrypro --dockerhub-password password --namespace sentry-pro
-```
+**Example:**
 
-The `kots docker ensure-secret` command creates an image pull secret that KOTS can use when pulling images.
+```yaml
+# kots.io/v1beta2 HelmChart custom resource
+apiVersion: kots.io/v1beta2
+kind: HelmChart
+metadata:
+  name: samplechart
+spec:
+  values:
+    image:
+      registry: docker.io
+      repository: org-name/example-docker-hub-image
+      # Add the dockerhub secret
+      pullSecrets:
+      - name: gitea-kotsadm-dockerhub
+```   
 
-KOTS then creates a new release sequence for the application to apply the image pull secret to all Kubernetes manifests that have images. After running the `kots docker ensure-secret` command, deploy this new release sequence either from the Admin Console or the KOTS CLI.
+## Provide Docker Hub Credentials with `kots docker ensure-secret`
+
+To avoid errors caused by reaching the Docker Hub rate limit, your users can pass a Docker Hub username and password to the `kots docker ensure-secret` command. The `kots docker ensure-secret` command creates an image pull secret that KOTS can use when pulling Docker Hub images and applies the Secret to application images where necessary.
+
+:::note
+The Docker Hub username and password passed with the `kots docker ensure-secret` command are used only to increase rate limits and do not need access to any private repositories on Docker Hub.
+:::
+
+1. Run the following command:
+
+     ```bash
+     kubectl kots docker ensure-secret --dockerhub-username sentrypro --dockerhub-password password --namespace sentry-pro
+     ```
+     KOTS then creates a new release sequence for the application to apply the image pull secret to all Kubernetes manifests that have images. 
+
+1. Deploy the new release sequence.
 
 For more information, see [docker ensure-secret](/reference/kots-cli-docker-ensure-secret) in the KOTS CLI documentation.

docs/enterprise/image-registry-settings.mdx

@@ -1,15 +1,15 @@
 import ImageRegistrySettings from "../partials/image-registry/_image-registry-settings.mdx"
 import DockerCompatibility from "../partials/image-registry/_docker-compatibility.mdx"
 
-# Configure Local Image Registries
+# Configure Local Image Registries in the Admin Console
 
 This topic describes how to configure private registry settings in the Replicated KOTS Admin Console.
 
 The information in this topic applies to existing cluster installations with KOTS and installations with Replicated kURL. This topic does _not_ apply to Replciated Embedded Cluster installations.
 
 ## Overview
 
-Using a private registry lets you create a custom image pipeline. Any proprietary configurations that you make to the application are shared only with the groups that you allow access, such as your team or organization. You also have control over the storage location, logging messages, load balancing requests, and other configuration options. Private registries can be used with online or air gap clusters.
+Using a private registry lets your users create a custom image pipeline. This gives users control over the storage location, logging messages, load balancing requests, and other configuration options. Private registries can be used with online or air gap clusters.
 
 ## Requirement
 
@@ -19,7 +19,7 @@ The domain of the image registry must support a Docker V2 protocol. KOTS has bee
 
 ## Configure Local Private Registries in Online Clusters
 
-In online (internet-connected) installations, you can optionally use a local private image registry. You can also disable the connection or remove the registry settings if needed.
+In online (internet-connected) installations, users can optionally use a local private image registry.
 
 To configure private registry settings in an online cluster:
 

docs/enterprise/installing-general-requirements.mdx

@@ -260,7 +260,7 @@ After manually creating these RBAC resources, the user must include both the `--
 
 A private image registry is required for air gap installations with KOTS in existing clusters. You provide the credentials for a compatible private registry during installation. You can also optionally configure a local private image registry for use with installations in online (internet-connected) environments.
 
-Private registry settings can be changed at any time. For more information, see [Configuring Local Image Registries](image-registry-settings).
+Private registry settings can be changed at any time. For more information, see [Configure Local Image Registries in the Admin Console](image-registry-settings).
 
 KOTS has been tested for compatibility with the following registries:
 

docs/partials/helm/_helmchart-v2-configure-step.mdx

@@ -0,0 +1,7 @@
+For each Helm chart in the release, open the corresponding KOTS HelmChart custom resource. In the HelmChart custom resource, do the following:
+   1. Update `apiVersion` to `kots.io/v1beta2`.
+   1. Rewrite image names to use the Replicated proxy registry and inject the image pull secret for the proxy registry. See [HelmChart v2](/vendor/private-images-kots#helmchart-v2) in _Use the Proxy Registry with Replicated Installers_.
+   1. Configure the `builder` key to allow your users to push images to their own local registries. See [Package Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles) and [builder](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_.
+   1. Configure the `optionalValues` key to rewrite image names for your application and the Replicated SDK to the user's local image registry if a local registry was configured. See [Rewrite Image Names with HelmChart v2 for Local Registries](/vendor/helmchart-local-registries).
+   1. Add a pull secret for any Docker Hub images that could be rate limited. See [Configure Local Image Registries in the Admin Console](/enterprise/image-registry-settings).
+   1. (KOTS Existing Cluster and kURL Installations Only) Add the `kots.io/backup: velero` and `kots.io/app-slug: APP_SLUG` backup labels to your resources to support backup and restore with the KOTS snapshots feature. See [Configure Snapshots](/vendor/snapshots-configuring-backups).

docs/partials/helm/_replicated-deprecated.mdx

@@ -1 +1 @@
-The HelmChart custom resource `apiVersion: kots.io/v1beta1` is deprecated. For installations with Replicated KOTS v1.99.0 and later, use the HelmChart custom resource with `apiVersion: kots.io/v1beta2` instead. See [HelmChart v2](/reference/custom-resource-helmchart-v2) and [Confguring the HelmChart Custom Resource v2](/vendor/helm-native-v2-using).
+The HelmChart custom resource `apiVersion: kots.io/v1beta1` is deprecated. For installations with Replicated KOTS v1.99.0 and later, use the HelmChart custom resource with `apiVersion: kots.io/v1beta2` instead. See [HelmChart v2](/reference/custom-resource-helmchart-v2).

docs/partials/proxy-service/_step-additional-ns.mdx

@@ -0,0 +1 @@
+If you are deploying Pods to namespaces other than the application namespace, add the namespace to the `additionalNamespaces` attribute of the KOTS Application custom resource. This ensures that KOTS can provision the `imagePullSecret` in the namespace to allow the Pod to pull the image. For instructions, see [Define Additional Namespaces](operator-defining-additional-namespaces).

docs/partials/proxy-service/_step-inject-pull-secret.mdx

@@ -0,0 +1,42 @@
+In the HelmChart v2 custom resource, configure the `values` key to inject the Replicated image pull secret into your Helm values. This provides authentication for the proxy registry. Use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to get the pull secret name.
+
+    <details>
+    <summary>What is the Replicated image pull secret?</summary>
+    <p>During application deployment, KOTS automatically creates an `imagePullSecret` with `type: kubernetes.io/dockerconfigjson` that is based on the customer license. This secret is used to authenticate with the proxy registry and grant proxy access to private images. 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.</p>
+    </details>
+
+    **Example**:
+
+    ```yaml
+    # kots.io/v1beta2 HelmChart custom resource
+
+    apiVersion: kots.io/v1beta2
+    kind: HelmChart
+    metadata:
+      name: samplechart
+    spec:
+      values:
+        image: 
+          # Get the pull secret name with ImagePullSecretName
+          pullSecrets:
+            - name: '{{repl ImagePullSecretName }}'
+    ```
+    Ensure that you provide this pull secret in any Pod definitions that reference images to be pulled through the proxy registry.
+
+    **Example**:
+
+    ```yaml
+    apiVersion: v1
+    kind: Pod
+    metadata:
+      name: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: {{ .Values.image.registry }}/{{ .Values.image.repository }}
+      # Access the value to provide the KOTS pull secret
+      {{- with .Values.image.pullSecrets }}
+      imagePullSecrets:
+      {{- toYaml . | nindent 2 }}
+      {{- end }}
+    ```

docs/partials/proxy-service/_step-rewrite-helm-values.mdx

@@ -0,0 +1,34 @@
+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
+    ```
+
+  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 }}
+    ```

docs/reference/custom-resource-helmchart-v2.mdx

@@ -101,7 +101,7 @@ The `builder` key is required for the following use cases:
 
 * To support online installations that use a local private registry, the `builder` field renders the Helm chart with all of the necessary images so that KOTS knows where to pull the images.
 
-  You cannot prevent customers from configuring a local private registry in the Admin Console. If you think any of your customers will use a local private registry, you should use the `builder` key. For more information, see [Configuring Local Image Registries](/enterprise/image-registry-settings).
+  You cannot prevent customers from configuring a local private registry in the Admin Console. If you think any of your customers will use a local private registry, you should use the `builder` key. For more information, see [Configure Local Image Registries in the Admin Console](/enterprise/image-registry-settings).
 
 <HelmBuilderRequirements/>
 

docs/vendor/embedded-disaster-recovery.mdx

@@ -123,8 +123,7 @@ To configure Velero Backup and Restore custom resources for Embedded Cluster dis
                     registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}'
                     repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/quay.io/my-org" }}/nginx'
                     tag: 1.24-alpine
-      ``` 
-      For more information about how to rewrite image names using the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions, including additional examples, see [Task 1: Rewrite Image Names](helm-native-v2-using#rewrite-image-names) in _Configuring the HelmChart v2 Custom Resource_.
+      ```
 
 1. If you support air gap installations, add any images that are referenced in your Backup and Restore resources to the `additionalImages` field of the KOTS Application custom resource. This ensures that the images are included in the air gap bundle for the release so they can be used during the backup and restore process in environments with limited or no outbound internet access. For more information, see [additionalImages](/reference/custom-resource-application#additionalimages) in _Application_.
 

docs/vendor/helm-image-registry.mdx

@@ -1,5 +1,6 @@
 import StepCreds from "../partials/proxy-service/_step-creds.mdx"
 import StepCustomDomain from "../partials/proxy-service/_step-custom-domain.mdx"
+import RewriteHelmValues from "../partials/proxy-service/_step-rewrite-helm-values.mdx"
 
 # Use the Proxy Registry with Helm Installations
 
@@ -19,40 +20,7 @@ To use the Replicated proxy registry for applications installed with Helm:
 
 1. <StepCustomDomain/>
 
-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. <RewriteHelmValues/>
 
 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.