Update helmchart v2 workflow

docs/vendor/helm-native-about.mdx

@@ -109,15 +109,59 @@ When installing an application that includes one or more Helm charts, KOTS alway
 
 For information about how to set the deployment order for Helm charts with KOTS, see [Orchestrate Resource Deployment](/vendor/orchestrating-resource-deployment).
 
-## Deprecated HelmChart kots.io/v1beta1 Installation Methods
+## Comparison to HelmChart v1
+
+### HelmChart v1 and v2 Differences
+
+To support the use of local registries with version `kots.io/v1beta2` of the HelmChart custom resource, provide the necessary values in the builder field to render the Helm chart with all of the necessary images so that KOTS knows where to pull the images from to push them into the local registry.
+
+For more information about how to configure the `builder` key, see [Packaging Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles) and [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_.
+
+The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`:
+
+<table>
+  <tr>
+    <th>HelmChart v1beta2</th>
+    <th>HelmChart v1beta1</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>apiVersion: kots.io/v1beta2</code></td>
+    <td><code>apiVersion: kots.io/v1beta1</code></td>
+    <td><code>apiVersion</code> is updated to <code>kots.io/v1beta2</code></td>
+  </tr>
+  <tr>
+    <td><code>releaseName</code></td>
+    <td><code>chart.releaseName</code></td>
+    <td><code>releaseName</code> is a top level field under <code>spec</code></td>
+  </tr>
+  <tr>
+    <td>N/A</td>
+    <td><code>helmVersion</code></td>
+    <td><code>helmVersion</code> field is removed</td>
+  </tr>
+  <tr>
+    <td>N/A</td>
+    <td><code>useHelmInstall</code></td>
+    <td><code>useHelmInstall</code> field is removed</td>
+  </tr>
+</table>
+
+### About Migrating Existing KOTS Installations to HelmChart v2
+
+Existing KOTS installations can be migrated to use the KOTS HelmChart v2 method, without having to reinstall the application.
+
+There are different steps for migrating to HelmChart v2 depending on the application deployment method used previously. For more information, see [Migrating Existing Installations to HelmChart v2](helm-v2-migrate).
+
+### Additional Information About HelmChart v1
 
 This section describes the deprecated Helm chart installation methods that use the HelmChart custom resource `apiVersion: kots.io/v1beta1`.
 
 :::important
 <Deprecated/>
 :::
 
-### useHelmInstall: true {#v1beta1}
+#### useHelmInstall: true {#v1beta1}
 
 :::note
 This method was previously referred to as _Native Helm_.
@@ -208,7 +252,7 @@ To deploy Helm charts with version `kots.io/v1beta1` of the HelmChart custom res
 
    Finally, KOTS runs `helm upgrade -i <release-name> <chart> --timeout 3600s -n <namespace>`. The Helm binary processes hooks and weights, applies manifests to the Kubernetes cluster, and saves a release secret similar to `sh.helm.release.v1.chart-name.v1`. Helm uses this secret to track upgrades and rollbacks of applications.
 
-### useHelmInstall: false {#v1beta1-false}
+#### useHelmInstall: false {#v1beta1-false}
 
 :::note
 This method was previously referred to as _Replicated Helm_.
@@ -218,7 +262,7 @@ When you use version `kots.io/v1beta1` of HelmChart custom resource with `useHel
 
 The resulting deployment is comprised of standard Kubernetes manifests. Therefore, cluster operators can view the exact differences between what is currently deployed and what an update will deploy.
 
-### Limitations {#replicated-helm-limitations}
+### HelmChart v1 Limitations {#replicated-helm-limitations}
 
 This section lists the limitations for version `kots.io/v1beta1` of the HelmChart custom resource.
 #### kots.io/v1beta1 (useHelmInstall: true) Limitations

docs/vendor/helm-native-v2-using.mdx

@@ -0,0 +1,100 @@
+import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.mdx"
+
+# Rewrite Images to Local Registries with HelmChart
+
+This topic describes how to configure the Replicated KOTS HelmChart custom resource so that KOTS rewrites the images used by your application to the location of the image in the user's local image registry. The main use case for local image registries is air gap installations with Replicated KOTS in existing clusters.
+
+## Overview
+
+The HelmChart custom resource `optionalValues` key can be used to set values in the Helm chart `values.yaml` file when a given conditional statement evaluates to true. For more information, see [optionalValues](/reference/custom-resource-helmchart-v2#optionalvalues) in _HelmChart v2_.
+
+If you have customers that will push images to their own local image registry (such as customers performing air gap installations with KOTS in existing clusters), you can configure the HelmChart `optionalValues` key so that KOTS rewrites the images for your application to the location of the image in user's local image registry during deployment.
+
+## Prerequisite
+
+Before configuring the HelmChart custom resource to conditionally rewrite images to the user's local registry, you first need to configure the HelmChart `builder` key to support the use of local registries. For more information, see [Package Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles).
+
+## Rewrite Application Images
+
+To configure the HelmChart `optionalValues` key so that KOTS conditionally rewrites images to the user's local registry:
+
+1. In the HelmChart custom resource `optionalValues` key, use the following KOTS template functions:
+   * [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry)
+   * [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost)
+   * [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace)
+      <details>
+      <summary>What is the registry namespace?</summary>
+      <p>The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`.</p>
+      </details>
+
+   **Example:**
+
+    ```yaml
+    # KOTS HelmChart custom resource
+
+     apiVersion: kots.io/v1beta2
+     kind: HelmChart
+     metadata:
+       name: samplechart
+     spec:
+       optionalValues:
+         # Define the conditional statement in the when field
+         - when: 'repl{{ HasLocalRegistry }}'
+           values:
+             postgres:
+               image:
+                 registry: '{{repl LocalRegistryHost }}'
+                 repository: '{{repl LocalRegistryNamespace }}'/cloudnative-pg/cloudnative-pg
+    ```  
+1.      
+
+## Rewrite the Replicated SDK Image
+
+To configure the HelmChart `optionalValues` key so that KOTS conditionally rewrites the SDK image to the user's local registry:
+
+1. In the KOTS HelmChart custom resource, under the `optionalValues` key, rewrite the image for the Replicated SDK so that it can be accessed from the user's local registry, if a local registry was configured:
+
+    ```yaml
+       # KOTS HelmChart custom resource
+
+    apiVersion: kots.io/v1beta2
+    kind: HelmChart
+    metadata:
+      name: samplechart
+    spec:
+      optionalValues:
+        # Rewrite Replicated SDK image to local registry
+        - when: 'repl{{ HasLocalRegistry }}'
+          values:
+            replicated:
+              image:
+                registry: '{{repl LocalRegistryHost }}'
+                repository: '{{repl LocalRegistryNamespace }}/replicated-sdk'
+    ```
+
+## Add a Pull Secret for Rate-Limited Docker Hub Images {#docker-secret}
+
+Docker Hub enforces rate limits for Anonymous and Free users. For more information about Docker Hub rate limiting, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website.
+
+To avoid errors caused by reaching the rate limit, your users can run the `kots docker ensure-secret` command, which creates an `APP_SLUG-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). 
+
+To support the use of the `kots docker ensure-secret` command, add the `APP_SLUG-kotsadm-dockerhub` pull secret (where `APP_SLUG` is your application slug) to any Docker images that could be rate-limited.
+
+**Example:**
+
+```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
+```    

docs/vendor/helm-packaging-airgap-bundles.mdx

@@ -5,7 +5,7 @@ import AirGapBundle from "../partials/airgap/_airgap-bundle.mdx"
 
 # Package Air Gap Bundles for Helm Charts
 
-This topic describes how to package and build air gap bundles for releases that contain one or more Helm charts. This topic applies to applications deployed with Replicated KOTS.
+This topic describes how to package and build air gap bundles for releases that contain one or more Helm charts. This topic applies to applications deployed with a Replicated installer (Embedded Cluster, KOTS, or kURL).
 
 ## Overview
 

docs/vendor/helm-v2-migrate.md → docs/vendor/helm-v2-migrate.mdx

@@ -18,11 +18,15 @@ To migrate existing installations from HelmChart v1 with `useHelmInstall: true`
 
 1. In a development environment, install an application release using the KOTS HelmChart v1 with `useHelmInstall: true` method. You will use this installation to test the migration to HelmChart v2.
 
-1. Create a new release containing your application files.
+1. Update your Helm values file or files to rewrite image names to use the proxy registry.
 
-1. For each Helm chart in the release, find the corresponding HelmChart custom resource and update `apiVersion` to `kots.io/v1beta2`. Then update it to rewrite images, inject image pull secrets, and add backup labels. See [Configure the HelmChart Custom Resource v2](helm-native-v2-using).
+1. For each of your application's Helm charts, update the corresponding HelmChart custom resource:
+    1. Update `apiVersion` to `kots.io/v1beta2`
+    1. Update the `values` key to inject the KOTS image pull secret to provide authentication to the proxy registry
+    1. Update the `optionalValues` key to rewrite images to support local registries
+    1. Add backup labels to support the snapshots feature for KOTS existing cluster and kURL installations
 
-1. Promote the release to an internal-only channel that your team uses for testing.
+1. Create and promote a new release with your changes to an internal-only channel that your team uses for testing.
 
 1. In your development environment, log in to the Admin Console and confirm that you can upgrade to the new HelmChart v2 release.
 

docs/vendor/helmchart-v2-snapshots.mdx

@@ -0,0 +1,48 @@
+# Add Backup Labels for Snapshots with HelmChart v2
+
+This topic describes how to configure the Replicated KOTS HelmChart v2 custom resource to add labels to resources in your Helm chart that you want to be included in backups taken with the Replicated snapshots feature. The information in this topic applies to Replicated KOTS installations in existing clusters and Replicated kURL installations.
+
+:::note
+The Replicated snapshots feature for backup and restore is supported only for KOTS existing cluster and kURL installations. Snapshots are not supported for installations with Replicated Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx).
+:::
+
+## Overview
+
+The snapshots feature requires the following labels on all resources in your Helm chart that you want to be included in the backup:
+* `kots.io/backup: velero`
+* `kots.io/app-slug: APP_SLUG`, where `APP_SLUG` is the slug of your Replicated application.
+
+For more information about snapshots, see [Understanding Backup and Restore](snapshots-overview).
+
+## Add Backup Labels for Snapshots
+
+To support backup and restore with snapshots:
+
+1. In the HelmChart v2 custom resource for your Helm chart, under the `optionalValues` key, add a `when` statement that evaluates to true only when the customer license has the `isSnapshotSupported` entitlement. This ensures that the labels are only added to resources when the customer license supports snapshots. Then, add `values` that assign the following labels to the resources you want backed up:
+    * `kots.io/backup: velero`
+    * `kots.io/app-slug: APP_SLUG`, where `APP_SLUG` is the unique slug of your application. You can use the KOTS [LicenseFieldValue](/reference/template-functions-license-context#licensefieldvalue) function to get the application slug from the license.
+
+    ```yaml
+    # kots.io/v1beta2 HelmChart custom resource
+
+    apiVersion: kots.io/v1beta2
+    kind: HelmChart
+    metadata:
+      name: samplechart
+    spec:
+      optionalValues:
+      # add backup labels only if the license supports snapshots
+      - when: "repl{{ LicenseFieldValue `isSnapshotSupported` }}"
+        recursiveMerge: true
+        values:
+          mariadb:
+            commonLabels:
+              kots.io/backup: velero
+              # use the LicenseFieldValue function to get the app slug from the license
+              kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }}
+            podLabels:
+              kots.io/backup: velero
+              kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }}
+    ```
+
+1. Save and promote the release to the channel that you use for testing. Install in a development environment using KOTS or kURL to test your changes.    

docs/vendor/private-images-about.md

@@ -14,12 +14,12 @@ The following diagram demonstrates how the proxy registry pulls images from your
 
 [View a larger version of this image](/images/private-registry-diagram-large.png)
 
-## About Enabling the Proxy Registry
+## About Using the Proxy Registry
 
 The proxy registry requires read-only credentials to your private registry to access your application images. See [Connect to an External Registry](/vendor/packaging-private-images).
 
 After connecting your registry, the steps the enable the proxy registry vary depending on your application deployment method. For more information, see:
-* [Using the Proxy Registry with KOTS Installations](/vendor/private-images-kots)
+* [Using the Proxy Registry with Replicated Installers](/vendor/private-images-kots)
 * [Using the Proxy Registry with Helm Installations](/vendor/helm-image-registry)
 
 ## About Allowing Pull-Through Access of Public Images