edits

Author: paigecalvert

docs/release-notes/rn-app-manager.md

@@ -64,7 +64,7 @@ Released on January 24, 2025
 Support for Kubernetes: 1.29, 1.30, and 1.31
 
 ### New Features {#new-features-1-124-0}
-* You can migrate Helm charts that were installed with HelmChart v1beta1 and `useHelmInstall: false` to HelmChart v1beta2 by passing the `--take-ownership` flag to the `helmUpgradeFlags` field in HelmChart custom resource as shown below:
+* You can migrate Helm charts that were installed with HelmChart `v1beta1` and `useHelmInstall: false` to HelmChart `v1beta2` by passing the `--take-ownership` flag to the `helmUpgradeFlags` field in HelmChart custom resource as shown below:
 
    ```yaml
    # HelmChart v1 beta2
@@ -79,7 +79,7 @@ Support for Kubernetes: 1.29, 1.30, and 1.31
 
    This flag allows Helm to take ownership of existing resources that were installed without Helm, like resources deployed with HelmChart v1beta1 and `useHelmInstall: false`.
 
-   To migrate an existing installation from `kots.io/v1beta1` with `useHelmInstall: false` to `kots.io/v1beta2`, reach out to your Replicated account representative in Slack or over email.
+   For information about how to migrate an existing installation to KOTS HelmChart `v1beta2`, see [Migrating Existing Installations to HelmChart v2](/vendor/helm-v2-migrate). 
 
 ## 1.123.1
 
@@ -115,7 +115,7 @@ Released on December 12, 2024
 Support for Kubernetes: 1.29, 1.30, and 1.31
 
 ### New Features {#new-features-1-122-0}
-* Adds support for the `kots.io/keep` annotation, which prevents KOTS from deleting resources during an upgrade if the resource is no longer present in the new release.
+* Adds support for the `kots.io/keep` annotation, which prevents KOTS from deleting resources during an upgrade if the resource is no longer present in the new release. This annotation is useful when migrating existing KOTS installations to the KOTS HelmChart v2 installation method. For more information, see [Migrating Existing Installations to HelmChart v2](/vendor/helm-v2-migrate). 
 
 ## 1.121.2
 

docs/vendor/helm-v2-migrate.md

@@ -4,6 +4,8 @@ This topic describes how to migrate existing Replicated KOTS installations to th
 
 For more information about how KOTS deploys Helm charts, see [About Distributing Helm Charts with KOTS](helm-native-about).
 
+For additional support migrating existing installations to HelmChart v2, reach out to your Replicated account representative.
+
 ## Migrate to HelmChart v2
 
 There are different migrations paths depending on which of the following methods were used to install the application previously:
@@ -17,8 +19,6 @@ The HelmChart v2 custom resource is supported for installations that use KOTS v1
 
 ### Migrate From HelmChart v1 with `useHelmInstall: true`
 
-Your customers can follow the regular upgrade flow in the KOTS Admin Console to update their instance to the new version using HelmChart v2.
-
 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`:
@@ -43,19 +43,30 @@ To migrate existing installations from HelmChart v1 with `useHelmInstall: true`
 
 ### Migrate From HelmChart v1 with `useHelmInstall: false`
 
-With HelmChart v1 and `useHelmInstall: false`, KOTS renders the Helm templates and deploys them as standard Kubernetes manifests using `kubectl apply`. With HelmChart v2, KOTS does a Helm install or upgrade of the chart directly.
-
-When migrating to HelmChart v2 from HelmChart v1 and `useHelmInstall: false`, you can use the `kots.io/keep` annotation to ensure that KOTS does not delete any existing resources from the cluster. Additionally, the `--take-ownership` flag will be used to allow Helm to take ownership of existing 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 can take ownership of these resources.
 
 To migrate existing installations from HelmChart v1 and `useHelmInstall: false` to HelmChart v2:
 
 1. Create a new release containing your application files:
 
      1. Add the `kots.io/keep` annotation to any resources that were previously deployed with `kubectl apply`. This includes any resources packaged as standard Kubernetes manifests or in Helm `templates`. The `kots.io/keep` annotation prevents KOTS from uninstalling these resources when deploying the release with HelmChart v2.
 
-     1. In the Embedded Cluster Config, add the `--take-ownership` flag.
+     1. In the Embedded Cluster Config, add the `--take-ownership` flag to the `helmUpgradeFlags` field, as shown below:
+
+         ```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 existing resources in the cluster during upgrade.  
 
-     1. (Recommended) In the KOTS Application custom resource, set `minKotsVersion: 1.122.0` to ensure that the `--take-ownership` flag is supported.
+     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`:
 
@@ -71,17 +82,17 @@ To migrate existing installations from HelmChart v1 and `useHelmInstall: false`
 
      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. Promote the release to channel that your team uses for testing.
+     1. Save the release and promote to channel that your team uses for testing.
 
 1. Install the release in a development environment to test that you can upgrade to the new release successfully.
 
 1. After testing, promote the release to one or more of your customer-facing channels.
 
     Your customers can follow the regular upgrade flow in the Admin Console to update their instance to the new version using HelmChart `v1beta2`.
 
-### Migrate Installations Previously Distributed as Standard Manifests
+### Migrate From Standard Kubernetes Manifests
 
-For applications distributed through KOTS that were packaged as standard Kubernetes manifests and are now packaged as one or more Helm charts, migrating to HelmChart v2 requires adding the `kots.io/keep` annotation to any previously-deployed resources. This ensures that KOTS does not delete these existing resources from the cluster when deploying a new release using the KOTS HelmChart v2 method.
+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.
 
 To migrate applications that were previously packaged as standard Kubernetes manifests:
 
@@ -118,7 +129,7 @@ To migrate applications that were previously packaged as standard Kubernetes man
 
      1. Save the release.
 
-1. Test the upgrade flow:
+1. Test the upgrade and migration process:
 
     1. Promote the first release to an internal-only channel used for testing.
 
@@ -174,6 +185,7 @@ The `--take-ownership` flag is required for the following types of migrations:
 
 `--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`.
 
-### Where can I find more help?
+### Why is the migration path from HelmChart v1 with `useHelmInstall: false` different than HelmChart v1 with `useHelmInstall: true`?
+
+With HelmChart v1 and `useHelmInstall: false`, KOTS renders the Helm templates and deploys them as standard Kubernetes manifests using `kubectl apply`. This differs from both HelmChart v1 and `useHelmInstall: true` and HelmChart v2, where KOTS installs the release using Helm.
 
-For additional support migrating existing installations to HelmChart v2, reach out to your Replicated account representative.