Migrate existing installations to HelmChart v2 #3066
Conversation
replicated-ci
added
type::docs
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| 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). |
There was a problem hiding this comment.
^ added link to the migration topic
docs/vendor/helm-native-v2-using.md
Outdated
| Existing KOTS installations can be migrated to use the KOTS HelmChart v2 method, without having to reinstall the application. | ||
|
|
||
| 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. | ||
| 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). |
There was a problem hiding this comment.
^ Replaced "reach out to your rep" with a link to the migration steps
docs/vendor/helm-v2-migrate.md
Outdated
|
|
||
| :::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. | ||
| ::: |
There was a problem hiding this comment.
^ recommend using required releases
There was a problem hiding this comment.
i don't think the second one needs to be required, unless they're going to remove the --take-ownership flag in a later release. it would need to be required if only this version has --take-ownership applied. which could be a good idea.
There was a problem hiding this comment.
The workflow I was trying to capture was testing the first (required) release, then promoting that same release to a customer-facing channel and again marking it as required.
But that said, the second release does have the --take-ownership flag...so it sounds like maybe it could be helpful to actually mark both the first and second releases are required?
docs/vendor/helm-v2-migrate.md
Outdated
|
|
||
| ### Where can I find additional help migrating existing installations to HelmChart v2? | ||
|
|
||
| For additional support migrating existing installations to HelmChart v2, Replicated recommends that you post your question in the [Replicated Community](https://community.replicated.com/) site. You can also reach out to your Replicated account representative. |
There was a problem hiding this comment.
^ post on community or reach out to your rep if you need help
docs/vendor/helm-v2-migrate.md
Outdated
|
|
||
| 1. Create a new release containing your application files: | ||
|
|
||
| 1. Add the `kots.io/keep` annotation to any resources that were previously installed with `kubectl apply`, including resources defined in Kubernetes manifests or in your Helm `templates`. The `kots.io/keep` annotation prevents KOTS from uninstalling resources that were previously installed without Helm when upgrading using the HelmChart v2 method. |
There was a problem hiding this comment.
Customers might not realize that v1 false uses kubectl apply. from their pov, they think it's a helm chart. so i wonder if we should make that clearer here. i might read this and say, well i had a helm chart, so no resources were applied with kubectl. but in reality, everything in the chart was kubectl applied.
docs/vendor/helm-v2-migrate.md
Outdated
|
|
||
| 1. Add the `kots.io/keep` annotation to any resources that were previously installed with `kubectl apply`, including resources defined in Kubernetes manifests or in your Helm `templates`. The `kots.io/keep` annotation prevents KOTS from uninstalling resources that were previously installed without Helm when upgrading using the HelmChart v2 method. | ||
|
|
||
| 1. In the `helmUpgradeFlags` field of the Embedded Cluster Config, add the `--take-ownership` flag, as shown below: |
There was a problem hiding this comment.
oops good catch
docs/vendor/helm-v2-migrate.md
Outdated
|
|
||
| 1. In a development environment, install the release to test that you can upgrade to the new release successfully. | ||
|
|
||
| 1. When you are done testing, promote the release to one or more of your customer-facing channels. |
There was a problem hiding this comment.
would you want to remove the keep annotation in a subsequent release though? I'm not sure if it matters or if @nvanthao tested it.
docs/vendor/helm-v2-migrate.md
Outdated
|
|
||
| :::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. | ||
| ::: |
There was a problem hiding this comment.
i don't think the second one needs to be required, unless they're going to remove the --take-ownership flag in a later release. it would need to be required if only this version has --take-ownership applied. which could be a good idea.
docs/vendor/helm-v2-migrate.md
Outdated
|
|
||
| ### 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 were either adopted into Helm charts, or that were previously deployed without Helm. |
There was a problem hiding this comment.
@nvanthao does this annotation work if you put it on a resource in a Helm chart, or does it only work for manifests in a release?
docs/vendor/helm-v2-migrate.md
Outdated
|
|
||
| 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. | ||
|
|
||
| 1. 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. |
There was a problem hiding this comment.
^ added step to remove the flag for later releases since it's not needed
There was a problem hiding this comment.
I'd just say to remove the take ownership flag, since they could be specifying other helm upgrade flags that they want to keep
There was a problem hiding this comment.
If I'm thinking of this correctly, they should also remove the keep annotation from the templates. Since this is the same chart, the annotation would be there, and we don't want that in the future (though I don't think KOTS will actually do anything about it anyway since it's in a Helm chart). But for cleanup purposes, that might be best.
docs/vendor/helm-v2-migrate.md
Outdated
|
|
||
| 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. | ||
|
|
||
| 1. 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. |
There was a problem hiding this comment.
I'd just say to remove the take ownership flag, since they could be specifying other helm upgrade flags that they want to keep
docs/vendor/helm-v2-migrate.md
Outdated
|
|
||
| 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. | ||
|
|
||
| 1. 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. |
There was a problem hiding this comment.
If I'm thinking of this correctly, they should also remove the keep annotation from the templates. Since this is the same chart, the annotation would be there, and we don't want that in the future (though I don't think KOTS will actually do anything about it anyway since it's in a Helm chart). But for cleanup purposes, that might be best.
Co-authored-by: Alex Parker <[email protected]>
https://deploy-preview-3066--replicated-docs.netlify.app/vendor/helm-v2-migrate