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:

REGISTRY_NAMESPACE="$(kubectl get configs.imageregistry.operator.alauda.io cluster \
  -o jsonpath='{.metadata.annotations.imageregistry\.operator\.alauda\.io/operand-namespace}')" || exit 1
test -n "$REGISTRY_NAMESPACE" || {
  echo "The Registry operand namespace binding is missing." >&2
  exit 1
}
printf 'Registry operand namespace: %s\n' "$REGISTRY_NAMESPACE"

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.

Main Components

ComponentPurpose
cluster-image-registry-operator DeploymentReconciles the singleton Registry from Config/cluster and ImagePruner/cluster.
image-registry DeploymentServes OCI push and pull traffic, authentication, authorization, storage access, health checks, and metrics.
image-api-server DeploymentProcesses public Image API requests, including image metadata, tag resolution, imports, and namespace image limits.
node-ca DaemonSetDistributes Registry CA trust and Registry service host mappings to nodes.
image-pruner CronJobRuns online image pruning according to the retention policy and ImagePruner.spec.suspend.
Managed imagePullSecret controllerCreates, injects, refreshes, and removes service account pull secrets for the internal registry.

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 kubectl version 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

  1. Log in to and navigate to the Administrator page.
  2. In the left navigation bar, click Marketplace > OperatorHub.
  3. Search for Alauda Container Platform Registry or cluster-image-registry-operator.
  4. Click Install.
  5. On the installation page, use the following settings unless your release guidance states otherwise:
ParameterRecommended value
Channelstable
Installation ModeAll namespaces on the cluster
Namespaceimage-registry-system
Upgrade StrategyManual
  1. Click Install.
  2. If an approval prompt appears, review and approve the generated install plan.
  3. Wait until the Operator status is Installed.

Verify the installation:

kubectl -n image-registry-system get subscription,csv,installplan
kubectl -n image-registry-system get deployment cluster-image-registry-operator

Expected results:

  • The installed CSV is Succeeded.
  • The cluster-image-registry-operator Deployment 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:

admission webhook "check-subscription.cpaas.io" denied the request:
packagemanifests.packages.operators.coreos.com "cluster-image-registry-operator" not found

Verify the package before continuing:

kubectl -n cpaas-system get packagemanifests | grep cluster-image-registry-operator

If the package is missing, follow the platform's Operator package upload procedure to upload it. For example:

violet push '<operator-package-file>' \
  --platform-address="https://<platform-host>" \
  --platform-username="<platform-admin-user>" \
  --platform-password="<platform-admin-password>" \
  --target-catalog-source=platform \
  --dest-repo="<global-registry-address>" \
  --username="<registry-user>" \
  --password="<registry-password>"
PlaceholderDescription
<operator-package-file>Local path to the released Alauda Container Platform Registry Operator package for the target cluster's architecture. Use the supplied archive filename.
<platform-host>ACP management platform hostname or IP address and optional port. The example supplies the https:// scheme.
<platform-admin-user>, <platform-admin-password>Credentials of an administrator permitted to upload packages to the platform catalog.
<global-registry-address>Existing platform registry host and optional port, such as registry.example.com:11443, without a scheme or repository path. This registry stores the installation images and must already be available.
<registry-user>, <registry-password>Credentials with push permission on the repositories that store installation images in the existing registry.

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:

kubectl get namespace image-registry-system >/dev/null 2>&1 || \
  kubectl create namespace image-registry-system

kubectl label namespace image-registry-system \
  cpaas.io/project=cpaas-system \
  pod-security.kubernetes.io/audit=privileged \
  pod-security.kubernetes.io/enforce=privileged \
  pod-security.kubernetes.io/warn=privileged \
  --overwrite

Create a file named image-registry-operator-subscription.yaml:

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  annotations:
    cpaas.io/target-namespaces: ""
  name: cluster-image-registry-operator
  namespace: image-registry-system
spec:
  channel: stable
  installPlanApproval: Manual
  name: cluster-image-registry-operator
  source: platform
  sourceNamespace: cpaas-system

Apply the Subscription:

kubectl apply -f image-registry-operator-subscription.yaml

Approve the generated InstallPlan:

kubectl -n image-registry-system get installplan

kubectl -n image-registry-system patch installplan '<installplan-name>' \
  --type=merge \
  -p '{"spec":{"approved":true}}'

Wait for the Operator:

