edits

paigecalvert · paigecalvert · commit e1f85c6356b8 · 2025-02-19T17:28:11.000-07:00
diff --git a/docs/vendor/helm-v2-migrate.md b/docs/vendor/helm-v2-migrate.md
@@ -8,37 +8,33 @@ For additional support migrating existing installations to HelmChart v2, reach o
 
 ## Migrate to HelmChart v2
 
-### Requirement
+### Requirements
 
-The HelmChart v2 custom resource is supported for installations that use KOTS v1.99.0 or later. If any of your customers are running a version of KOTS earlier than v1.99.0, see [Support Customers on KOTS Versions Earlier Than v1.99.0](#support-both-v1-v2) below for more information about how to support both HelmChart v1 and HelmChart v2 installations from the same release.
+* The HelmChart v2 custom resource is supported with KOTS v1.99.0 and later. If any of your customers are running a version of KOTS earlier than v1.99.0, see [Support Customers on KOTS Versions Earlier Than v1.99.0](#support-both-v1-v2) below for more information about how to support both HelmChart v1 and HelmChart v2 installations from the same release.
+
+* The Helm `--take-ownership` flag is supported with KOTS v1.124.0 and later.
+
+* The `kots.io/keep` annotation is supported with KOTS v1.122.0 and later.
 
 ### Migrate From HelmChart v1 with `useHelmInstall: true`
 
 To migrate existing installations from HelmChart v1 with `useHelmInstall: true` to HelmChart v2:
 
-1. In a new release, for each HelmChart custom resource in the release, update the `apiVersion` to `kots.io/v1beta2`:
-
-     ```yaml
-     # Set apiVersion to kots.io/v1beta2
-     apiVersion: kots.io/v1beta2
-     kind: HelmChart
-     metadata:
-       name: samplechart
-     spec:
+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. Configure the HelmChart custom resource to rewrite images, inject image pull secrets, and add backup labels. See [Configuring the HelmChart Custom Resource v2](helm-native-v2-using).
+1. Configure each HelmChart custom resource in the release to update `apiVersion` to `kots.io/v1beta2`, rewrite images, inject image pull secrets, and add backup labels. See [Configuring the HelmChart Custom Resource v2](helm-native-v2-using).
 
-1. Promote the release to channel that your team uses for testing.
+1. Promote the release to an internal-only channel that your team uses for testing.
 
-1. Access a development environment where there is an instance of your application that was deployed with KOTS HelmChart v1 with `useHelmInstall: true`. In the development environment, log in to the Admin Console and confirm that you can upgrade to the new HelmChart v2 release.
+1. In your development environment, log in to the Admin Console and confirm that you can upgrade to the new HelmChart v2 release.
 
-1. When you are ready, promote the release to one or more of your customer-facing channels.
+1. When you are done testing, promote the release to one or more of your customer-facing channels. Customers can follow the standard upgrade process in the Admin Console to update their instance.
 
 ### Migrate From HelmChart v1 with `useHelmInstall: false`
 
-This section describes how to migrate existing HelmChart v1 installations with `useHelmInstall: false`. These migration steps ensure that KOTS does not uninstall any resources that were previously deployed without Helm and that Helm can take ownership of these resources.
+This section describes how to migrate existing HelmChart v1 installations with `useHelmInstall: false`. These migration steps ensure that KOTS does not uninstall any resources that were previously deployed without Helm and that Helm takes ownership of these existing resources.
 
 To migrate existing installations from HelmChart v1 and `useHelmInstall: false` to HelmChart v2:
 
@@ -55,27 +51,13 @@ To migrate existing installations from HelmChart v1 and `useHelmInstall: false`
          metadata:
            name: samplechart
          spec:
-            helmUpgradeFlags:
-              - --take-ownership
+           helmUpgradeFlags:
+             - --take-ownership
          ```   
 
-         When the `--take-ownership` flag is enabled, Helm automatically takes ownership of existing resources in the cluster during upgrade.
+         When the `--take-ownership` flag is enabled, Helm automatically takes ownership of resources that were previously deployed without Helm during upgrade. The Helm `--take-ownership` flag requires KOTS 1.122.0 or later.
 
-     1. (Recommended) In the KOTS Application custom resource, set `minKotsVersion: 1.122.0`. The Helm `--take-ownership` flag is not supported on versions of KOTS earlier than 1.122.0.
-
-     1. For each HelmChart custom resource in the release, update the `apiVersion` to `kots.io/v1beta2`:
-
-         ```yaml
-         # Set apiVersion to kots.io/v1beta2
-         apiVersion: kots.io/v1beta2
-         kind: HelmChart
-         metadata:
-           name: samplechart
-         spec:
-
-         ```
-
-     1. Configure the HelmChart custom resource to rewrite images, inject pull secrets, and add backup labels. See [Configuring the HelmChart Custom Resource v2](helm-native-v2-using). 
+     1. Configure each HelmChart custom resource in the release to update `apiVersion` to `kots.io/v1beta2`, rewrite images, inject image pull secrets, and add backup labels. See [Configuring the HelmChart Custom Resource v2](helm-native-v2-using).
 
      1. Promote the release to an internal-only channel that your team uses for testing.
 
@@ -87,7 +69,7 @@ To migrate existing installations from HelmChart v1 and `useHelmInstall: false`
 
 ### Migrate From Standard Kubernetes Manifests
 
-This section describes how to migrate existing KOTS installations of applications that were previously packaged as standard Kubernetes manifests and are now packaged as one or more Helm charts. These migration steps ensure that KOTS does not uninstall any resources that were adopted into Helm charts and that Helm can take ownership of resources that were previously deployed without Helm.
+This section describes how to migrate existing KOTS installations of applications that were previously packaged as standard Kubernetes manifests and are now packaged as one or more Helm charts. This migration path involves performing two upgrades to ensure that KOTS does not uninstall any resources that were adopted into Helm charts, and that Helm can take ownership of resources that were previously deployed without Helm.
 
 To migrate applications that were previously packaged as standard Kubernetes manifests:
 
@@ -114,16 +96,18 @@ To migrate applications that were previously packaged as standard Kubernetes man
               - --take-ownership
          ```   
 
-         When the `--take-ownership` flag is enabled, Helm automatically takes ownership of existing resources in the cluster during upgrade.  
-
-     1. (Recommended) In the KOTS Application custom resource, set `minKotsVersion: 1.122.0`. The Helm `--take-ownership` flag is not supported on versions of KOTS earlier than 1.122.0.
+         When the `--take-ownership` flag is enabled, Helm automatically takes ownership of resources that were previously deployed without Helm during upgrade.
 
      1. Save the release.
 
 1. Test the upgrade process:
 
     1. Promote the first release to an internal-only channel that your team uses for testing.
 
+         :::note
+         Replicated recommends that you mark the release as required by enabling **Prevent this release from being skipped during upgrades** because customers must upgrade to this release first before they can upgrade to the release that migrates their installation to HelmChart v2.
+         :::
+
     1. In a development environment, install the release.
 
     1. Promote the second release to the same channel.
@@ -133,7 +117,7 @@ To migrate applications that were previously packaged as standard Kubernetes man
 1. After you are done testing the migration process, promote the first release containing your application manifests to one or more customer-facing channels.
   
      :::note
-     Replicated recommends that you mark the release as required because customers must upgrade to this release first before they can upgrade to the release that migrates their installation to HelmChart v2.
+     Replicated recommends that you mark the release as required by enabling **Prevent this release from being skipped during upgrades** because customers must upgrade to this release first before they can upgrade to the release that migrates their installation to HelmChart v2.
      :::
 
 1. Promote the second release containing your application Helm chart to the same channels.
@@ -148,31 +132,31 @@ To support both installation methods from the same release, include both version
 
 When you include both versions of the HelmChart custom resource for a Helm chart, installations with KOTS v1.98.0 or earlier use the v1 method, while installations with KOTS v1.99.0 or later use v2.
 
-After all customers are using KOTS v1.99.0 or later, you can remove the HelmChart `kots.io/v1beta1` custom resources so that all customers are using the HelmChart v2 method.
+After all customers are using KOTS v1.99.0 or later, you can remove the HelmChart v1 custom resources so that all customers are using the HelmChart v2 method.
 
 ## HelmChart v2 Migration FAQs
 
 This section includes FAQs related to migrating existing installations to the KOTS HelmChart v2 method.
 
 ### Which migration scenarios require the `kots.io/keep` annotation?
 
-When applied to a resource in a release, the `kots.io/keep` annotation prevents the given resource from being uninstalled. The `kots.io/keep` annotation can be used to prevent KOTS from deleting resources that you intend to adopt into Helm charts, or that were previously deployed with `kubectl apply` and will be deployed with Helm using KOTS HelmChart v2.
+When applied to a resource in a release, the `kots.io/keep` annotation prevents the given resource from being uninstalled. The `kots.io/keep` annotation can be used to prevent KOTS from deleting resources that were either adopted into Helm charts, or that were previously deployed without Helm.
 
-To prevent existing resources from being uninstalled, the `kots.io/keep` annotation is required for the following types of migrations:
+To prevent existing resources from being uninstalled during upgrade, the `kots.io/keep` annotation is required for the following types of migrations:
   * Applications previously packaged as Kubernetes manifests migrating to HelmChart v2
   * HelmChart v1 with `useHelmInstall: false` migrating to HelmChart v2
 
-`kots.io/keep` is _not_ needed when migrating from HelmChart v1 with `useHelmInstall: true` to HelmChart v1beta2. This is because the HelmChart v1 with `useHelmInstall: true` method deploys the given application with Helm, rather than using `kubectl apply`.
+`kots.io/keep` is _not_ needed when migrating from HelmChart v1 with `useHelmInstall: true` to HelmChart v2.
 
 ### Which migration scenarios require the `--take-ownership` flag?
 
-When the `--take-ownership` flag is enabled, Helm automatically takes ownership of existing resources by automatically adding the required annotations.
+When the `--take-ownership` flag is enabled, Helm automatically takes ownership of resources that were previously deployed to the cluster without Helm.
 
 The `--take-ownership` flag is required for the following types of migrations:
   * Applications previously packaged as Kubernetes manifests migrating to HelmChart v2
   * HelmChart v1 with `useHelmInstall: false` migrating to HelmChart v2
 
-`--take-ownership` is _not_ needed when migrating from HelmChart v1 with `useHelmInstall: true` to HelmChart v1beta2. This is because the HelmChart v1 with `useHelmInstall: true` method deploys the given application with Helm, rather than using `kubectl apply`.
+`--take-ownership` is _not_ needed when migrating from HelmChart v1 with `useHelmInstall: true` to HelmChart v2.
 
 ### What is the difference between HelmChart v1 with `useHelmInstall: false` and `useHelmInstall: true`?
 
