Skip to content

Commit 20368c7

Browse files
paigecalvertpaigecalvert
committed
formatting into numbered steps
1 parent 35d0933 commit 20368c7

File tree

1 file changed

+158
-182
lines changed

1 file changed

+158
-182
lines changed

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

Lines changed: 158 additions & 182 deletions
Original file line numberDiff line numberDiff line change
@@ -4,200 +4,176 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.md
44

55
This topic describes how to configure your application to support installations with the Replicated HelmChart custom resource version `kots.io/v1beta2`.
66

7-
## Workflow
7+
## Prerequisite
88

9-
To support HelmChart v2 installations for your application, do the following:
10-
1. 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_.
11-
1. Configure the `builder` and `optionalValues` keys to allow your users to push images to their own local registries. See [Support Local Image Registries](#local-registries).
12-
1. Add a pull secret for any Docker Hub images that could be rate limited. See [Add Pull Secret for Rate-Limited Docker Hub Images](#docker-secret).
13-
1. (KOTS Existing Cluster and kURL Installations Only) Add backup labels to your resources to support backup and restore with the KOTS snapshots feature. See [Add Backup Labels for Snapshots](#add-backup-labels-for-snapshots).
14-
:::note
15-
Snapshots is not supported for installations with Replicated Embedded Cluster. For more information about configuring disaster recovery for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery).
16-
:::
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_.
1710

18-
## Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret}
19-
20-
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).
21-
22-
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).
23-
24-
You can do this by adding 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. 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.
25-
26-
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.
27-
28-
#### Example
29-
30-
The following Helm chart `values.yaml` file includes `image.registry`, `image.repository`, and `image.pullSecrets` for a rate-limited Docker Hub image:
31-
32-
```yaml
33-
# Helm chart values.yaml file
34-
35-
image:
36-
registry: docker.io
37-
repository: my-org/example-docker-hub-image
38-
pullSecrets: []
39-
```
40-
41-
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.
42-
43-
The `spec.values.image.pullSecrets` array lists the `<app-slug>-kotsadm-dockerhub` pull secret, where the slug for the application is `example-app-slug`:
44-
45-
```yaml
46-
# kots.io/v1beta2 HelmChart custom resource
47-
48-
apiVersion: kots.io/v1beta2
49-
kind: HelmChart
50-
metadata:
51-
name: samplechart
52-
spec:
53-
values:
54-
image:
55-
registry: docker.io
56-
repository: my-org/example-docker-hub-image
57-
pullSecrets:
58-
- name: example-app-slug-kotsadm-dockerhub
59-
```
60-
61-
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`:
62-
63-
```yaml
64-
apiVersion: v1
65-
kind: Pod
66-
metadata:
67-
name: example
68-
spec:
69-
containers:
70-
- name: example
71-
image: {{ .Values.image.registry }}/{{ .Values.image.repository }}
72-
{{- with .Values.image.pullSecrets }}
73-
imagePullSecrets:
74-
{{- toYaml . | nindent 2 }}
75-
{{- end }}
76-
```
77-
78-
## Support the Use of Local Image Registries {#local-registries}
79-
80-
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).
81-
82-
This section describes how to configure the HelmChart v2 custom resource so that your users can push application images to their own local registry, and so that image references in your Helm values are correctly rewritten to the user's local registry.
83-
84-
To support the use of local image registries in air gap and online installations:
11+
## Configure HelmChart v2
8512

8613
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_.
8714

88-
1. Configure the `optionalValues` key so that KOTS conditionally rewrites image references in your Helm values during deployment when the user has a local image registry. 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).
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).
16+
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).
18+
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.
8974

9075
<details>
91-
<summary>What is the registry namespace?</summary>
92-
93-
The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`.
94-
</details>
95-
96-
Do the following:
97-
98-
1. Rewrite each of the application image references in your Helm values.
99-
100-
**Example:**
101-
102-
```yaml
103-
# KOTS HelmChart custom resource
104-
105-
apiVersion: kots.io/v1beta2
106-
kind: HelmChart
107-
metadata:
108-
name: samplechart
109-
spec:
110-
optionalValues:
111-
# Define the conditional statement in the when field
112-
- when: 'repl{{ HasLocalRegistry }}'
113-
values:
114-
postgres:
115-
image:
116-
registry: '{{repl LocalRegistryHost }}'
117-
repository: '{{repl LocalRegistryNamespace }}'/cloudnative-pg/cloudnative-pg
118-
```
119-
120-
1. Rewrite the reference Replicated SDK image in your Helm values.
121-
122-
**Example:**
123-
124-
```yaml
125-
# KOTS HelmChart custom resource
126-
apiVersion: kots.io/v1beta2
127-
kind: HelmChart
128-
metadata:
129-
name: samplechart
130-
spec:
131-
optionalValues:
132-
# Conditionally rewrite SDK image when a local registry
133-
# is configured
134-
- when: 'repl{{ HasLocalRegistry }}'
135-
values:
136-
replicated:
137-
image:
138-
registry: '{{repl LocalRegistryHost }}'
139-
# The default location for the SDK image is
140-
# proxy.replicated.com/library/replicated-sdk-image
141-
repository: '{{repl LocalRegistryNamespace }}/library/replicated-sdk-image'
142-
```
143-
144-
## (KOTS Existing Cluster and kURL Installations Only) Add Backup Labels for Snapshots {#add-backup-labels-for-snapshots}
145-
146-
:::note
147-
The Replicated [snapshots](snapshots-overview) feature for backup and restore is supported only for KOTS existing cluster installations 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).
148-
:::
149-
150-
The snapshots feature requires the following labels on all resources in your Helm chart that you want to be included in the backup:
151-
* `kots.io/backup: velero`
152-
* `kots.io/app-slug: APP_SLUG`, where `APP_SLUG` is the slug of your Replicated application.
153-
154-
For more information about snapshots, see [Understanding Backup and Restore](snapshots-overview).
155-
156-
To support backup and restore with snapshots, add the `kots.io/backup: velero` and `kots.io/app-slug: APP_SLUG` labels to fields under the HelmChart custom resource `optionalValues` key. Add a `when` statement that evaluates to true only when the customer license has the `isSnapshotSupported` entitlement.
157-
158-
The fields that you create under the `optionalValues` key must map to fields in your Helm chart `values.yaml` file. For more information about working with the `optionalValues` key, see [optionalValues](/reference/custom-resource-helmchart-v2#optionalvalues) in _HelmChart v2_.
159-
160-
#### Example
161-
162-
The following example shows how to add backup labels for snapshots in the `optionalValues` key of the HelmChart custom resource:
163-
164-
```yaml
165-
# kots.io/v1beta2 HelmChart custom resource
166-
167-
apiVersion: kots.io/v1beta2
168-
kind: HelmChart
169-
metadata:
170-
name: samplechart
171-
spec:
172-
...
173-
optionalValues:
174-
# add backup labels only if the license supports snapshots
175-
- when: "repl{{ LicenseFieldValue `isSnapshotSupported` }}"
176-
recursiveMerge: true
177-
values:
178-
mariadb:
179-
commonLabels:
180-
kots.io/backup: velero
181-
kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }}
182-
podLabels:
183-
kots.io/backup: velero
184-
kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }}
185-
```
76+
<summary>Why?</summary>
77+
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).
79+
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).
81+
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>
84+
85+
**Example:**
86+
87+
The following Helm chart `values.yaml` file includes `image.registry`, `image.repository`, and `image.pullSecrets` for a rate-limited Docker Hub image:
88+
89+
```yaml
90+
# Helm chart values.yaml file
91+
92+
image:
93+
registry: docker.io
94+
repository: my-org/example-docker-hub-image
95+
pullSecrets: []
96+
```
97+
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.
99+
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`:
101+
102+
```yaml
103+
# kots.io/v1beta2 HelmChart custom resource
104+
105+
apiVersion: kots.io/v1beta2
106+
kind: HelmChart
107+
metadata:
108+
name: samplechart
109+
spec:
110+
values:
111+
image:
112+
registry: docker.io
113+
repository: my-org/example-docker-hub-image
114+
pullSecrets:
115+
- name: example-app-slug-kotsadm-dockerhub
116+
```
117+
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`:
119+
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+
```
134+
135+
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.
136+
137+
:::note
138+
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).
139+
:::
140+
141+
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.
142+
143+
**Example**:
144+
145+
```yaml
146+
# kots.io/v1beta2 HelmChart custom resource
147+
148+
apiVersion: kots.io/v1beta2
149+
kind: HelmChart
150+
metadata:
151+
name: samplechart
152+
spec:
153+
...
154+
optionalValues:
155+
# Add backup labels only when the license supports snapshots.
156+
# Use the LicenseFieldValue template function to check if
157+
# the isSnapshotSupported license field is enabled
158+
- when: "repl{{ LicenseFieldValue `isSnapshotSupported` }}"
159+
recursiveMerge: true
160+
values:
161+
mariadb:
162+
commonLabels:
163+
kots.io/backup: velero
164+
# Use the LicenseFieldValue template function and the
165+
# built-in appSlug license field value to inject your
166+
# unique app slug
167+
kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }}
168+
podLabels:
169+
kots.io/backup: velero
170+
kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }}
171+
```
186172
187173
## Additional Information
188174
189-
### About the HelmChart Custom Resource
190-
191-
<KotsHelmCrDescription/>
192-
193-
For more information about the HelmChart custom resource, including the unique requirements and limitations for the keys described in this topic, see [HelmChart v2](/reference/custom-resource-helmchart-v2).
194-
195175
### HelmChart v1 and v2 Differences
196176
197-
To support the use of local registries with version `kots.io/v1beta2` of the HelmChart custom resource, provide the necessary values in the builder field to render the Helm chart with all of the necessary images so that KOTS knows where to pull the images from to push them into the local registry.
198-
199-
For more information about how to configure the `builder` key, see [Package Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles) and [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_.
200-
201177
The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`:
202178

203179
<table>

0 commit comments

Comments
 (0)