kubectl -n image-registry-system wait \
  --for=condition=Available \
  deployment/cluster-image-registry-operator \
  --timeout=300s

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.

  1. Wait for the Operator to create Config/cluster, then inspect its namespace binding and storage:

    kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml

    If the configuration is missing, check the Operator Pod and retry after it starts. For image pull authorization errors, use Repair Workload Image Pulls.

  2. Review the scheduled pruning policy before activating the Registry. New installations default to spec.suspend: false. Temporarily set it to true while configuring storage and reviewing retention, and keep it suspended through activation.

  3. 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.

  4. Wait for both deployments to appear, then verify the Registry and Image API:

    kubectl -n "$REGISTRY_NAMESPACE" get deployment image-registry image-api-server
    kubectl -n "$REGISTRY_NAMESPACE" rollout status deployment/image-registry --timeout=300s
    kubectl -n "$REGISTRY_NAMESPACE" rollout status deployment/image-api-server --timeout=300s
    kubectl wait --for=condition=Available apiservice/v1.image.alauda.io --timeout=300s
    kubectl api-resources --api-group=image.alauda.io --cached=false
    kubectl get imagedigests.image.alauda.io
    kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml

Expected results:

  • Both deployments are available, and APIService/v1.image.alauda.io is Available=True.
  • Public API discovery includes cluster-scoped imagedigests and namespaced imagestreams, imagestreamtags, and imagestreamimages. The ImageDigest query succeeds; a new Registry can return no objects.
  • Config/cluster.spec.managementState is Managed; its conditions report Available=True, Progressing=False, and Degraded=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:

kubectl -n '<pod-namespace>' describe pod '<failing-pod>'
kubectl -n '<pod-namespace>' get pod '<failing-pod>' \
  -o jsonpath='{.spec.serviceAccountName}{"\n"}'
kubectl -n '<pod-namespace>' get serviceaccount '<service-account>' \
  -o jsonpath='{.imagePullSecrets[*].name}{"\n"}'
kubectl -n '<pod-namespace>' get secret '<platform-pull-secret>'
PlaceholderSource
<pod-namespace>Namespace of the failing Pod: normally image-registry-system for the Operator, or the recorded operand namespace for Registry workloads.
<failing-pod>Pod reporting the pull error in that namespace. List Pods with kubectl -n <pod-namespace> get pods.
<service-account>The failing Pod's spec.serviceAccountName, returned above.
<platform-pull-secret>Existing image pull Secret supplied by the platform registry administrator. It must be in the Pod's namespace and allow pulling the image named in the Pod event. A Secret in another namespace cannot be referenced.
<workload>The failing Pod's owning workload: deployment/cluster-image-registry-operator, deployment/image-registry, deployment/image-api-server, or daemonset/node-ca.

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:

kubectl -n '<pod-namespace>' patch serviceaccount '<service-account>' \
  --type=strategic -p '{"imagePullSecrets":[{"name":"<platform-pull-secret>"}]}'
kubectl -n '<pod-namespace>' rollout restart '<workload>'
kubectl -n '<pod-namespace>' rollout status '<workload>' --timeout=300s

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.

kubectl -n image-registry-system get subscription,csv
kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml
kubectl -n "$REGISTRY_NAMESPACE" rollout status deployment/image-registry --timeout=300s
kubectl -n "$REGISTRY_NAMESPACE" rollout status deployment/image-api-server --timeout=300s
kubectl api-resources --api-group=image.alauda.io --cached=false

Set the Subscription approval strategy to Manual before making a new Operator package available:

kubectl -n image-registry-system get subscription
kubectl -n image-registry-system patch subscription '<subscription-name>' \
  --type=merge \
  -p '{"spec":{"installPlanApproval":"Manual"}}'
PlaceholderDescription
<subscription-name>Subscription for the Alauda Container Platform Registry Operator. Use the name returned by kubectl -n image-registry-system get subscription.

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:

PLAN_NAME="$(kubectl -n image-registry-system get subscription '<subscription-name>' \
  -o jsonpath='{.status.installPlanRef.name}')"
kubectl -n image-registry-system get installplan "$PLAN_NAME" -o yaml
kubectl -n image-registry-system patch installplan "$PLAN_NAME" \
  --type=merge \
  -p '{"spec":{"approved":true}}'

Wait for the new CSV and Operator Deployment, then check the Registry workloads and configuration:

kubectl -n image-registry-system get subscription,csv,installplan
kubectl -n image-registry-system rollout status deployment/cluster-image-registry-operator --timeout=300s
kubectl -n "$REGISTRY_NAMESPACE" rollout status deployment/image-registry --timeout=300s
kubectl -n "$REGISTRY_NAMESPACE" rollout status deployment/image-api-server --timeout=300s
kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml
kubectl get imagepruners.imageregistry.operator.alauda.io cluster -o yaml

Expected results:

  • The new CSV is Succeeded and the Subscription reports the new installed CSV.
  • cluster-image-registry-operator, image-registry, and image-api-server are available.
  • Existing storage, routes, compatible Image API metadata, and ImagePruner configuration remain reconciled.
  • An existing explicit ImagePruner.spec.suspend: true remains suspended, including values from earlier safety releases. Review the policy and generated online command before setting it to false.
  • Config/cluster reports Available=True, Progressing=False, and Degraded=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:

