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
{{ message }}
Repository navigation
Commit a535f93
Browse filesBrowse the repository at this point in the historyBrowse files
docs(air-gapped): improve registry mirrors for tenant Kubernetes (#461)
## Summary
- Clarify that tenant control plane (Kamaji) uses management cluster's
registry mirrors automatically, and only worker nodes need separate
configuration
- Add Option A showing how to configure registry mirrors via the
platform Package CR
- Add collapsible section with `kubectl patch` alternative for existing
deployments
- Add authentication example for containerd TOML configuration
- Add "How it works" section explaining the secret distribution
mechanism
- Fix per-cluster secret naming to match actual code
(`kubernetes-<cluster-name>-patch-containerd`)
## Test plan
- [x] Verify the page renders correctly with Hugo
- [x] Verify the collapsible `<details>` section renders properly with
code block inside
- [x] Verify all internal links work
(#2-configure-container-registry-mirrors anchor)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified air-gapped Kubernetes install flow: control planes inherit
registry mirrors automatically; worker nodes require separate mirror
configuration.
* Added two supported approaches for configuring worker node mirrors,
including an alternate method to patch an existing platform deployment.
* Documented authenticated mirror registry options and use of image pull
secrets.
* Added per-cluster mirror override support and precedence rules when
both global and per-cluster configs exist.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## 5. Configure Container Registry Mirrors for Tenant Kubernetes
152
152
153
-
To use registry mirrors, tenant Kubernetes clusters need to be configured separately,
154
-
although in the same way as the Talos nodes.
153
+
Tenant Kubernetes clusters in Cozystack use [Kamaji](https://kamaji.clastix.io/) for the control plane.
154
+
The control plane components run as pods on the management cluster nodes,
155
+
so they automatically use the registry mirrors configured in [step 2](#2-configure-container-registry-mirrors) for Talos.
156
+
157
+
However, tenant **worker nodes** run as separate virtual machines with their own containerd instance.
158
+
These worker nodes need a separate registry mirror configuration.
155
159
156
160
To perform this configuration, you first need to deploy a Cozystack cluster of
157
161
(or upgrade your cluster to) version v0.32.0 or later.
@@ -161,7 +165,124 @@ Check your current cluster version with:
161
165
kubectl get deploy -n cozy-system cozystack -oyaml | grep installer
162
166
```
163
167
164
-
Generate a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) named `patch-containerd` using the following example:
168
+
### Option A: Configure via platform package
169
+
170
+
The platform package can automatically generate the `patch-containerd` secret
171
+
from the `registries` section in the platform values.
172
+
173
+
Add the `registries` section to your **cozystack-platform.yaml**:
174
+
175
+
```yaml
176
+
apiVersion: cozystack.io/v1alpha1
177
+
kind: Package
178
+
metadata:
179
+
name: cozystack.cozystack-platform
180
+
spec:
181
+
variant: isp-full
182
+
components:
183
+
platform:
184
+
values:
185
+
# ... your existing publishing, networking, etc. ...
Alternatively, create a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) named `patch-containerd` directly:
165
286
166
287
```yaml
167
288
apiVersion: v1
@@ -208,12 +329,46 @@ stringData:
208
329
skip_verify = true
209
330
```
210
331
211
-
This secret will be copied for every tenant Kubernetes cluster deployed in Cozystack.
332
+
If your registry mirrors require authentication, add a custom `Authorization` header
333
+
with Base64-encoded credentials:
334
+
335
+
```toml
336
+
server = "https://registry-1.docker.io"
It's possible to configure registry mirrors for a particular tenant Kubernetes cluster:
356
+
The `patch-containerd` secret from the `cozy-system` namespace is automatically copied
357
+
to every tenant Kubernetes cluster namespace during deployment.
358
+
The secret data is mounted into worker node VMs as containerd registry configuration files
359
+
at `/etc/containerd/certs.d/<registry>/hosts.toml`.
214
360
215
-
- The tenant cluster must be deployed with a Kubernetes package version 0.23.1 or later, which is available since Cozystack 0.32.1.
216
-
- Before deploying the tenant cluster, create a Kubernetes Secret named `kubernetes-<cluster name>` with the same contents as shown above.
361
+
### Per-cluster configuration
362
+
363
+
It is possible to configure registry mirrors for a particular tenant Kubernetes cluster
364
+
instead of using the global `patch-containerd` secret:
365
+
366
+
- The tenant cluster must be deployed with a Kubernetes package version 0.23.1 or later, which is available since Cozystack 0.32.1.
367
+
- Before deploying the tenant cluster, create a Kubernetes Secret named `kubernetes-<cluster-name>-patch-containerd` in the tenant cluster namespace, using the same format as the examples above.
368
+
369
+
{{% alert color="warning" %}}
370
+
**Important:** If both the global `patch-containerd` secret and a per-cluster secret exist, the global secret takes precedence and the per-cluster secret is ignored. To use a per-cluster configuration, ensure that the global `patch-containerd` secret in the `cozy-system` namespace is not present.
371
+
{{% /alert %}}
217
372
218
373
To learn more about registry configuration values, read the [CRI Plugin configuration guide](
0 commit comments