You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/vendor/helm-v2-migrate.md
+65-35Lines changed: 65 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,7 +20,7 @@ To migrate existing installations from HelmChart v1 with `useHelmInstall: true`
20
20
21
21
1. Create a new release containing your application files.
22
22
23
-
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).
23
+
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).
24
24
25
25
1. Promote the release to an internal-only channel that your team uses for testing.
26
26
@@ -30,36 +30,61 @@ To migrate existing installations from HelmChart v1 with `useHelmInstall: true`
30
30
31
31
### Migrate From HelmChart v1 with `useHelmInstall: false`
32
32
33
-
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.
33
+
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.
34
34
35
35
To migrate existing installations from HelmChart v1 and `useHelmInstall: false` to HelmChart v2:
36
36
37
-
1. Create a new release containing your application files:
38
-
39
-
1. Add the `kots.io/keep` annotation to any application resources defined in Kubernetes manifests or in your Helm `templates` that were previously installed with the HelmChart v1 with `useHelmInstall: false` installation method. The `kots.io/keep` annotation prevents KOTS from uninstalling these resources when upgrading using the HelmChart v2 method.
37
+
1. Create a new release containing your application files.
40
38
41
-
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).
39
+
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.
40
+
41
+
**Example:**
42
+
43
+
```yaml
44
+
apiVersion: apps/v1
45
+
kind: Statefulset
46
+
metadata:
47
+
name: postgresql
48
+
annotations:
49
+
kots.io/keep: "true"
50
+
```
51
+
52
+
1. Save the release.
42
53
43
-
1.In the `helmUpgradeFlags` field of the KOTS HelmChart v2 custom resource, add the `--take-ownership` flag, as shown below:
54
+
1. Create another new release:
44
55
45
-
```yaml
46
-
# HelmChart v1 beta2
47
-
apiVersion: kots.io/v1beta2
48
-
kind: HelmChart
49
-
metadata:
50
-
name: samplechart
51
-
spec:
52
-
helmUpgradeFlags:
53
-
- --take-ownership
54
-
```
56
+
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).
57
+
58
+
1. In the KOTS HelmChart v2 custom resource, under the `helmUpgradeFlags` field, add the `--take-ownership` flag:
59
+
60
+
```yaml
61
+
# HelmChart v1 beta2
62
+
apiVersion: kots.io/v1beta2
63
+
kind: HelmChart
64
+
metadata:
65
+
name: samplechart
66
+
spec:
67
+
helmUpgradeFlags:
68
+
- --take-ownership
69
+
```
70
+
71
+
When the `--take-ownership` upgrade flag is enabled, Helm automatically takes ownership of resources that were previously deployed without Helm.
72
+
73
+
1. Save the release
55
74
56
-
When the `--take-ownership` upgrade flag is enabled, Helm automatically takes ownership of resources that were previously deployed without Helm. The Helm `--take-ownership` flag requires KOTS 1.124.0 or later.
75
+
1. Test the migration process:
57
76
58
-
1. Promote the release to an internal-only channel that your team uses for testing.
77
+
1. Promote the first release to an internal-only channel that your team uses for testing.
59
78
60
-
1. In a development environment, install the release to test that you can upgrade to the new release successfully.
79
+
1. In a development environment, install the first release.
61
80
62
-
1. When you are done testing, promote the release to one or more of your customer-facing channels.
81
+
1. Promote the second release to the same channel.
82
+
83
+
1. In your development environment, access the Admin Console to upgrade to the second release.
84
+
85
+
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**.
86
+
87
+
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**.
63
88
64
89
Your customers can follow the standard upgrade process in the Admin Console to update their instance to the new version.
65
90
@@ -69,16 +94,29 @@ This section describes how to migrate existing KOTS installations of application
69
94
70
95
To migrate applications that were previously packaged as standard Kubernetes manifests:
71
96
72
-
1. Create a new release containing the Kubernetes manifests for your application.
97
+
1. Create a new release containing the Kubernetes manifests for your application:
98
+
99
+
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.
73
100
74
-
1. Add the `kots.io/keep` annotation to each of the application manifests in the release. The `kots.io/keep` annotation prevents KOTS from uninstalling resources that were previously installed without Helm when upgrading using the HelmChart v2 method.
101
+
**Example:**
102
+
103
+
```yaml
104
+
apiVersion: apps/v1
105
+
kind: Statefulset
106
+
metadata:
107
+
name: postgresql
108
+
annotations:
109
+
kots.io/keep: "true"
110
+
```
75
111
76
-
1. Save the release.
112
+
1. Save the release.
77
113
78
114
1. Create another new release:
79
115
80
116
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).
81
117
118
+
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).
119
+
82
120
1. In the `helmUpgradeFlags` field of the Embedded Cluster Config, add the `--take-ownership` flag, as shown below:
83
121
84
122
```yaml
@@ -100,25 +138,17 @@ To migrate applications that were previously packaged as standard Kubernetes man
100
138
101
139
1. Promote the first release to an internal-only channel that your team uses for testing.
102
140
103
-
:::note
104
-
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.
105
-
:::
106
-
107
141
1. In a development environment, install the release.
108
142
109
143
1. Promote the second release to the same channel.
110
144
111
145
1. In your development environment, upgrade to the second release to migrate the installation to HelmChart v2.
112
146
113
-
1. After you are done testing the migration process, promote the first release containing your application manifests to one or more customer-facing channels.
114
-
115
-
:::note
116
-
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.
117
-
:::
147
+
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**.
118
148
119
-
1. Promote the second release containing your application Helm chart to the same channels.
149
+
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**.
120
150
121
-
1. Instruct customers to migrate by first upgrading to the release containing the standard manifests, then upgrading to the release packaged with Helm second.
151
+
1. Instruct customers to migrate by first upgrading to the release containing the standard manifests, then upgrading to the release packaged with Helm.
122
152
123
153
## Support Customers on KOTS Versions Earlier Than v1.99.0 {#support-both-v1-v2}
0 commit comments