Choose the Image Registry for a Workload Cluster
Alauda Container Platform installs and manages platform components on every workload cluster, such as Kube-OVN and the platform modules that are delivered after the cluster is up. By default, the images of these components come from the registry that the global cluster uses. Instead, you can bind a workload cluster to a registry of its own, for example a registry that is close to a workload cluster in another region.
Decide which registry credential the cluster uses before you create the cluster. You cannot replace the credential after creation, but you can update the address in it.
TOC
OptionsWhat the Binding CoversInherit the Registry of the global ClusterBind a Workload Cluster to Its Own RegistryBefore You StartStep 1 — Prepare the RegistryStep 2 — Create the RegistryCredential SecretStep 3 — Reference the Credential When You Create the ClusterStep 4 — Verify the BindingCheck the Registry Address on the global ClusterCheck the Images on the Workload ClusterCheck the Registry Configuration of the NodesOperate an Existing BindingTroubleshootingOptions
A dedicated registry requires platform v4.4.0 or later on every provider.
What the Binding Covers
The binding applies to:
- The platform components that Alauda Container Platform installs and manages on the workload cluster, such as Kube-OVN and the platform modules delivered to it.
- On Bare Metal, the OS image that the hosts are reinstalled with.
It does not apply to the following:
Inherit the Registry of the global Cluster
This is the default. Leave cluster.registrySecretRef out of install-config.yaml. ac reads the registry address from the registry key of the public-registry-credential Secret in cpaas-system on the global cluster. The key must exist even when the registry needs no authentication.
Check the key before you create the cluster:
Continue when the command prints the registry address of the global cluster, such as <host>:<port>. Otherwise, contact technical support.
See Add External Address for Built-in Registry only when all of the following apply:
- The
globalcluster was upgraded from an earlier version and still uses the platform built-in Registry. - The workload cluster nodes cannot reach that registry.
Bind a Workload Cluster to Its Own Registry
Before You Start
- You can create Secrets in the
cpaas-systemnamespace of theglobalcluster. - The dedicated registry is reachable from every workload cluster node.
- The dedicated registry already holds Alauda Container Platform Core for the target version, plus the packages of every platform plugin that you plan to install on this cluster. See Prepare the Registry.
Step 1 — Prepare the Registry
The platform never copies images into a dedicated registry. Populate the registry yourself before you create the cluster:
- Alauda Container Platform Core for the target version, matching the version and CPU architecture of the cluster.
- The packages of every platform plugin that you plan to install on this cluster. The platform does not add missing packages later.
- On Bare Metal, the OS images of every Kubernetes version that the cluster uses. Each time a host is reinstalled, it pulls its OS image from this registry; see Push the OS Images.
Upload with the same Core Package procedure that prepares an external platform image registry, and use the dedicated registry as the target address. See Prepare the Target-Version Payload.
Then check that the registry responds. Run the following commands on a host in the network of the workload cluster nodes:
Continue when the output is 200 or 401; otherwise, correct the network path or the TLS setup of the registry.
Before you create the cluster, confirm in the administration interface or API of the registry that the uploaded repositories and tags are complete. A cluster bound to an incomplete registry still reaches Ready. The gap appears later, when platform Pods stay in ImagePullBackOff. You cannot change the binding.
Step 2 — Create the RegistryCredential Secret
Create the credential as described in Create a Registry Credential. The credential holds the registry address and, when the registry requires authentication, the username and password.
Step 3 — Reference the Credential When You Create the Cluster
Name the Secret in cluster.registrySecretRef of install-config.yaml, then create the cluster as described in your provider's cluster creation guide:
ac checks the Secret before it applies anything. If a check fails, nothing is applied, and the error names the problem; see Troubleshooting.
The platform reads the credential binding only when the cluster is created. Changing the cpaas.io/registry-reference label on an existing Cluster has no effect. To use a different credential, recreate the cluster. Updating the address in the selected credential is supported.
Step 4 — Verify the Binding
Check the Registry Address on the global Cluster
Continue when the output is the Secret name followed by the registry address from the Secret; otherwise, see Troubleshooting.
Check the Images on the Workload Cluster
Continue when the platform component images use the dedicated registry. The images that kubeadm manages and the pause image do not use it; they come from elsewhere, as described in What the Binding Covers. If every platform component image still uses another registry, see Troubleshooting.
Check the Registry Configuration of the Nodes
Continue when the Registry status is ready and the platform component images use the dedicated registry.
Operate an Existing Binding
Update a credential with ac patch, not ac apply. Quote values that contain YAML special characters, because the patch file is YAML.
Keep the file private with chmod 600 registry-credential-patch.yaml, because it holds the password.