Alauda Container Platform Registry Overview
Alauda Container Platform Registry stores container images for ACP 4.4 clusters. It manages ImageStream and ImageDigest metadata, controls access by namespace, provides service account pull credentials, and prunes unused images.
TOC
Components and Resource ScopeImage Storage and ImportsRepository NamesAccess and Request HandlingImage CleanupComponents and Resource Scope
The Image Registry Operator runs in image-registry-system. It manages Registry operand resources
in cpaas-system by default, including the image-registry and image-api-server Deployments,
Services, the node-ca DaemonSet, and the image-pruner CronJob.
The Operator records the actual operand namespace on Config/cluster:
If the namespace was customized, replace cpaas-system in commands and service addresses with the
returned value.
Config and ImagePruner use imageregistry.operator.alauda.io/v1. Use the public
image.alauda.io/v1 API for image metadata operations. The cluster-scoped digest resource is
imagedigests.image.alauda.io; ac get images lists repository and tag references instead.
Developers normally work with ImageStreams and their tag or digest views.
The Image API server stores metadata in internal CRDs under storage.image.alauda.io/v1alpha1.
Manage images through the public API. Creating, editing, or deleting internal CRD objects directly
bypasses validation, authorization, and tag and signature synchronization.
Image Storage and Imports
The backend in Config/cluster.spec.storage stores pushed image blobs and manifests. Kubernetes
stores the Image API metadata. Recovery requires both: a backup of the Registry PVC or object
storage does not include ImageStreams, image digests, or signature metadata. Back up the Registry
backend and the cluster state; see
Backing Up etcd.
ACP 4.4 supports emptyDir, PVC, S3-compatible storage, and node-local hostPath storage through a
PV/PVC. Use persistent storage for images that must be retained; emptyDir is for disposable
development data. Node-local storage requires a single Registry replica on the node that holds
the data. See Configure Registry storage.
Other storage types that appear in the API schema are outside the ACP 4.4 support scope.
Importing an external image into an ImageStream records its metadata and source reference. The layers stay in the source registry. Push or mirror the image to store it locally. See Managing images with ac.
Repository Names
Image repositories are namespace-scoped and use the following format:
Each repository maps to one ImageStream in the image namespace. The Registry rejects additional
repository path segments: registry.example.com/team-a/my-app:v1 is valid;
registry.example.com/team-a/backend/my-app:v1 is rejected.
Access and Request Handling
The Registry integrates with authentication and Kubernetes authorization.
RoleBindings in the image namespace control image access, including pulls by ServiceAccounts in
other namespaces. The authenticated /v2/_catalog endpoint lists repositories permitted by the
caller's ImageStream permissions; anonymous catalog access is not available. See
Grant namespace permissions.
To compare recorded identity claims on an ImageDigest, see Check Recorded Signature Identity.
Workloads use the internal service address image-registry.cpaas-system.svc:5000. For external
clients, configure a custom Registry hostname with DNS and a matching TLS certificate. See
Accessing the Registry and
Exposing the Registry.
Config/cluster.spec.readOnly rejects pushes, deletes, and Image API metadata changes while
allowing image reads. For read-only operation, request limits, and image quotas, see
Setting up and configuring the Registry.
Image Cleanup
In modern mode, ac adm prune images retains images younger than 60 minutes and three revisions per
tag by default. Manual runs leave --prune-registry disabled and remove only eligible Image API
metadata when confirmed. Set --prune-registry=true to also unlink eligible Registry manifests and
run garbage collection in a verified Registry Pod.
New installations enable the image-pruner schedule. The Operator honors
ImagePruner/cluster.spec.suspend and preserves an explicit true, including one set by an earlier
safety release. Online metadata pruning requires a writable Image API. Adding
--prune-registry=true also requires a writable Registry and Operator-managed Pod execution
permissions.
Deletion is irreversible. Online pruning does not stop concurrent writers, and new references can appear after a reference check but before deletion. It also cannot discover consumers outside the cluster.
Standalone full storage garbage collection removes unreferenced blobs, including old orphaned data whose inventory is unavailable. It requires read-only mode, isolated writers, and completed in-flight uploads. Deleting a tag alone does not immediately reclaim storage.
See Configure scheduled image pruning for the Operator-managed policy, or Prune images and Run Registry garbage collection for administrator-run cleanup.