edits

paigecalvert · paigecalvert · commit 139920224a45 · 2025-02-26T11:10:55.000-07:00
diff --git a/docs/vendor/helm-v2-migrate.md b/docs/vendor/helm-v2-migrate.md
@@ -34,7 +34,7 @@ This section describes how to migrate existing HelmChart v1 installations with `
 
 To migrate existing installations from HelmChart v1 and `useHelmInstall: false` to HelmChart v2:
 
-1. Create a new release containing your application files.
+1. Create a new release containing your application files:
 
    1. In the release, for any resources defined in Kubernetes manifests or in your Helm `templates` that were previously installed with HelmChart v1 and `useHelmInstall: false`, add the `kots.io/keep` annotation. The `kots.io/keep` annotation prevents KOTS from uninstalling these resources when upgrading using the HelmChart v2 method.
 
@@ -45,6 +45,7 @@ To migrate existing installations from HelmChart v1 and `useHelmInstall: false`
        kind: Statefulset
        metadata:
          name: postgresql
+         # Add the kots.io/keep annotation
          annotations:
            kots.io/keep: "true"
        ```
@@ -55,7 +56,7 @@ To migrate existing installations from HelmChart v1 and `useHelmInstall: false`
 
    1. For each Helm chart in the release, configure the corresponding HelmChart custom resource 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. In the KOTS HelmChart v2 custom resource, under the `helmUpgradeFlags` field, add the `--take-ownership` flag:
+   1. In the HelmChart custom resource, under the `helmUpgradeFlags` field, add the `--take-ownership` flag:
 
       ```yaml
       # HelmChart v1 beta2
@@ -82,11 +83,13 @@ To migrate existing installations from HelmChart v1 and `useHelmInstall: false`
    
    1. In your development environment, access the Admin Console to upgrade to the second release.
 
-1. When you are done testing, promote the first release to one or more of your customer-facing channels. Replicated recommends that you mark the release as required by enabling **Prevent this release from being skipped during upgrades**.
+1. When you are done testing, promote the first release to one or more of your customer-facing channels. Replicated recommends that you mark the release as required by enabling **Prevent this release from being skipped during upgrades**. For more information about required releases, see [Properties](/vendor/releases-about#properties) in _About Channels and Releases_.
+
+1. Promote the second release to the same customer-facing channel(s). Replicated recommends that you mark the release as required by enabling **Prevent this release from being skipped during upgrades**.
 
-1. Promote the second release to the customer-facing channels. Replicated recommends that you mark the release as required by enabling **Prevent this release from being skipped during upgrades**.
+1. Instruct customers to migrate by first upgrading to the release where the `kots.io.keep` annotation is applied to your resources, then upgrading to the release with HelmChart v2.
 
-    Your customers can follow the standard upgrade process in the Admin Console to update their instance to the new version.
+1. (Recommended) In subsequent releases, remove the `helmUpgradeFlags` field (including the `--take-ownership` flag) from the HelmChart custom resource. This flag is only required during one upgrade to allow Helm to take ownership of your application resources.
 
 ### Migrate From Standard Kubernetes Manifests
 
@@ -98,58 +101,60 @@ To migrate applications that were previously packaged as standard Kubernetes man
 
    1. For each of the application manifests in the release, add the `kots.io/keep` annotation. The `kots.io/keep` annotation prevents KOTS from uninstalling resources that were previously installed without Helm when upgrading using the HelmChart v2 method.
 
-     **Example:**
- 
-     ```yaml
-     apiVersion: apps/v1
-     kind: Statefulset
-     metadata:
-       name: postgresql
-       annotations:
-         kots.io/keep: "true"
-     ```   
+      **Example:**
+  
+      ```yaml
+      apiVersion: apps/v1
+      kind: Statefulset
+      metadata:
+        name: postgresql
+        annotations:
+          kots.io/keep: "true"
+      ```   
 
    1. Save the release.
 
 1. Create another new release:
 
-     1. In the release, add your application Helm chart or charts. Remove the application manifests for resources that were adopted into the Helm chart(s).
+     1. In the release, add your application Helm chart(s). Remove the application manifests for resources that were adopted into the Helm chart(s).
 
-     1. For each Helm chart in the new release, configure the corresponding HelmChart custom resource 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. For each Helm chart in the release, add a corresponding KOTS HelmChart custom resource with `apiVersion` set to `kots.io/v1beta2`. Configure the resource to rewrite images, inject image pull secrets, and add backup labels. See [Configuring the HelmChart Custom Resource v2](helm-native-v2-using).
 
-     1. In the `helmUpgradeFlags` field of the Embedded Cluster Config, add the `--take-ownership` flag, as shown below:
+     1. In the HelmChart custom resource, under the `helmUpgradeFlags` field, add the `--take-ownership` flag:
 
-         ```yaml
-         # HelmChart v1 beta2
-         apiVersion: kots.io/v1beta2
-         kind: HelmChart
-         metadata:
-           name: samplechart
-         spec:
-            helmUpgradeFlags:
-              - --take-ownership
-         ```   
+        ```yaml
+        # HelmChart v1 beta2
+        apiVersion: kots.io/v1beta2
+        kind: HelmChart
+        metadata:
+          name: samplechart
+        spec:
+          helmUpgradeFlags:
+            - --take-ownership
+        ```   
 
-         When the `--take-ownership` flag is enabled, Helm automatically takes ownership of resources that were previously deployed without Helm during upgrade.
+        When the `--take-ownership` upgrade flag is enabled, Helm automatically takes ownership of resources that were previously deployed without Helm.
 
      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.
+1. Test the migration process:
 
-    1. In a development environment, install the release.
+   1. Promote the first release to an internal-only channel that your team uses for testing.
 
-    1. Promote the second release to the same channel.
+   1. In a development environment, install the first release.
 
-    1. In your development environment, upgrade to the second release to migrate the installation to HelmChart v2.
+   1. Promote the second release to the same channel.
+   
+   1. In your development environment, access the Admin Console to upgrade to the second release. Upgrading to the second release migrates the installation to HelmChart v2.
 
-1. After you are done testing the migration process, promote the first release containing your application manifests to one or more customer-facing channels. Mark the release as required by enabling **Prevent this release from being skipped during upgrades**.
+1. After you are done testing the migration process, promote the first release containing your application manifests with the `kots.io/keep` annotation to one or more customer-facing channels. Replicated recommends that you mark the release as required by enabling **Prevent this release from being skipped during upgrades**. For more information about required releases, see [Properties](/vendor/releases-about#properties) in _About Channels and Releases_.
 
-1. Promote the second release containing your application Helm chart to the same channels. Mark the release as required by enabling **Prevent this release from being skipped during upgrades**.
+1. Promote the second release containing your Helm chart(s) and the HelmChart v2 custom resource(s) to the same channels. Replicated recommends that you mark the release as required by enabling **Prevent this release from being skipped during upgrades**.
 
 1. Instruct customers to migrate by first upgrading to the release containing the standard manifests, then upgrading to the release packaged with Helm.
 
+1. (Recommended) In subsequent releases, remove the `helmUpgradeFlags` field (including the `--take-ownership` flag) from the HelmChart custom resource. This flag is only required during one upgrade to allow Helm to take ownership of your application resources.
+
 ## Support Customers on KOTS Versions Earlier Than v1.99.0 {#support-both-v1-v2}
 
 The HelmChart v2 installation method requires KOTS v1.99.0 or later. If you have existing customers that have not yet upgraded to KOTS v1.99.0 or later, Replicated recommends that you support both the HelmChart v2 and v1 installation methods from the same release until all installations are running KOTS v1.99.0 or later.
