Skip to content

Commit 6f3daa3

Browse files
paigecalvertpaigecalvert
committed
wip
1 parent 8468664 commit 6f3daa3

File tree

1 file changed

+49
-146
lines changed

1 file changed

+49
-146
lines changed

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

Lines changed: 49 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -10,45 +10,27 @@ For more information about how KOTS uses the HelmChart custom resource to instal
1010

1111
To configure the HelmChart custom resource, do the following:
1212

13-
1. Rewrite image names and Inject a KOTS-generated image pull secret they can be pulled through the Replicated proxy registry. See [Rewrite Image Names](#rewrite-image-names).
14-
1. Inject a KOTS-generated image pull secret that grants proxy access to private images through the Replicated proxy registry. See [Inject Image Pull Secrets](#inject-image-pull-secrets).
13+
1. Rewrite image names and inject the KOTS-generated image pull secret. See [Rewrite Image Names](#rewrite-image-names).
1514
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).
16-
1. Configure the `builder` key to allow your users to push images to their own local registries, such as in air gap installations. See [Configure the `builder` key to Support Local Image Registries](#local-registries).
15+
1. Configure the `builder` key to allow users to push images to their own local registries. See [Configure the `builder` key to Support Local Image Registries](#local-registries).
1716
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).
1817
:::note
1918
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).
2019
:::
2120

22-
## Task 1: Rewrite Image Names {#rewrite-image-names}
21+
## Task 1: Rewrite Image Names and Inject the KOTS Pull Secret {#rewrite-image-names}
2322

24-
### Overview
25-
26-
Configure the HelmChart custom resource so that KOTS rewrites the names of images in your Helm values during deployment.
27-
28-
This allows images to be accessed at one of the following locations, depending on where they were pushed:
23+
Configure the HelmChart custom resource so that KOTS rewrites the names of images in your Helm values during deployment. Additionally, add the KOTS-generated pull secret for the proxy service. This allows images to be accessed at one of the following locations, depending on where they were pushed:
2924
* The [Replicated proxy registry](private-images-about) (`proxy.replicated.com` or your custom domain)
3025
* A public image registry
3126
* Your customer's local registry
3227
* The built-in registry used in Replicated Embedded Cluster or Replicated kURL installations in air-gapped environments
3328

34-
You will use the following KOTS template functions to conditionally rewrite image names depending on where the given image should be accessed:
35-
* [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry): Returns true if the installation environment is configured to use a local image registry. HasLocalRegistry is always true in air gap installations. HasLocalRegistry is also true in online installations if the user configured a local private registry.
36-
* [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost): Returns the host of the local registry that the user configured. Alternatively, for air gap installations with Embedded Cluster or kURL, LocalRegistryHost returns the host of the built-in registry.
37-
* [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace): Returns the namespace of the local registry that the user configured. Alternatively, for air gap installations with Embedded Cluster or kURL, LocalRegistryNamespace returns the namespace of the built-in registry.
38-
39-
<details>
40-
<summary>What is the registry namespace?</summary>
41-
42-
The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`.
43-
</details>
44-
45-
### Task 1a: Rewrite Private Image Names
46-
4729
To rewrite image names to the location of the image in the proxy registry:
4830

4931
1. In the HelmChart custom resource, under the `values` key, rewrite image names using the format `<proxy-domain>/proxy/<app-slug>/<image>`, where:
5032
* `<proxy-domain>` is `proxy.replicated.com` or your custom domain. For more information about configuring a custom domain for the proxy registry, see [Using Custom Domains](/vendor/custom-domains-using).
51-
* `<app-slug>` is the unique application slug in the Vendor Portal
33+
* `<app-slug>` is the unique application slug in the Vendor Portal. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug).
5234
* `<image>` is the path to the image in your registry
5335

5436
For example, if the private image is `quay.io/my-org/nginx:v1.0.1` and `images.yourcompany.com` is the custom proxy registry domain, then the image name should be rewritten to `images.yourcompany.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`.
@@ -60,7 +42,7 @@ To rewrite image names to the location of the image in the proxy registry:
6042
repository: '{{repl LocalRegistryNamespace }}/gitea'
6143
```
6244
63-
1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite image names.
45+
1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite private image names.
6446

6547
```yaml
6648
optionalValues:
@@ -73,123 +55,62 @@ To rewrite image names to the location of the image in the proxy registry:
7355
- name: '{{repl ImagePullSecretName }}'
7456
```
7557

76-
### Task 1b: Rewrite Public Image Names
77-
78-
For any public images used by your application, configure the HelmChart custom resource so that image names are rewritten to either the location of the image in the public registry (for online installations) or the local registry (for air gap installations or online installations where the user configured a local registry.
79-
80-
For more information, see the example below.
81-
82-
#### Example
83-
84-
The following HelmChart custom resource uses the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite an image registry and repository depending on if a local registry is used:
85-
86-
```yaml
87-
# kots.io/v1beta2 HelmChart custom resource
88-
89-
apiVersion: kots.io/v1beta2
90-
kind: HelmChart
91-
metadata:
92-
name: samplechart
93-
spec:
94-
...
95-
values:
96-
image:
97-
# If a local registry is used, use that registry's hostname
98-
# Else, use the public registry host (ghcr.io)
99-
registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "ghcr.io" }}'
100-
# If a local registry is used, use the registry namespace provided
101-
# Else, use the path to the image in the public registry
102-
repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "cloudnative-pg" }}/cloudnative-pg'
103-
tag: catalog-1.24.0
104-
```
105-
106-
The `spec.values.image.registry` and `spec.values.image.repository` fields in the HelmChart custom resource correspond to `image.registry` and `image.repository` fields in the Helm chart `values.yaml` file, as shown in the example below:
107-
108-
```yaml
109-
# Helm chart values.yaml file
110-
111-
image:
112-
registry: ghcr.io
113-
repository: cloudnative-pg/cloudnative-pg
114-
tag: catalog-1.24.0
115-
```
116-
117-
During installation, KOTS renders the template functions and sets the `image.registry` and `image.repository` fields in your Helm chart `values.yaml` file based on the value of the corresponding fields in the HelmChart custom resource. Any templates in the Helm chart that access the `image.registry` and `image.repository` fields are updated to use the appropriate value, as shown in the example below:
118-
119-
```yaml
120-
apiVersion: v1
121-
kind: Pod
122-
spec:
123-
containers:
124-
- name:
125-
image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }}
126-
```
58+
1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite public image names.
12759

128-
## Task 2: Inject Image Pull Secrets {#inject-image-pull-secrets}
60+
For any public images used by your application, configure the HelmChart custom resource so that image names are rewritten to either the location of the image in the public registry (for online installations) or the local registry (for air gap installations or online installations where the user configured a local registry.
12961

130-
Kubernetes requires a Secret of type `kubernetes.io/dockerconfigjson` to authenticate with a registry and pull a private image. When you reference a private image in a Pod definition, you also provide the name of the Secret in a `imagePullSecrets` key in the Pod definition. For more information, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation.
62+
```yaml
63+
# kots.io/v1beta2 HelmChart custom resource
13164
132-
During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret that is based on the customer license. This pull secret grants access to the private image through the Replicated proxy registry or in the Replicated registry. Additionally, if the user configured a local image registry, then the pull secret contains the credentials for the local registry. You must provide the name of this KOTS-generated pull secret in any Pod definitions that reference the private image.
65+
apiVersion: kots.io/v1beta2
66+
kind: HelmChart
67+
metadata:
68+
name: samplechart
69+
spec:
70+
...
71+
values:
72+
image:
73+
# If a local registry is used, use that registry's hostname
74+
# Else, use the public registry host (ghcr.io)
75+
registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "ghcr.io" }}'
76+
# If a local registry is used, use the registry namespace provided
77+
# Else, use the path to the image in the public registry
78+
repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "cloudnative-pg" }}/cloudnative-pg'
79+
tag: catalog-1.24.0
80+
```
13381

134-
You can inject the name of this pull secret into a field in the HelmChart custom resource using the Replicated ImagePullSecretName template function. During installation, KOTS sets the value of the corresponding field in your Helm chart `values.yaml` file with the rendered value of the ImagePullSecretName template function.
82+
1. Add the pull secret.
13583

136-
#### Example
84+
Kubernetes requires a Secret of type `kubernetes.io/dockerconfigjson` to authenticate with a registry and pull a private image. For more information, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation.
13785

138-
The following example shows a `spec.values.image.pullSecrets` array in the HelmChart custom resource that uses the ImagePullSecretName template function to inject the name of the KOTS-generated pull secret:
86+
During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret that is based on the customer license. This pull secret grants access to the private image through the Replicated proxy registry or in the Replicated registry. Additionally, if the user configured a local image registry, then the pull secret contains the credentials for the local registry. You must provide the name of this KOTS-generated pull secret in any Pod definitions that reference the private image.
13987

140-
```yaml
141-
# kots.io/v1beta2 HelmChart custom resource
88+
You can inject the name of this pull secret into a field in the HelmChart custom resource using the Replicated ImagePullSecretName template function. During installation, KOTS sets the value of the corresponding field in your Helm chart `values.yaml` file with the rendered value of the ImagePullSecretName template function.
14289

143-
apiVersion: kots.io/v1beta2
144-
kind: HelmChart
145-
metadata:
146-
name: samplechart
147-
spec:
148-
values:
149-
image:
150-
# Note: Use proxy.replicated.com or your custom domain
151-
registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}'
152-
repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/ecr.us-east-1.amazonaws.com/my-org" }}/api'
153-
pullSecrets:
154-
- name: '{{repl ImagePullSecretName }}'
155-
```
156-
157-
The `spec.values.image.pullSecrets` array in the HelmChart custom resource corresponds to a `image.pullSecrets` array in the Helm chart `values.yaml` file, as shown in the example below:
90+
The following example shows a `spec.values.image.pullSecrets` array in the HelmChart custom resource that uses the ImagePullSecretName template function to inject the name of the KOTS-generated pull secret:
15891

159-
```yaml
160-
# Helm chart values.yaml file
92+
```yaml
93+
# kots.io/v1beta2 HelmChart custom resource
16194
162-
image:
163-
registry: ecr.us-east-1.amazonaws.com
164-
repository: my-org/api/nginx
165-
pullSecrets:
166-
- name: my-org-secret
167-
```
168-
169-
During installation, KOTS renders the ImagePullSecretName template function and adds the rendered pull secret name to the `image.pullSecrets` array in the Helm chart `values.yaml` file.
170-
171-
Any templates in the Helm chart that access the `image.pullSecrets` field are updated to use the name of the KOTS-generated pull secret, as shown in the example below:
172-
173-
```yaml
174-
apiVersion: v1
175-
kind: Pod
176-
metadata:
177-
name: nginx
178-
spec:
179-
containers:
180-
- name: nginx
181-
image: {{ .Values.image.registry }}/{{ .Values.image.repository }}
182-
{{- with .Values.image.pullSecrets }}
183-
imagePullSecrets:
184-
{{- toYaml . | nindent 2 }}
185-
{{- end }}
186-
```
95+
apiVersion: kots.io/v1beta2
96+
kind: HelmChart
97+
metadata:
98+
name: samplechart
99+
spec:
100+
values:
101+
image:
102+
# Note: Use proxy.replicated.com or your custom domain
103+
registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}'
104+
repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/ecr.us-east-1.amazonaws.com/my-org" }}/api'
105+
pullSecrets:
106+
- name: '{{repl ImagePullSecretName }}'
107+
```
187108

188-
## Task 3: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret}
109+
## Task 2: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret}
189110

190111
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).
191112

192-
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).
113+
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.
193114

194115
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.
195116

@@ -228,24 +149,7 @@ spec:
228149
- name: example-app-slug-kotsadm-dockerhub
229150
```
230151

231-
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`:
232-
233-
```yaml
234-
apiVersion: v1
235-
kind: Pod
236-
metadata:
237-
name: example
238-
spec:
239-
containers:
240-
- name: example
241-
image: {{ .Values.image.registry }}/{{ .Values.image.repository }}
242-
{{- with .Values.image.pullSecrets }}
243-
imagePullSecrets:
244-
{{- toYaml . | nindent 2 }}
245-
{{- end }}
246-
```
247-
248-
## Task 4: Support the Use of Local Image Registries {#local-registries}
152+
## Task 3: Support the Use of Local Image Registries {#local-registries}
249153

250154
Local image registries are required for KOTS installations in air-gapped environments with no outbound internet connection. Also, users in online environments can optionally use a local registry. For more information about how users configure a local image registry with KOTS, see [Configuring Local Image Registries](/enterprise/image-registry-settings).
251155

@@ -298,7 +202,6 @@ spec:
298202
299203
### About the HelmChart Custom Resource
300204
301-
302205
<KotsHelmCrDescription/>
303206
304207
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).

0 commit comments

Comments
 (0)