Skip to content

Commit 6b51059

Browse files
paigecalvertpaigecalvert
committed
Redistribute helmchart v2 topic
1 parent ce398bf commit 6b51059

File tree

9 files changed

+295
-58
lines changed

9 files changed

+295
-58
lines changed

‎docs/partials/proxy-service/_step-additional-ns.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
If you are deploying Pods to namespaces other than the application namespace, add the namespace to the `additionalNamespaces` attribute of the KOTS Application custom resource. This ensures that KOTS can provision the `imagePullSecret` in the namespace to allow the Pod to pull the image. For instructions, see [Define Additional Namespaces](operator-defining-additional-namespaces).

‎docs/partials/proxy-service/_step-rewrite-helm-values.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
In your Helm chart values file, set your image repository URL to the location of the image on the proxy registry. If you added a custom domain, use your custom domain. Otherwise, use `proxy.replicated.com`.
2+
3+
The proxy registry URL has the following format: `DOMAIN/proxy/APP_SLUG/EXTERNAL_REGISTRY_IMAGE_URL`
4+
5+
Where:
6+
* `DOMAIN` is either `proxy.replicated.com` or your custom domain.
7+
* `APP_SLUG` is the unique slug of your application.
8+
* `EXTERNAL_REGISTRY_IMAGE_URL` is the path to the private image on your external registry.
9+
10+
**Example:**
11+
12+
```yaml
13+
# values.yaml
14+
api:
15+
image:
16+
# proxy.registry.com or your custom domain
17+
registry: ghcr.io
18+
repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg
19+
tag: catalog-1.24.0
20+
```
21+
22+
Ensure that any references to the image in your Helm chart access the field from your values file.
23+
24+
**Example**:
25+
26+
```yaml
27+
apiVersion: v1
28+
kind: Pod
29+
spec:
30+
containers:
31+
- name: api
32+
# Access the registry, repository, and tag fields from the values file
33+
image: {{ .Values.images.api.registry }}/{{ .Values.images.api.repository }}:{{ .Values.images.api.tag }}
34+
```

‎docs/vendor/helm-image-registry.mdx‎

Lines changed: 2 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import StepCreds from "../partials/proxy-service/_step-creds.mdx"
22
import StepCustomDomain from "../partials/proxy-service/_step-custom-domain.mdx"
3+
import RewriteHelmValues from "../partials/proxy-service/_step-rewrite-helm-values.mdx"
34

45
# Use the Proxy Registry with Helm Installations
56

@@ -19,40 +20,7 @@ To use the Replicated proxy registry for applications installed with Helm:
1920

2021
1. <StepCustomDomain/>
2122

22-
1. In your Helm chart values file, set your image repository URL to the location of the image on the proxy registry. If you added a custom domain, use your custom domain. Otherwise, use `proxy.replicated.com`.
23-
24-
The proxy registry URL has the following format: `DOMAIN/proxy/APP_SLUG/EXTERNAL_REGISTRY_IMAGE_URL`
25-
26-
Where:
27-
* `DOMAIN` is either `proxy.replicated.com` or your custom domain.
28-
* `APP_SLUG` is the unique slug of your application.
29-
* `EXTERNAL_REGISTRY_IMAGE_URL` is the path to the private image on your external registry.
30-
31-
**Example:**
32-
33-
```yaml
34-
# values.yaml
35-
api:
36-
image:
37-
# proxy.registry.com or your custom domain
38-
registry: ghcr.io
39-
repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg
40-
tag: catalog-1.24.0
41-
```
42-
43-
1. Ensure that any references to the image in your Helm chart access the field from your values file.
44-
45-
**Example**:
46-
47-
```yaml
48-
apiVersion: v1
49-
kind: Pod
50-
spec:
51-
containers:
52-
- name: api
53-
# Access the registry, repository, and tag fields from the values file
54-
image: {{ .Values.images.api.registry }}/{{ .Values.images.api.repository }}:{{ .Values.images.api.tag }}
55-
```
23+
1. <RewriteHelmValues/>
5624

5725
1. In your Helm chart templates, create a Kubernetes Secret to evaluate if the `global.replicated.dockerconfigjson` value is set and then write the rendered value into a Secret on the cluster, as shown below.
5826

‎docs/vendor/helm-native-about.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,48 @@ The `kots.io/v1beta2` HelmChart custom resource requires configuration. For more
6060

6161
For information about the fields and syntax of the HelmChart custom resource, see [HelmChart v2](/reference/custom-resource-helmchart-v2).
6262

