Skip to content

Commit fb1c1f8

Browse files
paigecalvertpaigecalvert
committed
editing steps on how to configure helmchart v2
1 parent 20368c7 commit fb1c1f8

File tree

1 file changed

+100
-98
lines changed

1 file changed

+100
-98
lines changed

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

Lines changed: 100 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -2,102 +2,77 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.md
22

33
# Support Installations with HelmChart v2
44

5-
This topic describes how to configure your application to support installations with the Replicated HelmChart custom resource version `kots.io/v1beta2`.
5+
This topic describes how to configure your application to support installations with the Replicated HelmChart custom resource version `kots.io/v1beta2` (HelmChart v2).
66

77
## Prerequisite
88

9-
Update your Helm chart values to proxy your application images through 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+
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_.
1010

1111
## Configure HelmChart v2
1212

13-
1. Configure the `builder` key. This ensures that all of the required and optional images for your application are available to users to push their own local registry. See [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_.
13+
To support installations with HelmChart v2:
1414

15-
1. Configure the `optionalValues` key so that image references in your Helm values are correctly rewritten to the user's local registry.To support the use of local image registries in air gap and online installations. Local image registries are required for installations in air-gapped environments with limited or no outbound internet access. Also, users in online environments can optionally use a local registry. For more information about how users configure a local image registry, see [Configuring Local Image Registries](/enterprise/image-registry-settings).
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_.
1616

17-
You will use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) template function to create the conditional statement. 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).
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.
1818

19-
<details>
20-
<summary>What is the registry namespace?</summary>
21-
22-
The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`.
23-
</details>
24-
25-
Do the following:
26-
27-
1. Rewrite each of the application image references in your Helm values.
28-
29-
**Example:**
30-
31-
```yaml
32-
# KOTS HelmChart custom resource
33-
34-
apiVersion: kots.io/v1beta2
35-
kind: HelmChart
36-
metadata:
37-
name: samplechart
38-
spec:
39-
optionalValues:
40-
# Define the conditional statement in the when field
41-
- when: 'repl{{ HasLocalRegistry }}'
42-
values:
43-
postgres:
44-
image:
45-
registry: '{{repl LocalRegistryHost }}'
46-
repository: '{{repl LocalRegistryNamespace }}'/cloudnative-pg/cloudnative-pg
47-
```
48-
49-
1. Rewrite the reference Replicated SDK image in your Helm values.
50-
51-
**Example:**
52-
53-
```yaml
54-
# KOTS HelmChart custom resource
55-
apiVersion: kots.io/v1beta2
56-
kind: HelmChart
57-
metadata:
58-
name: samplechart
59-
spec:
60-
optionalValues:
61-
# Conditionally rewrite SDK image when a local registry
62-
# is configured
63-
- when: 'repl{{ HasLocalRegistry }}'
64-
values:
65-
replicated:
66-
image:
67-
registry: '{{repl LocalRegistryHost }}'
68-
# The default location for the SDK image is
69-
# proxy.replicated.com/library/replicated-sdk-image
70-
repository: '{{repl LocalRegistryNamespace }}/library/replicated-sdk-image'
71-
```
72-
73-
1. To avoid errors caused by reaching the Docker Hub rate limit, add the `<app-slug>-kotsadm-dockerhub` pull secret to a field in the `values` key of the HelmChart custom resource, along with a matching field in your Helm chart `values.yaml` file. For more information about Docker Hub rate limiting, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website.
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.
7420

7521
<details>
76-
<summary>Why?</summary>
22+
<summary>What is the registry namespace?</summary>
7723

78-
Docker Hub enforces rate limits for Anonymous and Free users. 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).
24+
The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`.
25+
</details>
7926

80-
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, where `<app-slug>` is your application slug. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug).
27+
**Example:**
8128

82-
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.
83-
</details>
29+
```yaml
30+
# KOTS HelmChart custom resource
8431

85-
**Example:**
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
39+
- when: 'repl{{ HasLocalRegistry }}'
40+
values:
41+
postgres:
42+
image:
43+
registry: '{{repl LocalRegistryHost }}'
44+
repository: '{{repl LocalRegistryNamespace }}'/cloudnative-pg/cloudnative-pg
45+
```
8646
87-
The following Helm chart `values.yaml` file includes `image.registry`, `image.repository`, and `image.pullSecrets` for a rate-limited Docker Hub image:
47+
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.
8848

