Skip to content

Commit 77a4219

Browse files
paigecalvertpaigecalvert
authored
Merge pull request #3066 from replicatedhq/120396
Migrate existing installations to HelmChart v2
2 parents a804932 + 871d3a5 commit 77a4219

File tree

4 files changed

+202
-17
lines changed

4 files changed

+202
-17
lines changed

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ Released on January 24, 2025
6464
Support for Kubernetes: 1.29, 1.30, and 1.31
6565

6666
### New Features {#new-features-1-124-0}
67-
* 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:
67+
* 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:
6868

6969
```yaml
7070
# HelmChart v1 beta2
@@ -79,7 +79,7 @@ Support for Kubernetes: 1.29, 1.30, and 1.31
7979
8080
This flag allows Helm to take ownership of existing resources that were installed without Helm, like resources deployed with HelmChart v1beta1 and `useHelmInstall: false`.
8181

82-
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.
82+
For information about how to migrate an existing installation to KOTS HelmChart `v1beta2`, see [Migrating Existing Installations to HelmChart v2](/vendor/helm-v2-migrate).
8383

8484
## 1.123.1
8585

@@ -115,7 +115,7 @@ Released on December 12, 2024
115115
Support for Kubernetes: 1.29, 1.30, and 1.31
116116

117117
### New Features {#new-features-1-122-0}
118-
* 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.
118+
* 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).
119119

120120
## 1.121.2
121121

‎docs/vendor/helm-native-about.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,11 +46,11 @@ This section describes how KOTS uses the HelmChart custom resource to deploy Hel
4646

4747
<KotsHelmCrDescription/>
4848

49-
The HelmChart custom resource with `apiVersion: kots.io/v1beta2` is supported with KOTS v1.99.0 and later. For more information, see [About the HelmChart kots.io/v1beta2 Installation Method](#v2-install) below.
49+
The HelmChart custom resource with `apiVersion: kots.io/v1beta2` (HelmChart v2) is supported with KOTS v1.99.0 and later. For more information, see [About the HelmChart kots.io/v1beta2 Installation Method](#v2-install) below.
5050

5151
KOTS versions earlier than v1.99.0 can install Helm charts with `apiVersion: kots.io/v1beta1` of the HelmChart custom resource. The `kots.io/v1beta1` HelmChart custom resource is deprecated. For more information, see [Deprecated HelmChart kots.io/v1beta1 Installation Methods](#deprecated-helmchart-kotsiov1beta1-installation-methods) below.
5252

53-
### About the HelmChart kots.io/v1beta2 Installation Method {#v2-install}
53+
### About the HelmChart v2 Installation Method {#v2-install}
5454

5555
When you include a HelmChart custom resource with `apiVersion: kots.io/v1beta2` in a release, KOTS v1.99.0 or later does a Helm install or upgrade of the associated Helm chart directly.
5656

‎docs/vendor/helm-native-v2-using.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -364,8 +364,8 @@ The `kots.io/v1beta2` HelmChart custom resource has the following differences fr
364364
</tr>
365365
</table>
366366

367-
### Migrate Existing HelmChart v1 Installations to v2
367+
### Migrate Existing KOTS Installations to HelmChart v2
368368

369-
After you complete the tasks in this topic to configure the `kots.io/v1beta2` HelmChart custom resource, you can migrate any existing installations that were deployed with `kots.io/v1beta1` with `useHelmInstall: true` to use `kots.io/v1beta2` instead. For more information, see [Migrating Existing Installations to HelmChart v2](helm-v2-migrate).
369+
Existing KOTS installations can be migrated to use the KOTS HelmChart v2 method, without having to reinstall the application.
370370

371-
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.
371+
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).

‎docs/vendor/helm-v2-migrate.md‎

Lines changed: 194 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,204 @@
11
# Migrating Existing Installations to HelmChart v2
22

3-
This topic provides guidance for migrating existing installations that were deployed with the HelmChart custom resource `kots.io/v1beta1` with `useHelmInstall: true` to use `kots.io/v1beta2` instead.
3+
This topic describes how to migrate existing Replicated KOTS installations to the KOTS HelmChart `kots.io/v1beta2` (HelmChart v2) installation method, without having to reinstall the application. It also includes information about how to support both HelmChart v1 and HelmChart v2 installations from a single release, and lists frequently-asked questions (FAQs) related to migrating to HelmChart v2.
44

5-
## Overview
5+
## Migrate to HelmChart v2
66

7-
The HelmChart custom resource `kots.io/v1beta1` is deprecated and is not recommended for new installations. Existing installations that were installed with `kots.io/v1beta1` and `useHelmInstall: true` can be migrated to `kots.io/v1beta2` without needing to reinstall the application. For information about how to support installation with the `kots.io/v1beta2` HelmChart custom resource, including rewriting images, injecting pull secrets, and adding backup labels, see [Configuring the HelmChart Custom Resource v2](helm-native-v2-using).
7+
### Requirements
88

9-
### `useHelmInstall: false` Limitation
9+
* 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.
1010

11-
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.
11+
* The Helm `--take-ownership` flag is supported with KOTS v1.124.0 and later.
1212

13-
## How to Migrate Existing Installations
13+
* The `kots.io/keep` annotation is supported with KOTS v1.122.0 and later.
1414

15-
The HelmChart custom resource version `kots.io/v1beta2` is available only for installations that use KOTS v1.99.0 or later. To support existing users that have not yet upgraded to KOTS v1.99.0 or later, Replicated recommends that you include both a `kots.io/v1beta2` and a `kots.io/v1beta1` (with `useHelmInstall: true`) HelmChart custom resource for each Helm chart in your release. This allows you to support both installation methods from the same release.
15+
### Migrate From HelmChart v1 with `useHelmInstall: true`
1616

17-
When you include both versions in a single release for the same Helm chart, installations with KOTS v1.98.0 or earlier use `kots.io/v1beta1`. Installations with KOTS v1.99.0 or later use `kots.io/v1beta2`.
17+
To migrate existing installations from HelmChart v1 with `useHelmInstall: true` to HelmChart v2:
1818

19-
After all customer environments where the Helm chart was previously installed with `kots.io/v1beta1` and `useHelmInstall: true` are upgraded to KOTS v1.99.0 or later, you can remove version `kots.io/v1beta1` of the HelmChart custom resource from your releases.
19+
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.
20+
21+
1. Create a new release containing your application files.
22+
23+
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 [Configuring the HelmChart Custom Resource v2](helm-native-v2-using).
24+
25+
1. Promote the release to an internal-only channel that your team uses for testing.
26+
27+
1. In your development environment, log in to the Admin Console and confirm that you can upgrade to the new HelmChart v2 release.
28+
29+
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.
30+
31+
### Migrate From HelmChart v1 with `useHelmInstall: false`
32+
33+
This section describes how to migrate existing HelmChart v1 installations with `useHelmInstall: false`.
34+
35+
:::note
36+
When the `useHelmInstall` field is _not_ set in the HelmChart custom resource, `false` is the default value.
37+
:::
38+
39+
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.
40+
41+
To migrate existing installations from HelmChart v1 and `useHelmInstall: false` to HelmChart v2:
42+
43+
1. Create a new release containing your application files:
44+
45+
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.
46+
47+
**Example:**
48+
49+
```yaml
50+
apiVersion: apps/v1
51+
kind: Statefulset
52+
metadata:
53+
name: postgresql
54+
# Add the kots.io/keep annotation
55+
annotations:
56+
kots.io/keep: "true"
57+
```
58+
59+
1. Save the release.
60+
61+
1. Create another new release:
62+
63+
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 [Configuring the HelmChart Custom Resource v2](helm-native-v2-using).
64+
65+
1. In the HelmChart custom resource, under the `helmUpgradeFlags` field, add the `--take-ownership` flag:
66+
67+
```yaml
68+
# HelmChart v2
69+
apiVersion: kots.io/v1beta2
70+
kind: HelmChart
71+
metadata:
72+
name: samplechart
73+
spec:
74+
helmUpgradeFlags:
75+
- --take-ownership
76+
```
77+
78+
When the `--take-ownership` upgrade flag is enabled, Helm automatically takes ownership of resources that were previously deployed without Helm.
79+
80+
1. Save the release.
81+
82+
1. Test the migration process:
83+
84+
1. Promote the first release to an internal-only channel that your team uses for testing.
85+
86+
1. In a development environment, install the first release.
87+
88+
1. Promote the second release to the same channel.
89+
90+
1. In your development environment, access the Admin Console to upgrade to the second release.
91+
92+
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_.
93+
94+
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**.
95+
96+
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.
97+
98+
1. In subsequent releases, remove the `--take-ownership` flag from the `helmUpgradeFlags` field and remove the `kots.io/keep` annotation from resources in your Helm templates.
99+
100+
### Migrate From Standard Kubernetes Manifests
101+
102+
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.
103+
104+
To migrate applications that were previously packaged as standard Kubernetes manifests:
105+
106+
1. Create a new release containing the Kubernetes manifests for your application:
107+
108+
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.
109+
110+
**Example:**
111+
112+
```yaml
113+
apiVersion: apps/v1
114+
kind: Statefulset
115+
metadata:
116+
name: postgresql
117+
annotations:
118+
kots.io/keep: "true"
119+
```
120+
121+
1. Save the release.
122+
123+
1. Create another new release:
124+
125+
1. In the release, add your application Helm chart(s). Remove the application manifests for resources that were adopted into the Helm chart(s).
126+
127+
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).
128+
129+
1. In the HelmChart custom resource, under the `helmUpgradeFlags` field, add the `--take-ownership` flag:
130+
131+
```yaml
132+
# HelmChart v1 beta2
133+
apiVersion: kots.io/v1beta2
134+
kind: HelmChart
135+
metadata:
136+
name: samplechart
137+
spec:
138+
helmUpgradeFlags:
139+
- --take-ownership
140+
```
141+
142+
When the `--take-ownership` upgrade flag is enabled, Helm automatically takes ownership of resources that were previously deployed without Helm.
143+
144+
1. Save the release.
145+
146+
1. Test the migration process:
147+
148+
1. Promote the first release to an internal-only channel that your team uses for testing.
149+
150+
1. In a development environment, install the first release.
151+
152+
1. Promote the second release to the same channel.
153+
154+
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.
155+
156+
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_.
157+
158+
1. Promote the second release containing your Helm chart(s) to the same channels. Replicated recommends that you mark the release as required by enabling **Prevent this release from being skipped during upgrades**.
159+
160+
1. Instruct customers to migrate by first upgrading to the release containing the standard manifests, then upgrading to the release packaged with Helm.
161+
162+
1. In subsequent releases, remove the `--take-ownership` flag from the `helmUpgradeFlags` field and remove the `kots.io/keep` annotation from resources in your Helm templates.
163+
164+
## Support Customers on KOTS Versions Earlier Than v1.99.0 {#support-both-v1-v2}
165+
166+
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.
167+
168+
To support both installation methods from the same release, include both versions of the HelmChart custom resource for each Helm chart in your application releases (HelmChart `kots.io/v1beta2` and HelmChart `kots.io/v1beta1` with `useHelmInstall: true`).
169+
170+
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.
171+
172+
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.
173+
174+
## HelmChart v2 Migration FAQs
175+
176+
This section includes FAQs related to migrating existing installations to the KOTS HelmChart v2 method.
177+
178+
### Which migration scenarios require the `kots.io/keep` annotation?
179+
180+
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 adopted into Helm charts or otherwise previously deployed without Helm.
181+
182+
To prevent existing resources from being uninstalled during upgrade, the `kots.io/keep` annotation is required for the following types of migrations:
183+
* Applications previously packaged as Kubernetes manifests migrating to HelmChart v2
184+
* HelmChart v1 with `useHelmInstall: false` migrating to HelmChart v2
185+
186+
`kots.io/keep` is _not_ needed when migrating from HelmChart v1 with `useHelmInstall: true` to HelmChart v2.
187+
188+
### Which migration scenarios require the `--take-ownership` flag?
189+
190+
When the `--take-ownership` flag is enabled, Helm automatically takes ownership of resources that were previously deployed to the cluster without Helm.
191+
192+
The `--take-ownership` flag is required for the following types of migrations:
193+
* Applications previously packaged as Kubernetes manifests migrating to HelmChart v2
194+
* HelmChart v1 with `useHelmInstall: false` migrating to HelmChart v2
195+
196+
`--take-ownership` is _not_ needed when migrating from HelmChart v1 with `useHelmInstall: true` to HelmChart v2.
197+
198+
### What is the difference between HelmChart v1 with `useHelmInstall: false` and `useHelmInstall: true`?
199+
200+
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 the HelmChart v1 with `useHelmInstall: true` and HelmChart v2 methods, where KOTS installs the application using Helm.
201+
202+
Because the HelmChart v1 with `useHelmInstall: false` method does not deploy resources with Helm, it is necessary to use the `kots.io/keep` annotation and the Helm `--take-ownership` flag when migrating to the HelmChart v2 installation method. These ensure that Helm can take ownership of existing resources and that the resources are not uninstalled during upgrade.
203+
204+
For more information about how KOTS deploys Helm charts, including information about the deprecated HelmChart v1 installation methods, see [About Distributing Helm Charts with KOTS](helm-native-about).

0 commit comments

Comments
 (0)