Setting Up and Configuring the Registry
Configure storage, request limits, service account pull credentials, image limits, and scheduled cleanup for Alauda Container Platform Registry.
TOC
PrerequisitesConfigure Registry AuthenticationPrepare Private Image ImportsBefore Configuring StorageConfigure Development StorageConfigure PVC StorageUse hostPath-backed StorageConfigure S3-Compatible StorageConfigure Request HandlingConfigure HTTP TimeoutsEnable Read-Only ModeOther Runtime SettingsConfigure Managed Service Account Pull SecretsConfigure Image LimitsConfigure Scheduled Image PruningOperate StoragePrerequisites
- The Image Registry Operator is installed, and it has created
Config/cluster. - Run commands from an administrator workstation with
kubectlconfigured for the target ACP 4.5 cluster. - You have permission to update
configs.imageregistry.operator.alauda.io,imagepruners.imageregistry.operator.alauda.io,LimitRange,ResourceQuota, and related Kubernetes resources. - For persistent storage, prepare the storage backend and required credentials before configuring
Config/cluster. - Before configuring runtime behavior or image limits, complete Registry activation.
The Operator runs in image-registry-system and manages Registry resources in cpaas-system by
default. Confirm the operand namespace before running commands:
If the returned namespace differs, replace cpaas-system in Registry commands and YAML manifests.
Storage Secrets, CA ConfigMaps, PVCs, and Registry workloads belong in this namespace. Use workload
namespaces such as team-a when configuring application image access or limits. Run the remaining
commands in the same shell to retain REGISTRY_NAMESPACE.
Configure Registry Authentication
The Registry discovers the platform OIDC configuration at runtime by default. Set spec.auth.oidc.ldapID to
choose the ACP identity provider for basic login. Leave runtime discovery enabled unless platform
guidance requires static authentication settings:
Verify the authentication settings and Registry rollout:
Expected results:
runtimeDiscoveryistrue.ldapIDis the supplied identity provider ID when one was configured; otherwise it is absent.- The Registry rollout completes successfully. The effective configuration reports
Available=True,Progressing=False, andDegraded=False.
Prepare Private Image Imports
Create the private source registry's pull Secret in the destination image namespace before importing. The Image API server reads credentials from this namespace. Import requests do not include the CLI's local authentication file.
-
Obtain a source registry account with read access to the required repository. Confirm that the Image API server can reach the source endpoint and trusts its certificate.
-
Follow the Creating a container registry type Secret procedure in Configuring Secrets. Specify
--namespace=team-awhen running the creation command for this example. Use the source registry host and its credentials, and select the container registry credential type. -
Verify the Secret metadata without displaying its credentials:
Replace
<source-pull-secret>with the name used in step 2. The Secret must use the registry credential type created by that procedure, contain credential data, and not havealauda.io/image.excludeSecret: "true". A generic or basic-auth Secret is not an import credential. -
From a client authenticated to the target cluster, preview an import to verify source access:
Replace team-a with the destination image namespace and the source reference with an existing
image that the account can read. The preview must report Success in the STATUS column; it does
not persist the ImageStream change. If it fails, check the source reference, namespace credentials,
source permissions, and connectivity from the Image API server. Continue with
Manage ImageStreams to persist the import.
Before Configuring Storage
ACP 4.5 supports the following storage configurations:
Configure exactly one backend. Other storage fields in the API schema are outside the ACP 4.5
support scope. The examples set unused backends to null to remove earlier selections.
Warning: The storage examples configure a new Registry. Changing a backend, PVC claim, or bucket does not migrate existing blobs or Image API metadata. Before replacing storage, back up both, suspend scheduled pruning, wait for active cleanup Jobs to finish, and stop image writers. Complete a validated data migration before switching the configuration or discarding the old storage. Replacing
emptyDircan permanently lose its data.
Inspect the current backend before choosing a procedure:
Configure Development Storage
Warning: Removing the Registry Pod from its node deletes its
emptyDirimage data. Use this storage only with one Registry replica in development or test environments where the data can be discarded. Production environments and images that must be retained require persistent storage.
Patch Config/cluster. The null fields remove mutually exclusive storage backends from the current configuration:
Verify the configuration and rollout:
Expected results:
Config/clusterreportsAvailable=True,Progressing=False, andDegraded=False.- The
image-registryDeployment rolls out successfully.
Configure PVC Storage
This example uses ReadWriteOnce storage with one Registry replica. The Operator requires the
Recreate rollout strategy for RWO storage.
Warning: For an existing Registry, complete the storage replacement preparation before changing its backend or claim. The patch below does not copy existing image data.
Create image-registry-pvc.yaml with a dedicated user-managed claim name. The Operator reserves
the names image-registry and image-registry-storage.
Apply the PVC:
Patch Config/cluster to use the PVC. The merge patch preserves other Config/cluster.spec fields,
including routes and pull-secret settings. Its null values remove the other storage backends:
Verify the PVC, configuration, and rollout:
Expected results:
- The
registry-dataPVC isBound. Config/clusterreportsAvailable=True,Progressing=False, andDegraded=False.- The
image-registryDeployment rolls out successfully.
Use hostPath-backed Storage
Ask the storage administrator to provide a dedicated hostPath-backed PV and a PVC in the Registry
operand namespace. The PV must have node affinity for the node that holds the data, and its
directory must be writable by the Registry container's user and group. Confirm that the PVC is
Bound before activating the Registry. Inspect the volume and node affinity:
Follow Configure PVC storage, using this claim instead of creating the
example claim. Keep spec.replicas: 1 and spec.rolloutStrategy: Recreate. Verify that the Registry
Pod runs on the PV's node and that the Deployment rolls out successfully:
The Config API has no separate storage.hostPath field. Node-local data is unavailable when its
node fails and does not follow a Pod to another node. Back up the data outside that node.
Configure S3-Compatible Storage
Warning: For an existing Registry, complete the storage replacement preparation before changing the backend or bucket. Updating storage credentials can also affect the active backend. The following procedure configures new storage and does not migrate existing images.
Create the storage Secret before configuring Config/cluster. The Operator merges this
user-managed Secret into the Registry's private configuration:
Verify the Secret without printing its contents:
Expected results:
- The Secret exists in the Registry operand namespace.
- Both key-presence checks return
true. Do not continue if either key is missing or empty. The template checks the required keys without printing or decoding their values.
Set disableRedirect: true to serve all content through the Registry when clients cannot reach the
object storage endpoint directly.
If the S3 endpoint uses a private CA, create the referenced ConfigMap with the required key:
Verify the ConfigMap key without displaying the certificate:
Expected result:
- The command returns a non-zero byte count for
ca-bundle.crt.
Patch Config/cluster. The null fields remove mutually exclusive storage backends from the current configuration:
HostPath-backed storage uses pvc; the other supported backend fields are emptyDir and s3.
Verify the configuration and rollout:
Expected results:
Config/clusterreportsAvailable=True,Progressing=False, andDegraded=False.- The Registry logs do not show storage authentication, bucket, endpoint, or certificate errors.
Configure Request Handling
Use Config/cluster.spec.requests to limit concurrent reads and writes, queued requests, and queue
wait time for each Registry replica:
Verify request handling settings and the rollout:
Expected results:
Config/cluster.spec.requestscontains the requested values.- The Registry Deployment rolls out successfully.
Configure HTTP Timeouts
Set server timeouts with non-negative Go durations such as 30m or 60s. A value of 0s disables
that timeout.
To set the default values explicitly:
Expected result: the configured durations are present and the Deployment is available. The request-header timeout is fixed at 5 seconds. Also check Ingress timeouts for external traffic. The Ingress read timeout limits the interval between upstream reads. Increasing it does not extend the Registry server's request deadlines.
Enable Read-Only Mode
Set spec.readOnly: true to reject Registry pushes, deletes, and Image API changes during
maintenance. This includes tag changes, imports, mappings, and signature writes. Authorized reads
remain available. The Operator applies this setting when Config/cluster.spec.managementState is
Managed.
Warning: Online image pruning, including metadata-only pruning, requires writes. Leave read-only mode disabled for ordinary pruning; no maintenance window is required. Full storage garbage collection requires this read-only procedure as well as writer isolation and upload draining. Follow Run Registry garbage collection.
Enable read-only mode and record the requested configuration generation. Wait for the Operator to observe that generation and reconcile without a degraded condition before checking the rollout:
Expected result: true. Authorized reads succeed; pushes and Image API changes receive read-only
rejections. Wait for the Pod rollout, then check every Registry Pod to confirm that the setting has
taken effect:
Continue only when Pods are present, every row contains {enabled: true}, and the deletion timestamp
column is empty. Repeat the check while old Pods are terminating. Keep writers paused until
in-flight requests have finished and no old writable Registry Pod remains.
After maintenance, restore writes and wait for the corresponding reconciliation before resuming writers or pruning:
Repeat the Pod check above. Before resuming writers or pruning, Pods must be present, the deletion timestamp column must be empty, and the read-only value column must be empty in every row. If any check fails, keep writers paused and inspect the Operator conditions before retrying.
Other Runtime Settings
proxy.http, proxy.https, and proxy.noProxy configure Registry egress. disableRedirect: true
serves object data through the Registry when clients cannot reach the storage endpoint directly.
logLevel accepts Normal, Debug, Trace, or TraceAll. Resource requests and limits, node
selection, tolerations, affinity, and topology spread are also supported by Config/cluster.spec.
Configure Managed Service Account Pull Secrets
When Config/cluster is managed, the Operator's imagePullSecret controller can create, inject,
refresh, and remove service account pull credentials for the internal Registry.
Warning: Excluding a namespace with
ignoredNamespaces, or settingignoreSystemNamespacestotruefor a namespace labelednamespace-type=system, removes existing managed pull Secrets, their ServiceAccount references, and the managed image-puller RoleBinding there. Prepare and verify replacement credentials and image permissions before changing these settings. SelectingimagePullSecret.managementState: Removedalso removes managed access.
Patch Config/cluster to add hosts or exclude namespaces. The patch replaces array fields, so
include every host and namespace that must remain configured:
Verify the configuration:
Expected result:
Config/cluster.spec.imagePullSecretcontains the configured management state, additional hosts, and ignored namespace settings.
Credential updates are asynchronous. Allow the controller to reconcile, then check the managed RoleBinding and a ServiceAccount:
Expected results:
- The RoleBinding grants the
system:image-pullerClusterRole to service accounts in the namespace. - The ServiceAccount lists at least one managed pull Secret after asynchronous reconciliation.
- At least one Secret with the managed-pull-secret label exists. Use
kubectl get secretto inspect metadata only; do not print or decode credential data.
imagePullSecret.managementState supports Managed and Force to manage credentials, Unmanaged
to pause reconciliation, and Removed to remove managed credentials. When it is omitted, the
setting follows Config/cluster.spec.managementState. Existing user-managed pull Secrets are not
removed by the controller.
Configure Image Limits
In Registry, image size and tag-count limits are represented with
Kubernetes LimitRange and ResourceQuota objects.
Create a file named team-a-image-quota.yaml for namespace-level quota:
Apply the quota:
Create a file named team-a-image-limits.yaml for per-image and per-ImageStream limits:
alauda.io/images counts distinct image digests referenced by the ImageStream, including tag
history. alauda.io/image-tags counts distinct image references in its spec.
alauda.io/repository-tags counts current repository tag names, including tags that share an image.
Only a LimitRange enforces alauda.io/repository-tags; a ResourceQuota does not.
Apply the limits:
Verify the quota and limits:
Expected results:
- The
ResourceQuotacontains the configured Image API limits. - The
LimitRangecontains the configuredalauda.io/Imageandalauda.io/ImageStreamlimits.
Configure Scheduled Image Pruning
The Operator enables scheduled pruning on new installations by creating ImagePruner/cluster
with these defaults:
The Operator honors explicit spec.suspend: true and false. An upgrade preserves an explicit
true, including one set by an earlier safety release. Review the retention policy before
enabling a suspended schedule.
Warning: When
ImagePruner.spec.dryRunisfalse, Jobs runac adm prune images --confirm=trueand delete data without an interactive confirmation. WhendryRunistrue, the generated command uses--confirm=falseand previews the same policy. A managed Registry also uses--prune-registry=trueto unlink eligible references and run Registry garbage collection in a verified Registry Pod. Keep metadata and storage backups. Live reference checks are not atomic with newly created references and do not detect consumers outside this cluster.
Scheduled online pruning with --prune-registry=true requires a writable Registry and Image API.
It runs without read-only mode or a full maintenance window. Choose retention settings that cover
image publication and deployment. Use manual
repository exclusions to protect images used
outside this cluster. Keep scheduled pruning suspended if its policy cannot retain those images.
The Operator suspends unsafe older CronJob templates before reconciling dependent resources. The
condition Scheduled=False with reason ScheduledGCUnsafe identifies an unsafe template. Its
replacement specifies modern mode, the operand namespace, retention settings, and the verified
internal Registry endpoint. It uses --prune-registry=true for a managed Registry and
--prune-registry=false otherwise. Once the template is safe, the CronJob follows spec.suspend;
the Operator does not pause a supported online template on every reconciliation. An explicit pause
takes effect even when a later prerequisite check fails.
Temporarily suspend the schedule while reviewing or changing the policy:
Wait until the CronJob reports true. Suspension prevents new scheduled Jobs; it does not stop a
Job already running. Wait for active Jobs to finish before changing the policy or backend.
Create image-pruner.yaml with the retention values you want to review. Leave pruning suspended:
Apply the configuration:
Verify the pruner resource and rendered CronJob:
Expected results:
ImagePruner/clustercontains the configured schedule and retention policy.- The rendered
image-prunerCronJob remains suspended in the Registry operand namespace. - The
servicecaConfigMap contains a non-emptyservice-ca.crtbundle for the pruner Pod.
The system:image-pruner ClusterRole and image-registry-system-pruner ClusterRoleBinding let the
pruner ServiceAccount read Config/cluster. This permission allows get only on the configuration
named cluster; it grants no configuration changes. The CLI checks it before scanning.
Before enabling the schedule, check the ServiceAccount's effective permission. Run this as a cluster
administrator who can impersonate ServiceAccounts and their groups. REGISTRY_NAMESPACE must
contain the operand namespace discovered earlier:
Expected result: yes. If it is no, keep the schedule suspended and inspect the Operator-managed
role and binding:
The system:image-pruner role must allow get on configs in
imageregistry.operator.alauda.io, limited to resourceNames: [cluster]. Its binding must reference
that role and the pruner ServiceAccount in the operand namespace.
The system:image-pruner-gc role must allow create on pods/exec, get on Services, and list on
endpointslices. The image-registry-pruner-gc RoleBinding grants this role to the same pruner
ServiceAccount in the operand namespace. The rules apply throughout that namespace, without
resourceNames restrictions. Before executing GC, the CLI validates the Registry Service selector,
Ready EndpointSlice, and target Pod.
All three kubectl auth can-i checks must return yes. If permission to read the Registry
configuration is denied, the CLI exits with
ac adm prune images requires platform-admin access to Registry Config/cluster. Resolve the
Operator installation or reconciliation issue, then repeat the checks. Do not edit the
Operator-managed role directly.
Inspect the suspension reason and rendered command:
Expected results while the policy is suspended:
- The condition is
Falsewith reasonSuspended, and CronJob suspension istrue. - The sample
dryRun: falsepolicy produces--confirm=true. WithdryRun: true, the command uses--confirm=false. - A managed Registry uses
--prune-registry=trueand its bound Registry URL. When the Registry isRemovedorUnmanaged, the command uses--prune-registry=falseand leaves Registry manifest and layer references and blob data in place. - Unless customized, the CronJob reports
startingDeadline=3600,successfulHistory=3, andfailedHistory=3.
Verify the generated mode:
Expected result: modern. Online Registry cleanup uses the separate system:image-pruner-gc
binding described above; system:image-pruner does not grant pods/exec. Resolve any remaining
ScheduledGCUnsafe or degraded condition before enabling execution. Do not edit the CronJob or
remove its safety checks.
Enable the reviewed schedule through ImagePruner/cluster:
Expected result after reconciliation: True with reason Scheduled. Jobs run on the configured
schedule. Forbid concurrency prevents scheduled Jobs from overlapping; coordinate manual cleanup
separately so that it does not overlap them. Set spec.suspend: true to pause future scheduled Jobs.
Kubernetes retries failed Jobs according to backoffLimit. Each retry scans the current images and
workloads again. The Operator retains but ignores an existing image-pruner-state ConfigMap and
does not create or update one.
See Prune images for metadata-only behavior. With
--prune-registry=true, the same Job also runs Registry garbage collection. The separate
Registry garbage collection
command requires read-only mode and writer isolation during maintenance.
Other supported ImagePruner fields include:
ignoreInvalidImageReferences sets --ignore-invalid-refs. logLevel maps Normal, Debug,
Trace, and TraceAll to --v=0, --v=4, --v=6, and --v=8, respectively. The CRD rejects
other values.
Operate Storage
For PVC-backed Registry storage:
Replace <claim-name> with the configured claim, such as registry-data from the PVC example.
Common actions:
- If a PVC is pending, check StorageClass, access mode, capacity, quotas, and events.
- If a Registry Pod cannot mount storage, check PV binding, node attachment, and backend storage availability.
- If image metadata exists but blob data is missing, verify whether the Registry used
emptyDiror whether the storage backend was changed. - Confirm which data must be retained before deleting PVCs, PVs, or object storage data.