89-
```yaml
90-
# Helm chart values.yaml file
49+
**Example:**
9150

92-
image:
93-
registry: docker.io
94-
repository: my-org/example-docker-hub-image
95-
pullSecrets: []
96-
```
51+
```yaml
52+
# KOTS HelmChart custom resource
53+
apiVersion: kots.io/v1beta2
54+
kind: HelmChart
55+
metadata:
56+
name: samplechart
57+
spec:
58+
optionalValues:
59+
# Conditionally rewrite SDK image when a local registry
60+
# is configured
61+
- when: 'repl{{ HasLocalRegistry }}'
62+
values:
63+
replicated:
64+
image:
65+
registry: '{{repl LocalRegistryHost }}'
66+
# The default location for the SDK image is
67+
# proxy.replicated.com/library/replicated-sdk-image
68+
repository: '{{repl LocalRegistryNamespace }}/library/replicated-sdk-image'
69+
```
70+
71+
1. To avoid errors caused by reaching the Docker Hub rate limit, do the following:
9772

98-
The following HelmChart custom resource includes `spec.values.image.registry`, `spec.values.image.repository`, and `spec.values.image.pullSecrets`, which correspond to those in the Helm chart `values.yaml` file above.
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.
9974

100-
The `spec.values.image.pullSecrets` array lists the `<app-slug>-kotsadm-dockerhub` pull secret, where the slug for the application is `example-app-slug`:
75+
**Example:**
10176

10277
```yaml
10378
# kots.io/v1beta2 HelmChart custom resource
@@ -110,27 +85,56 @@ Update your Helm chart values to proxy your application images through the Repli
11085
values:
11186
image:
11287
registry: docker.io
113-
repository: my-org/example-docker-hub-image
88+
repository: your-org/example-docker-hub-image
89+
# Add a new pullSecrets array with the <app-slug>-kotsadm-dockerhub pull secret
11490
pullSecrets:
115-
- name: example-app-slug-kotsadm-dockerhub
91+
- name: your-app-slug-kotsadm-dockerhub
11692
```
93+
<details>
94+
<summary>How does the `kotsadm-dockerhub` pull secret avoid Docker Hub rate limiting errors?</summary>
11795

118-
During installation, KOTS adds the `example-app-slug-kotsadm-dockerhub` secret to the `image.pullSecrets` array in the Helm chart `values.yaml` file. Any templates in the Helm chart that access `image.pullSecrets` are updated to use `example-app-slug-kotsadm-dockerhub`:
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.
97+
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).
11999

120-
```yaml
121-
apiVersion: v1
122-
kind: Pod
123-
metadata:
124-
name: example
125-
spec:
126-
containers:
127-
- name: example
128-
image: {{ .Values.image.registry }}/{{ .Values.image.repository }}
129-
{{- with .Values.image.pullSecrets }}
130-
imagePullSecrets:
131-
{{- toYaml . | nindent 2 }}
132-
{{- end }}
133-
```
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.
103+
</details>
104+
105+
1. Ensure that there is a matching value in your Helm chart `values.yaml`.
106+
107+
**Example:**
108+
109+
```yaml
110+
# Helm chart values.yaml file
111+
112+
image:
113+
registry: docker.io
114+
repository: your-org/your-docker-hub-image
115+
# include the new pullSecrets array
116+
pullSecrets: []
117+
```
118+
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.
120+
121+
**Example:**
122+
123+
```yaml
124+
apiVersion: v1
125+
kind: Pod
126+
metadata:
127+
name: example
128+
spec:
129+
containers:
130+
- name: example
131+
image: {{ .Values.image.registry }}/{{ .Values.image.repository }}
132+
# the kotsadm-dockerhub pull secret is access from values and added to this array
133+
{{- with .Values.image.pullSecrets }}
134+
imagePullSecrets:
135+
{{- toYaml . | nindent 2 }}
136+
{{- end }}
137+
```
134138

135139
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.
136140

@@ -170,9 +174,7 @@ Update your Helm chart values to proxy your application images through the Repli
170174
kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }}
171175
```
172176
173-
## Additional Information
174-
175-
### HelmChart v1 and v2 Differences
177+
## Differences From HelmChart v1
176178
177179
The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`:
178180

@@ -204,8 +206,8 @@ The `kots.io/v1beta2` HelmChart custom resource has the following differences fr
204206
</tr>
205207
</table>
206208

207-
### Migrate Existing KOTS Installations to HelmChart v2
209+
## Next Step: Migrate Existing Installations to HelmChart v2
208210

209-
Existing KOTS installations can be migrated to use the KOTS HelmChart v2 method, without having to reinstall the application.
211+
Existing installations can be migrated to use the KOTS HelmChart v2 method, without having to reinstall the application.
210212

211213
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

Comments
 (0)