63+
### HelmChart v1 and v2 Differences
64+
65+
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.
66+
67+
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_.
68+
69+
The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`:
70+
71+
<table>
72+
<tr>
73+
<th>HelmChart v1beta2</th>
74+
<th>HelmChart v1beta1</th>
75+
<th>Description</th>
76+
</tr>
77+
<tr>
78+
<td><code>apiVersion: kots.io/v1beta2</code></td>
79+
<td><code>apiVersion: kots.io/v1beta1</code></td>
80+
<td><code>apiVersion</code> is updated to <code>kots.io/v1beta2</code></td>
81+
</tr>
82+
<tr>
83+
<td><code>releaseName</code></td>
84+
<td><code>chart.releaseName</code></td>
85+
<td><code>releaseName</code> is a top level field under <code>spec</code></td>
86+
</tr>
87+
<tr>
88+
<td>N/A</td>
89+
<td><code>helmVersion</code></td>
90+
<td><code>helmVersion</code> field is removed</td>
91+
</tr>
92+
<tr>
93+
<td>N/A</td>
94+
<td><code>useHelmInstall</code></td>
95+
<td><code>useHelmInstall</code> field is removed</td>
96+
</tr>
97+
</table>
98+
99+
### About Migrating Existing KOTS Installations to HelmChart v2
100+
101+
Existing KOTS installations can be migrated to use the KOTS HelmChart v2 method, without having to reinstall the application.
102+
103+
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).
104+
63105
### Limitations
64106

65107
The following limitations apply when deploying Helm charts with the `kots.io/v1beta2` HelmChart custom resource:

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -279,7 +279,7 @@ To support the use of local registries, configure the `builder` key. For more in
279279
## Task 5: Add Backup Labels for Snapshots (KOTS Existing Cluster and kURL Installations Only) {#add-backup-labels-for-snapshots}
280280

281281
:::note
282-
The Replicated [snapshots](snapshots-overview) feature for backup and restsore is supported only for existing cluster installations with KOTS. Snapshots are not support 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).
282+
The Replicated [snapshots](snapshots-overview) feature for backup and restore is supported only for existing cluster installations with KOTS. Snapshots are not support 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).
283283
:::
284284

285285
The snapshots feature requires the following labels on all resources in your Helm chart that you want to be included in the backup:
@@ -323,7 +323,6 @@ spec:
323323
324324
### About the HelmChart Custom Resource
325325
326-
327326
<KotsHelmCrDescription/>
328327
329328
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).

‎docs/vendor/helmchart-local-registries.mdx‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Conditionally Rewrite Image Names for Local Registries
2+
3+
This topic describes how to conditionally rewrite image names for local registries when using the HelmChart v2 custom resource.
4+
5+
## Overview
6+
7+
Local image registries are required for air gap KOTS installations in existing clusters. 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).
8+
9+
You can configure the KOTS HelmChart custom resource `optionalValues` key so that KOTS conditionally rewrites the names of images in your Helm values during deployment, depending on if the user configured a local registry.
10+
11+
You can use the following KOTS template functions in the `optionalValues` key to conditionally rewrite image names:
12+
* [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.
13+
* [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.
14+
* [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.
15+
16+
<details>
17+
<summary>What is the registry namespace?</summary>
18+
19+
The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`.
20+
</details>
21+
22+
## Prerequisite
23+
24+
To support the use of local registries, configure the `builder` key. For more information about how to configure the `builder` key, see [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_.
25+
26+
## Rewrite Application Image Names
27+
28+
**Example:**
29+
30+
```yaml
31+
# KOTS HelmChart custom resource
32+
33+
apiVersion: kots.io/v1beta2
34+
kind: HelmChart
35+
metadata:
36+
name: samplechart
37+
spec:
38+
optionalValues:
39+
# Define the conditional statement in the when field
40+
- when: 'repl{{ HasLocalRegistry }}'
41+
values:
42+
postgres:
43+
image:
44+
registry: '{{repl LocalRegistryHost }}'
45+
repository: '{{repl LocalRegistryNamespace }}'/cloudnative-pg/cloudnative-pg
46+
```
47+
48+
## Rewrite the Replicated SDK Image Name
49+
50+
**Example:**
51+
52+
```yaml
53+
# KOTS HelmChart custom resource
54+
apiVersion: kots.io/v1beta2
55+
kind: HelmChart
56+
metadata:
57+
name: samplechart
58+
spec:
59+
optionalValues:
60+
# Rewrite Replicated SDK image to local registry
61+
- when: 'repl{{ HasLocalRegistry }}'
62+
values:
63+
replicated:
64+
image:
65+
registry: '{{repl LocalRegistryHost }}'
66+
repository: '{{repl LocalRegistryNamespace }}/replicated-sdk'
67+
```
68+
69+
## Add a Pull Secret for Rate-Limited Docker Hub Images {#docker-secret}
70+
71+
Docker Hub enforces rate limits for Anonymous and Free users. 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.
72+
73+
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).
74+
75+
To support the use of the `kots docker ensure-secret` command, add the `APP_SLUG-kotsadm-dockerhub` pull secret (where `APP_SLUG` is your application slug) to any Docker images that could be rate-limited.
76+
77+
**Example:**
78+
79+
```yaml
80+
# kots.io/v1beta2 HelmChart custom resource
81+
apiVersion: kots.io/v1beta2
82+
kind: HelmChart
83+
metadata:
84+
name: samplechart
85+
spec:
86+
values:
87+
image:
88+
registry: docker.io
89+
repository: org-name/example-docker-hub-image
90+
# Add the dockerhub secret
91+
pullSecrets:
92+
- name: gitea-kotsadm-dockerhub
93+
```

0 commit comments

Comments
 (0)