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-native-v2-using.md
+72-56Lines changed: 72 additions & 56 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,49 +2,58 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.md
2
2
3
3
# Support Installations with HelmChart v2
4
4
5
-
This topic describes how to configure your application to support installations with the Replicated HelmChart custom resource version `kots.io/v1beta2` (HelmChart v2).
5
+
This topic describes how to configure a release to support installations with the Replicated HelmChart custom resource version `kots.io/v1beta2` (HelmChart v2). For more information about HelmChart v2, see [About Distributing Helm Chart with KOTS](/vendor/helm-native-about).
6
6
7
-
## Prerequisite
7
+
## Configure a Release to Support HelmChart v2 Installations
8
8
9
-
For each Helm chart in your release, update all image references in your Helm values to use the domain of the Replicated proxy registry. See [Configure Your Application to Use the Proxy Registry](/vendor/private-images-kots) in _Use the Proxy Registry with Replicated Installers_.
9
+
To configure a releaseto support installations with HelmChart v2:
10
10
11
-
## Configure HelmChart v2
11
+
1. For each Helm chart used by your application, update all image references in the Helm values to use the domain of the Replicated proxy registry. See [Configure Your Application to Use the Proxy Registry](/vendor/private-images-kots) in _Use the Proxy Registry with Replicated Installers_.
12
12
13
-
To support installations with HelmChart v2:
13
+
1. Package each Helm chart and add the `.tgz` chart archives to a new release. See [Package a Helm Chart for a Release](/vendor/helm-install-release).
14
14
15
-
1.In the HelmChart v2 custom resource, configure the `builder` key. This ensures that all the required and optional images for your application are available for users to push to their own local image registry. See [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_.
15
+
1.For each Helm chart in the release, ensure that there is a corresponding HelmChart v2 custom resource (version `kots.io/v1beta2`) . See [HelmChart v2](/reference/custom-resource-helmchart-v2).
16
16
17
-
1.Configure the HelmChart v2 [`optionalValues`](/reference/custom-resource-helmchart-v2#optionalValues) key so that KOTS conditionally rewrites any application image references in your Helm values if the user configured a local image registry.
17
+
1.If you are migrating from HelmChart v1, remove any unsupported fields from the HelmChart custom resource(s) in the release. See [Differences From HelmChart v1](#differences) below.
18
18
19
-
You will use the KOTS [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost) and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to inject the hostname and namespace for the user's registry in the image reference(s). You will use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) template function to create a conditional statement that evaluates if a local registry is configured.
19
+
1. For each HelmChart v2 resource in the release, configure the `builder` key. This ensures that all the required and optional images for your application are available for users to push to their own local image registry. Using a local image registry is required in air gap installations and optional in online installations. See [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_.
20
20
21
-
<details>
22
-
<summary>What is the registry namespace?</summary>
23
-
24
-
The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`.
25
-
</details>
21
+
1. For each HelmChart v2 resource in the release, configure the [`optionalValues`](/reference/custom-resource-helmchart-v2#optionalValues) key so that KOTS conditionally rewrites any application image references in your Helm values if a local image registry is used.
26
22
27
23
**Example:**
28
24
29
-
```yaml
30
-
# KOTS HelmChart custom resource
31
-
32
-
apiVersion: kots.io/v1beta2
33
-
kind: HelmChart
34
-
metadata:
35
-
name: samplechart
36
-
spec:
37
-
optionalValues:
38
-
# Create a conditional statement in the `when` field
1. In the [`optionalValues`](/reference/custom-resource-helmchart-v2#optionalValues) key, use the same method as in the previous step to update the Replicated SDK image reference.
48
+
For more information about the KOTS template functions used, see [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace).
49
+
50
+
<details>
51
+
<summary>What is the registry namespace?</summary>
52
+
53
+
The registry namespace is the path between the registry and the image name. For example, `images.registry.com/namespace/image:tag`.
54
+
</details>
55
+
56
+
1. In the HelmChart v2 custom resource that corresponds to the chart where the Replicated SDK is declared as a dependency, configure the [`optionalValues`](/reference/custom-resource-helmchart-v2#optionalValues) key using the same method as in the previous step to conditionally rewrite the Replicated SDK image reference.
48
57
49
58
**Example:**
50
59
@@ -56,8 +65,8 @@ To support installations with HelmChart v2:
56
65
name: samplechart
57
66
spec:
58
67
optionalValues:
59
-
# Conditionally rewrite SDK image when a local registry
60
-
# is configured
68
+
# Conditionally rewrite SDK image when a
69
+
# local registry is configured
61
70
- when: 'repl{{ HasLocalRegistry }}'
62
71
values:
63
72
replicated:
@@ -67,10 +76,17 @@ To support installations with HelmChart v2:
For more information about declaring the SDK as a dependency, see [Install the SDK as a Subchart](/vendor/replicated-sdk-installing#install-the-sdk-as-a-subchart) in _Install the Replicated SDK_.
70
80
71
-
1. To avoid errors caused by reaching the Docker Hub rate limit, do the following:
81
+
1. For any of your application images that could be rate limited by Docker Hub, do the following to avoid errors caused by reaching the rate limit:
82
+
83
+
<details>
84
+
<summary>What is Docker Hub rate limiting?</summary>
72
85
73
-
1. In the HelmChart v2 [`values`](/reference/custom-resource-helmchart-v2#values) key, add a new value with the KOTS `APP_SLUG-kotsadm-dockerhub` pull secret, where `APP_SLUG` is your unique application slug.
86
+
Docker Hub enforces rate limits for Anonymous and Free users. For more information, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website.
87
+
</details>
88
+
89
+
1. For each HelmChart v2 resource in the release, configure the [`values`](/reference/custom-resource-helmchart-v2#values) key to add a new value with the KOTS `APP_SLUG-kotsadm-dockerhub` pull secret, where `APP_SLUG` is your unique application slug.
74
90
75
91
**Example:**
76
92
@@ -91,18 +107,14 @@ To support installations with HelmChart v2:
91
107
- name: your-app-slug-kotsadm-dockerhub
92
108
```
93
109
<details>
94
-
<summary>How does the `kotsadm-dockerhub` pull secret avoid Docker Hub rate limiting errors?</summary>
95
-
96
-
Docker Hub enforces rate limits for Anonymous and Free users. For more information, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website.
110
+
<summary>What is the purpose of the `kotsadm-dockerhub` pull secret?</summary>
97
111
98
-
To avoid errors caused by reaching the rate limit, your users can run the `kots docker ensure-secret` command, which creates an `<app-slug>-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits).
112
+
To avoid errors caused by reaching the rate limit, your users can run the `kots docker ensure-secret` command, which creates an `<app-slug>-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information about this command, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits).
99
113
100
-
If you are deploying a Helm chart with Docker Hub images that could be rate limited, to support the use of the `kots docker ensure-secret` command, any Pod definitions in your Helm chart templates that reference the rate-limited image must be updated to access the `<app-slug>-kotsadm-dockerhub` pull secret.
101
-
102
-
During installation, KOTS sets the value of the matching field in the `values.yaml` file with the `<app-slug>-kotsadm-dockerhub` pull secret, and any Helm chart templates that access the value are updated.
114
+
If you are deploying a Helm chart with Docker Hub images that could be rate limited, any Pod definitions in your Helm chart templates that reference the rate-limited image must be updated to access the `<app-slug>-kotsadm-dockerhub` pull secret.
103
115
</details>
104
116
105
-
1. Ensure that there is a matching value in your Helm chart `values.yaml`.
117
+
1. Ensure that there is a matching value in each of the corresponding Helm chart `values.yaml` files.
106
118
107
119
**Example:**
108
120
@@ -116,7 +128,7 @@ To support installations with HelmChart v2:
116
128
pullSecrets: []
117
129
```
118
130
119
-
1. In your Helm chart templates, update any Pod definitions that reference rate-limited Docker Hub images to access the Helm value with the Docker Hub pull secret.
131
+
1. In your Helm chart templates, update any Pod definitions that reference rate-limited Docker Hub images to include the pull secret.
120
132
121
133
**Example:**
122
134
@@ -129,21 +141,20 @@ To support installations with HelmChart v2:
# the kotsadm-dockerhub pull secret is access from values and added to this array
144
+
# the kotsadm-dockerhub pull secret is accessed from
145
+
# the Helm values and added to this array
133
146
{{- with .Values.image.pullSecrets }}
134
147
imagePullSecrets:
135
148
{{- toYaml . | nindent 2 }}
136
149
{{- end }}
137
150
```
138
151
139
-
1. (KOTS Existing Cluster and kURL Installations Only) To support backup and restore with snapshots, configure the HelmChart v2 [optionalValues](/reference/custom-resource-helmchart-v2#optionalvalues) key so that the required `kots.io/backup: velero` and `kots.io/app-slug: APP_SLUG` labels are added to all resources that you want to be included in backups.
152
+
1. (KOTS Existing Cluster and kURL Installations Only) If you support KOTS existing cluster or kURL installations, for each HelmChart v2 resource in the release, configure the [optionalValues](/reference/custom-resource-helmchart-v2#optionalvalues) key to add the `kots.io/backup: velero` and `kots.io/app-slug: APP_SLUG` labels to all resources that you want to be included in backups with Replicated snapshots. These labels are required to support the use of snapshots. In the `optionalValues` key, use a `when` statement that evaluates to true only when the customer has the [`isSnapshotSupported`](/vendor/licenses-using-builtin-fields#admin-console-feature-options) field enabled for their license.
140
153
141
154
:::note
142
-
The Replicated [snapshots](snapshots-overview) feature for backup and restore is supported only for KOTS existing cluster and kURL installations. Snapshots are not supported for installations with Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx).
155
+
The Replicated [snapshots](snapshots-overview) feature for backup and restore is supported only for KOTS existing cluster and kURL installations. Snapshots are not supported for installations with Embedded Cluster. For more information about disaster recovery for Embedded Cluster installations, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx).
143
156
:::
144
157
145
-
In the `optionalValues` key, use a `when` statement that evaluates to true only when the customer has the [`isSnapshotSupported`](/vendor/licenses-using-builtin-fields#admin-console-feature-options) field enabled for their license. You can use the KOTS [LicenseFieldValue](/reference/template-functions-license) template function to check the value of the `isSnapshotSupported` license field.
146
-
147
158
**Example**:
148
159
149
160
```yaml
@@ -173,10 +184,21 @@ To support installations with HelmChart v2:
For more information about the KOTS LicenseFieldValue template function, see [LicenseFieldValue](/reference/template-functions-license).
188
+
189
+
For more information about the `isSnapshotSupported` and `appSlug` built-in license fields, see the [Admin Console Feature Options](/vendor/licenses-using-builtin-fields#admin-console-feature-options) table in _Built-In License Fields_.
190
+
191
+
1. Promote the release a channel that your team uses for testing, and install the release in a development environment to test your changes.
192
+
193
+
## Next Step: Migrate Existing Installations to HelmChart v2
194
+
195
+
Existing installations can be migrated to use the KOTS HelmChart v2 method, without having to reinstall the application.
176
196
177
-
## Differences From HelmChart v1
197
+
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).
198
+
199
+
## Differences From HelmChart v1 {#differences}
178
200
179
-
The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`:
201
+
The HelmChart v2 custom resource has the following differences from v1:
180
202
181
203
<table>
182
204
<tr>
@@ -205,9 +227,3 @@ The `kots.io/v1beta2` HelmChart custom resource has the following differences fr
205
227
<td><code>useHelmInstall</code> field is removed</td>
206
228
</tr>
207
229
</table>
208
-
209
-
## Next Step: Migrate Existing Installations to HelmChart v2
210
-
211
-
Existing installations can be migrated to use the KOTS HelmChart v2 method, without having to reinstall the application.
212
-
213
-
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).
0 commit comments