Alauda Container Platform Registry
The Image Registry Operator installs and manages the cluster-wide Alauda Container Platform Registry.
It reconciles Registry runtime resources from Config/cluster and scheduled pruning
resources from ImagePruner/cluster.
The Operator runs in image-registry-system. Registry operands, storage, and TLS Secrets use
cpaas-system by default. Once installation creates Config/cluster, read the operand namespace
before running commands against those resources:
Use REGISTRY_NAMESPACE for operand commands. The platform CatalogSource and monitoring
ServiceAccounts use the platform namespace, cpaas-system. Run namespace discovery first and keep
REGISTRY_NAMESPACE in the same shell for later commands.
TOC
Main ComponentsInstall Alauda Container Platform RegistryPrerequisitesInstall from OperatorHubInstall by Using YAMLPrerequisitesActivate the RegistryRepair Workload Image PullsUpgrade Alauda Container Platform RegistryChange the Registry Management StateImage Pruner ReconciliationCheck Operator and Registry StatusCheck Registry Logs and Metrics AccessCommon Operator IssuesMain Components
The Operator publishes the Image API as image.alauda.io/v1 through the Kubernetes API server.
It manages the APIService registration and internal metadata storage resources. Use the public
Image API or ac for image operations. Do not manage images through internal storage CRDs.
Install Alauda Container Platform Registry
When the Operator package is available in OperatorHub, install the Image Registry Operator from the web console to deploy Alauda Container Platform Registry. Use YAML only for controlled automation or support-guided installation when the web console is unavailable.
Both installation methods require the cluster-image-registry-operator package in the target
CatalogSource. See Install by Using YAML to verify the package and upload
it if needed.
Prerequisites
- You have cluster administrator access to the target ACP 4.5 cluster.
- Use a
kubectlversion compatible with the cluster. Run commands from an administrator workstation with the target cluster context selected. - The Registry operand namespace exists. The default is
cpaas-system; the Operator does not create it. - Prepare a persistent storage backend and its credentials before activating the Registry.
Install from OperatorHub
- Log in to and navigate to the Administrator page.
- In the left navigation bar, click Marketplace > OperatorHub.
- Search for Alauda Container Platform Registry or
cluster-image-registry-operator. - Click Install.
- On the installation page, use the following settings unless your release guidance states otherwise:
- Click Install.
- If an approval prompt appears, review and approve the generated install plan.
- Wait until the Operator status is Installed.
Verify the installation:
Expected results:
- The installed CSV is
Succeeded. - The
cluster-image-registry-operatorDeployment is available.
Continue with Activate the Registry.
Install by Using YAML
Prerequisites
The target CatalogSource must contain the cluster-image-registry-operator package. A fresh
platform installation does not include it. If the package is missing, the
check-subscription.cpaas.io admission webhook rejects the Subscription:
Verify the package before continuing:
If the package is missing, follow the platform's Operator package upload procedure to upload it. For example:
Use a registry account with push permission on the target repositories. A pull-only account fails
with requested access to the resource is denied. Uploading the package does not configure image
pull credentials for the Operator's workloads. If those pulls fail, use the workload image pull
repair procedure below.
Create the installation namespace if it does not exist:
Create a file named image-registry-operator-subscription.yaml:
Apply the Subscription:
Approve the generated InstallPlan:
Wait for the Operator:
Continue with Activate the Registry.
Activate the Registry
Complete this procedure after either installation method. On a fresh ACP installation without a
configured storage backend, the Operator creates Config/cluster with managementState: Removed.
It creates the Registry and Image API deployments once storage is configured and the state is
Managed.
-
Wait for the Operator to create
Config/cluster, then inspect its namespace binding and storage:If the configuration is missing, check the Operator Pod and retry after it starts. For image pull authorization errors, use Repair Workload Image Pulls.
-
Review the scheduled pruning policy before activating the Registry. New installations default to
spec.suspend: false. Temporarily set it totruewhile configuring storage and reviewing retention, and keep it suspended through activation. -
Configure PVC storage or S3-compatible storage. These examples also set
managementState: Managed. If the backend is already configured, use Change the Registry Management State to enable it. -
Wait for both deployments to appear, then verify the Registry and Image API:
Expected results:
- Both deployments are available, and
APIService/v1.image.alauda.ioisAvailable=True. - Public API discovery includes cluster-scoped
imagedigestsand namespacedimagestreams,imagestreamtags, andimagestreamimages. The ImageDigest query succeeds; a new Registry can return no objects. Config/cluster.spec.managementStateisManaged; its conditions reportAvailable=True,Progressing=False, andDegraded=False.
After activation and policy review, follow Configure scheduled image pruning to verify the generated online command and enable the schedule.
Repair Workload Image Pulls
Use this procedure when a Pod reports ImagePullBackOff and its events show an image authentication
or authorization error. An empty ServiceAccount imagePullSecrets list alone does not prove a
problem: the node runtime might already have working credentials.
Inspect the failing Pod and identify its ServiceAccount:
If the required Secret is missing from that ServiceAccount, add it with a strategic merge patch.
This preserves existing imagePullSecrets references. Restart only the affected workload:
Verify that existing Secret references remain and replacement Pods become ready. If pulling still fails, ask the registry administrator to check the image path and the credentials' repository permissions.
Upgrade Alauda Container Platform Registry
Upgrade Alauda Container Platform Registry by upgrading the Image Registry Operator through
OperatorHub. The Operator upgrade updates the cluster-image-registry-operator Deployment and then
reconciles the existing Config/cluster, ImagePruner/cluster, Registry, Image API, and supporting
resources.
These steps require a compatible ImageDigest storage model. Before upgrading, confirm that the Registry is healthy and that the current and target releases use compatible image metadata resources. The Operator does not automatically rename or copy objects between different metadata storage resources. If an earlier preview uses a different schema, obtain a supported migration plan before approving an InstallPlan.
Important: For Alauda Container Platform Registry versions earlier than
v4.4, contact technical support for upgrade and migration plans.
Set the Subscription approval strategy to Manual before making a new Operator package available:
Make the target Operator package available in Administrator > Marketplace > OperatorHub. If the package is not present, follow the platform's Operator package upload procedure before continuing.
In OperatorHub, open Alauda Container Platform Registry, select the target channel and version,
and review the pending upgrade. Approve the generated InstallPlan only after verifying that the
Subscription uses Manual approval:
Wait for the new CSV and Operator Deployment, then check the Registry workloads and configuration:
Expected results:
- The new CSV is
Succeededand the Subscription reports the new installed CSV. cluster-image-registry-operator,image-registry, andimage-api-serverare available.- Existing storage, routes, compatible Image API metadata, and ImagePruner configuration remain reconciled.
- An existing explicit
ImagePruner.spec.suspend: trueremains suspended, including values from earlier safety releases. Review the policy and generated online command before setting it tofalse. Config/clusterreportsAvailable=True,Progressing=False, andDegraded=False.
If the upgraded Operator Pod reports an image pull authorization error, follow Repair Workload Image Pulls. Check the Pod's ServiceAccount and preserve existing Secret references when adding a missing credential.
Do not delete the Subscription, Config/cluster, storage objects, or Image API metadata as part of
an Operator upgrade. If the upgrade does not complete, inspect the Subscription, InstallPlan, CSV
events, Operator logs, and Config/cluster.status.conditions before taking further action.
Change the Registry Management State
Configure one supported storage backend before enabling the Registry. When
Config/cluster.spec.storage is empty, setting managementState to Managed leaves the Operator in
StorageNotConfigured and prevents it from reconciling the Registry workloads.
Enable the Registry by setting Config/cluster.spec.managementState to Managed:
Verify that the Registry data plane is available:
Expected result:
Config/clusterreportsAvailable=True,Progressing=False, andDegraded=False.
Warning: Setting the management state to
Removedstops the Registry runtime components. Push and pull traffic and the Image API server become unavailable.emptyDirdata is lost when the Registry Pods are removed, even if storage management isUnmanaged. With managed persistent storage, removal can delete the PVC or object storage data; managed S3 removal deletes the objects and bucket. Use this state only during a maintenance window or for support-guided recovery.
Before switching to Removed, back up required image data and metadata, stop image writers, and
suspend scheduled pruning.
Wait for any active pruning Job to finish. Inspect the storage configuration:
To retain a persistent backend, set its storage management state to Unmanaged before removal:
Expected result: Unmanaged. This prevents the Operator from deleting persistent backend resources;
it does not preserve emptyDir. A PV reclaim policy governs data after PVC deletion and does not
protect an object storage bucket from explicit deletion.
To stop the Registry, set the management state to Removed:
Verify that the data-plane deployments are removed:
Expected result:
- The
image-registryandimage-api-serverDeployments are not present while the Registry is removed.
Image Pruner Reconciliation
The Operator reconciles the singleton ImagePruner/cluster into an image-pruner CronJob in the
Registry operand namespace (cpaas-system by default). Configure the retention policy in the
ImagePruner resource. See Setting up and configuring the registry.
New installations default to spec.suspend: false. The Operator honors explicit true and false
and preserves an existing explicit true, including values from earlier safety releases.
Suspension prevents new scheduled Jobs; it does not stop an existing Job.
Generated Jobs use modern mode with explicit confirmation, retention, and Registry cleanup
arguments. For a managed Registry, the Job passes --prune-registry=true and the bound internal
Registry URL. When the Registry is Removed or Unmanaged, it passes --prune-registry=false for
metadata-only pruning. Online cleanup unlinks eligible Registry manifests and runs garbage
collection in a verified Registry Pod.
The Operator grants the pruner ServiceAccount the required Pod execution, Service, and EndpointSlice
permissions through the namespace-scoped image-registry-pruner-gc RoleBinding in the operand
namespace. These RBAC rules apply across the namespace. Before GC, the CLI validates the Registry
Service selector, Ready EndpointSlice, and Pod.
The Operator suspends an old Job template that lacks the required modern command safeguards before
reconciliation can fail on other prerequisites. It reports Scheduled=False with reason ScheduledGCUnsafe
until it can safely regenerate the template. The replacement honors spec.suspend. Reconciliation
does not routinely suspend supported online templates. If safety suspension fails, inspect the
Degraded condition with reason SuspensionFailed and the Operator logs.
The Operator does not create or write an image-pruner-state ConfigMap. It retains existing objects
with that name for compatibility, but current cleanup does not use them. Job retries use the
Kubernetes backoffLimit and rerun the current image and workload scan. See
Prune images for online cleanup behavior. The
standalone Registry garbage collection
command remains a separate maintenance procedure with read-only mode and writer isolation.
Check Operator and Registry Status
These checks assume Config/cluster.spec.managementState is set to Managed, as described in
Change the Registry Management State.
Fresh ACP installations without configured storage start in an explicit Removed state. In that
state, Available=True with reason Removed means removal is complete. To verify an active
Registry, check both the management state and workload readiness.
Expected results:
- The Operator CSV is
Succeeded. cluster-image-registry-operator,image-registry, andimage-api-serverare available.node-cais ready on target nodes.APIService/v1.image.alauda.ioisAvailable=True.- The APIService backend is
<operand-namespace>/image-api-server:443, where<operand-namespace>is the namespace recorded onConfig/cluster. - Discovery exposes
imagedigestsasImageDigestat cluster scope. The public metadata queries succeed, even when they return no objects. Config/clusterreportsAvailable=True,Progressing=False, andDegraded=False.
APIService availability checks connectivity to the Image API server. Discovery and resource queries also check the public resource path and metadata backend. Verify Registry blob availability separately by pushing or pulling the required images.
Check Registry Logs and Metrics Access
Check Registry Pods:
View Registry logs:
To check metrics access, use an administrator account that can create SubjectAccessReviews.
registry/metrics is an RBAC-only resource, so specify its API group, resource, and subresource
explicitly. Submit JSON with the standard resource command:
--validate=false skips the client's local schema check. The API server still validates the request
and enforces RBAC. The command uses the selected cluster context and its configured API proxy path.
Expected result:
- Each review prints
truewhen the named identity has metrics access. If it printsfalse, inspect the live RBAC configuration. Omit the output option to inspect the full review response.
When the monitoring APIs are available, the Operator creates the registry-monitoring ClusterRole
and ClusterRoleBinding. The binding grants registry/metrics access to prometheus-sa and vm-sa
in the platform namespace, cpaas-system. It does not create those ServiceAccounts.
A review checks an identity's authorization. Check separately that the ServiceAccount exists and metrics are being collected:
For a custom operand namespace, query the image-registry ServiceMonitor there. Verify that the
monitoring targets are healthy before relying on collected metrics.