kubectl patch configs.imageregistry.operator.alauda.io cluster \
  --type=merge \
  -p '{"spec":{"managementState":"Managed"}}'

Verify that the Registry data plane is available:

kubectl -n "$REGISTRY_NAMESPACE" rollout status deployment/image-registry --timeout=300s
kubectl -n "$REGISTRY_NAMESPACE" rollout status deployment/image-api-server --timeout=300s
kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml

Expected result:

  • Config/cluster reports Available=True, Progressing=False, and Degraded=False.

Warning: Setting the management state to Removed stops the Registry runtime components. Push and pull traffic and the Image API server become unavailable. emptyDir data is lost when the Registry Pods are removed, even if storage management is Unmanaged. 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:

kubectl get configs.imageregistry.operator.alauda.io cluster \
  -o jsonpath='{.spec.storage}{"\n"}'

To retain a persistent backend, set its storage management state to Unmanaged before removal:

kubectl patch configs.imageregistry.operator.alauda.io cluster \
  --type=merge -p '{"spec":{"storage":{"managementState":"Unmanaged"}}}'
kubectl get configs.imageregistry.operator.alauda.io cluster \
  -o jsonpath='{.spec.storage.managementState}{"\n"}'

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:

kubectl patch configs.imageregistry.operator.alauda.io cluster \
  --type=merge \
  -p '{"spec":{"managementState":"Removed"}}'

Verify that the data-plane deployments are removed:

kubectl -n "$REGISTRY_NAMESPACE" get deployment image-registry image-api-server --ignore-not-found

Expected result:

  • The image-registry and image-api-server Deployments 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.

kubectl -n image-registry-system get subscription,csv,installplan
kubectl -n image-registry-system get deploy cluster-image-registry-operator
kubectl -n "$REGISTRY_NAMESPACE" get deploy image-registry image-api-server
kubectl -n "$REGISTRY_NAMESPACE" get daemonset node-ca
kubectl -n "$REGISTRY_NAMESPACE" get cronjob image-pruner
kubectl get apiservice v1.image.alauda.io
kubectl get apiservice v1.image.alauda.io \
  -o jsonpath='{.spec.service.namespace}{"/"}{.spec.service.name}{":"}{.spec.service.port}{"\n"}'
kubectl api-resources --api-group=image.alauda.io --cached=false
kubectl get imagedigests.image.alauda.io
kubectl get imagestreams.image.alauda.io -A
kubectl get imagesignatures.image.alauda.io
kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml
kubectl get imagepruners.imageregistry.operator.alauda.io cluster -o yaml

Expected results:

  • The Operator CSV is Succeeded.
  • cluster-image-registry-operator, image-registry, and image-api-server are available.
  • node-ca is ready on target nodes.
  • APIService/v1.image.alauda.io is Available=True.
  • The APIService backend is <operand-namespace>/image-api-server:443, where <operand-namespace> is the namespace recorded on Config/cluster.
  • Discovery exposes imagedigests as ImageDigest at cluster scope. The public metadata queries succeed, even when they return no objects.
  • Config/cluster reports Available=True, Progressing=False, and Degraded=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:

kubectl -n "$REGISTRY_NAMESPACE" get pods -l app.kubernetes.io/name=image-registry

View Registry logs:

kubectl -n "$REGISTRY_NAMESPACE" logs deployment/image-registry -c registry

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:

for SA in prometheus-sa vm-sa; do
  printf '%s: ' "${SA}"
  kubectl create -f - --validate=false -o jsonpath='{.status.allowed}{"\n"}' <<EOF
{
  "apiVersion": "authorization.k8s.io/v1",
  "kind": "SubjectAccessReview",
  "spec": {
    "user": "system:serviceaccount:cpaas-system:${SA}",
    "resourceAttributes": {
      "verb": "get",
      "group": "image.alauda.io",
      "resource": "registry",
      "subresource": "metrics"
    }
  }
}
EOF
done

--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 true when the named identity has metrics access. If it prints false, 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:

kubectl -n cpaas-system get serviceaccount prometheus-sa vm-sa
kubectl get clusterrolebinding registry-monitoring -o yaml
kubectl -n "$REGISTRY_NAMESPACE" get servicemonitor image-registry
kubectl -n image-registry-system get servicemonitor image-registry-operator

For a custom operand namespace, query the image-registry ServiceMonitor there. Verify that the monitoring targets are healthy before relying on collected metrics.

Common Operator Issues

SymptomCheck
CSV is not SucceededSubscription, InstallPlan, CSV events, and the cpaas-system catalog source.
Config/cluster is Degraded=TrueConfig.status.conditions, Operator logs, Registry Pod events, storage, TLS Secret, and RBAC.
Registry Pod is pendingPVC binding, node resources, node selectors, taints, tolerations, and topology constraints.
node-ca is not readyDaemonSet scheduling, Pod logs, node trust configuration, and host mapping updates.