Alauda Container Platform

Registry v2: Image Registry Overview

Registry v2 is the Operator-managed integrated image registry for clusters. It provides internal image storage, ImageStream metadata, namespace-based access control, managed service account pull credentials, and image pruning.

TOC

Integrated Image RegistryWhat Changed from the Legacy RegistryCommon TermsAutomatic Image PruningCompatibility Notes

Integrated Image Registry

The registry runs as a cluster workload in image-registry-system. The image-registry Deployment serves OCI push and pull traffic, while image metadata is served through the aggregated image.alauda.io/v1 Image API.

Image data and image metadata are stored separately:

Data typeStorage location
Image blobs and manifestsThe storage backend configured in Config/cluster.spec.storage, such as PVC, S3-compatible storage, emptyDir, or another supported backend.
Image metadata Image API resources such as Image, ImageStream, ImageStreamTag, ImageStreamImage, and ImageSignature.

The registry integrates with authentication and Kubernetes authorization. Namespace RoleBindings control who can pull, push, delete, list, or prune image content.

What Changed from the Legacy Registry

AreaLegacy RegistryRegistry v2
Runtime namespaceCommonly cpaas-systemimage-registry-system
Internal service addressimage-registry.cpaas-system.svcimage-registry.image-registry-system.svc:5000
Lifecycle managementPlatform plugin or chart-managed Registry resourcesOLM and cluster-image-registry-operator
Desired statePlugin configuration and legacy Registry configurationconfigs.imageregistry.operator.alauda.io/cluster and imagepruners.imageregistry.operator.alauda.io/cluster
Image metadataRegistry HTTP view and legacy metadata APIsAggregated image.alauda.io/v1 Image API
External exposureLegacy ingress or gateway configurationConfig.spec.defaultRoute and Config.spec.routes[], rendered as Kubernetes Ingress
Pull credentialsLegacy service account pull secret automationBuilt-in Operator imagePullSecret controller
Image limitsLegacy Registry gateway ConfigMapKubernetes LimitRange and ResourceQuota with alauda.io image resources
Pruning and GCLegacy ac Registry commands and scriptsImagePruner/cluster, image-pruner CronJob, and ac adm prune images / ac adm registry gc

Common Terms

TermMeaning
Image repositoryA namespace-scoped collection of image tags and digests, addressed as <namespace>/<repository>:<tag>.
ImageStream Image API resource that records tag specifications and tag history for a repository.
ImageCluster-scoped image metadata for a digest.
ImagePrunerSingleton custom resource that configures scheduled prune jobs.
Managed pull secretA service account pull credential generated and injected by the Operator.
Registry storageThe backend that stores image blobs and manifests.

Automatic Image Pruning

Registry v2 uses imagepruners.imageregistry.operator.alauda.io/cluster to configure scheduled pruning. The Operator renders an image-pruner CronJob that runs ac adm prune images with the configured retention policy.

Pruning removes unused image metadata first. Registry garbage collection reclaims storage after metadata is removed.

Compatibility Notes

  • The legacy Registry how-to pages remain valid for environments that still use the legacy Registry.
  • Registry v2 Image API resources use the API groups image.alauda.io/v1 and imageregistry.operator.alauda.io/v1.
  • Registry v2 uses Image API resources such as Image, ImageStream, ImageStreamTag, and ImagePruner.
  • Use ac for Registry workflows.