Managing Access and Cleanup
These procedures cover Alauda Container Platform Registry and namespace administration: image access, usage reporting, pruning, garbage collection, and recorded signature identity checks.
TOC
Task IndexPrerequisitesGrant Namespace PermissionsView UsageCheck Recorded Signature IdentityPrune ImagesPrune Metadata and Reclaim StoragePrune Metadata OnlyRetry a Failed Online CleanupRun Registry Garbage CollectionPrepare the Maintenance WindowCollect Already Unlinked BlobsVerify Blob AvailabilityRestore the Previous SettingsTask Index
Prerequisites
- Registry is installed and available.
- You have
kubectlandacaccess to the target cluster. - You have permission to create RoleBindings in the image namespace.
- You can create cluster-scoped
subjectaccessreviews.authorization.k8s.ioto check another principal's permissions. - You have administrator permissions for usage reporting and cleanup. Online metadata pruning uses
the Image API. Registry cleanup also requires Registry HTTP deletion and permission to execute
commands in a verified Registry Pod. Full maintenance also requires
permission to update
Config/clusterandImagePruner/cluster. - For signature identity checks, you can
getcluster-scopedimagedigests.image.alauda.io. Saving conditions or removing embedded signatures also requiresupdateon that resource.
Select the ACP 4.5 Registry backend before using the ac administrative commands:
Expected result:
- Subsequent
acImage API, pruning, garbage-collection, and signature commands use the ACP 4.5 Registry.
Grant Namespace Permissions
Grant pull permission to a user:
Grant push permission to a user:
Grant pull permission to a service account in another namespace:
Verify that the RoleBinding exists:
The Registry uses the following permissions in the image.alauda.io API group:
Use a RoleBinding for namespace access. Direct ImageSignature API operations and metrics require
cluster-scoped authorization. A ClusterRoleBinding grants that role across the cluster. The
administrative signature command uses ImageDigest get and update permissions instead.
Catalog visibility follows pull permissions. A user with get on imagestreams/layers can see
the permitted repositories without a separate catalog-reader grant. A namespace-wide grant covers
the namespace; a grant for named repositories covers only those repositories. Catalog visibility
does not grant push or delete permission.
Deleting a manifest by digest through the OCI Registry API can remove every current tag in that
repository that points to the digest. The authorization check uses the repository name.
ImageStreamTag API deletion targets a single <repository>:<tag> resource name. These namespace
grants do not authorize deletion of cluster-scoped ImageDigest objects. To remove one tag,
use Delete image references.
The system:image-pruner ClusterRole is reserved for the Operator-managed pruner ServiceAccount.
It is not a namespace access role. Manual pruning and garbage collection require the corresponding
administrator permissions.
Check effective pull access with a SubjectAccessReview that matches the Registry authorization
check. Run the command in the target cluster's kubeconfig context to preserve any API proxy path.
--validate=false bypasses the client schema check when OpenAPI validation blocks the request.
Authentication and RBAC still apply:
Supply the principal's actual groups when testing group-based grants. For a ServiceAccount,
include system:serviceaccounts, system:serviceaccounts:<workload-namespace>, and
system:authenticated. For push access, repeat the request with verb set to update.
The command prints status.allowed. A true result means the supplied identity and resource
attributes are authorized. A false result does not establish whether the account exists. For
details, repeat with -o json and inspect status.reason and status.evaluationError.
For Registry signature uploads, reuse the request above with these resourceAttributes:
For direct cluster-scoped ImageSignature API creation, omit the namespace and repository name:
Repeat that review with verb set to delete to check direct signature deletion. To check the
administrative signature command, use resource: imagedigests, name: sha256:<digest>, and
verb: get or verb: update, still without a namespace.
registry/metrics is an RBAC-only subresource absent from Image API discovery. Check its
cluster-scoped permission directly:
Use the principal's actual groups as above. The command prints true when the supplied identity
has the metrics reader permission in the target cluster.
View Usage
Show metadata-derived storage totals and Pod usage for ImageDigest objects:
Show metadata-derived totals for ImageStreams:
Expected result:
- The command prints usage rows for ImageDigest or ImageStream resources visible to the current administrator.
Interpret the columns as follows:
- Image
STORAGEsums recorded layer sizes and child-manifest sizes. ImageStreamSTORAGEsums those values once per distinct referenced image digest, including tag history. - Shared layers are counted again across different images. These totals do not measure physical backend usage or predict reclaimable bytes.
- Image
USAGEcounts Pods with matching digest references in the queried Pod scope. It does not include every workload or external consumer.METADATAcounts recorded layer and child-manifest entries; ImageStreamLAYERSsums those counts per referenced image. - Image
IMAGESTREAMTAGlists thenamespace/stream:tagreferences that contribute the row, comma-separated when several match. ImageStreamIMAGEScounts the distinct image digests the stream references.
Check Recorded Signature Identity
The command compares identity claims recorded on an ImageDigest object. It does not verify signature cryptography, signer trust, or image integrity. Independently verify the signature under your signing policy before recording a trust decision.
Check the recorded identity without modifying the object:
Expected result: the command reports a matching recorded identity and leaves the ImageDigest unchanged.
Before changing signatures, back up the ImageDigest metadata to a protected local file:
Warning:
--savereplaces the matching signatures' conditions withTrusted=TrueandForImage=True. An identity match alone does not justify trust. Use this option only after independent verification, with cluster-scoped ImageDigestupdatepermission and a metadata backup.
Record the independently verified trust decision:
Verify the saved condition:
Expected result:
- Matching signature records contain
Trusted=TrueandForImage=Trueconditions.
To roll back --save, restore the affected signatures' previous conditions from the metadata backup.
Warning:
--remove-allimmediately clears all embedded signature data from the ImageDigest object without a confirmation prompt. The Registry cannot undo this operation. Keep a metadata backup and confirm the records are no longer required before running it.
Remove the embedded records and verify that signatures is empty:
Prune Images
Warning: Confirmed online pruning permanently removes selected image metadata and eligible Registry data. Keep metadata and storage backups, and review a dry run with the same retention, endpoint, and exclusion flags before adding
--confirm. There is no automatic rollback.
Pruning requires platform-level access. The account must be allowed to get
configs.imageregistry.operator.alauda.io/cluster; otherwise the command exits before scanning.
Namespace image roles such as system:image-deleter are not sufficient.
For the Operator-managed Registry, ac adm prune images uses the Image API reference graph. A
confirmed run without --prune-registry=true removes eligible Image API metadata only. With
--prune-registry=true, it verifies the bound Service, Ready EndpointSlice, and Registry Pod before
deleting eligible manifest references through authenticated HTTP requests. It then refreshes the
graph and runs Registry garbage collection in that Pod. Online pruning does not automatically
isolate writers. Use the separate maintenance procedure for standalone GC.
Manual defaults are independent of ImagePruner/cluster:
Explicit flags override these defaults. The examples retain five revisions per tag and images
younger than 72 hours. Use the same policy for every preview and confirmation.
The --all flag bypasses age and revision retention. Omit it when those limits must apply. It does
not mean "apply the configured retention to all images."
The pruner scans Pod specifications in this cluster's Pods, Deployments, StatefulSets, DaemonSets,
ReplicaSets, ReplicationControllers, Jobs, and CronJobs. Retained tag history, workload references,
shared config and layer blobs, and image index children are protected by the observed graph.
Consumers in other clusters or outside the platform are not scanned; exclude their repositories
with --whitelist or retain the required images before proceeding.
For running containers, the pruner also checks resolved image IDs in regular, init, and ephemeral container statuses. This protects an older image while its workload tag advances. If the pruner cannot safely interpret a running container's image ID, it stops and identifies the affected Pod. Inspect that Pod's container runtime status before retrying.
The pruner refreshes metadata and workload checks during cleanup. These checks do not lock out writers or make deletion atomic with new references. Concurrent pushes, imports, retagging, or workload changes can introduce references after a check. Choose retention that covers image publication and deployment, and avoid reusing candidates while they are being deleted.
Prune Metadata and Reclaim Storage
Use online pruning while the Image API graph is available. The CLI verifies the Registry operand
binding. A confirmed run with --prune-registry=true also verifies the Registry endpoint and Pod.
If your workstation cannot reach the internal Service, add --registry-url with a verified,
reachable endpoint and --certificate-authority with its PEM CA bundle to confirmed runs that
include --prune-registry=true. See Configure client trust.
Preview online pruning:
Expected result:
- The dry run lists metadata candidates without deleting metadata, Registry references, or blobs. It does not run Registry garbage collection.
Run pruning after reviewing the dry-run output:
Verify pruning:
Expected result:
- A follow-up dry run no longer lists the completed targets. Check command errors separately; an empty metadata candidate list alone does not prove storage cleanup finished.
Verify that retained ImageStream tags still resolve. Fully pull or extract critical images from a fresh client directory to check layer availability; metadata inspection alone cannot verify this. Resolve failures before another cleanup run.
Exclude repositories from pruning with --whitelist. The flag takes regular expressions and can be
repeated:
After reviewing the preview, confirm the same policy:
Prune Metadata Only
Set --prune-registry=false explicitly to update ImageStream references and remove eligible
ImageDigest objects without deleting Registry references or blobs. Preview and confirm the same policy:
Metadata-only pruning uses the bound operand namespace, including a custom installation namespace, and does not require an available Registry Service.
It leaves storage manifest and layer references intact. Standalone garbage collection follows those references and can retain blobs after Image API metadata is gone. To reclaim storage, choose online pruning while the graph still exists. Later garbage collection cannot recover missing manifest unlink information.
If a previous online run failed, resolve the error and rerun the same policy with --prune-registry=true.
Retry a Failed Online Cleanup
Cleanup does not store a journal or blob inventory in a ConfigMap. With --prune-registry=true,
the CLI verifies the bound Registry Service, Ready EndpointSlice, and Pod before unlinking eligible
manifest references. It then refreshes the Image API graph, removes eligible metadata, and runs
Registry garbage collection in that Pod. If manifest deletion fails, the run stops before removing
the corresponding metadata.
If a command or scheduled Job fails, resolve the error, review another dry run, and retry with the
same Registry endpoint, retention, and exclusion options. Kubernetes retries scheduled Jobs
according to backoffLimit. Each retry rebuilds the current image and workload view. Do not
edit or create an image-pruner-state ConfigMap to bypass a failed cleanup. Standalone garbage
collection cannot reconstruct manifest links that were never removed, and it does not scan Image
API metadata for retention candidates.
For scheduled pruning, see Configure scheduled image pruning. For recovery, restore both metadata and missing blobs from verified backups or republish from a trusted image source. Re-importing external metadata alone does not restore local blob data.
Run Registry Garbage Collection
ac adm registry gc performs full storage garbage collection in a Registry Pod, separately from
ordinary online image pruning. It collects blobs no longer referenced by storage manifests,
including old orphaned blobs. It does not use Image API retention to select images or unlink
manifests. After metadata-only pruning, storage manifest links can still retain blobs during GC.
Warning: Confirmed blob reclamation is irreversible through the Registry. Full GC does not automatically stop writers. Prevent concurrent pushes, imports, and other Registry or Image API writes, enable read-only mode, and let in-flight writes finish before cleanup. Keep writers paused until verification completes. Restore missing data from a storage backup or a trusted image source.
Prepare the Maintenance Window
ac adm registry gc resolves the Registry operand namespace from the installation binding, even
when Registry mode is selected explicitly. It uses the bound Service's complete selector to find
a ready Registry Pod. The CLI refuses GC if it cannot verify the binding or find that Pod.
Use an administrator environment with kubectl, ac, curl, pull access to critical images,
and enough disk space to extract them. Select and verify the access path before changing Registry
settings:
- For an external endpoint, use the verified HTTPS hostname from Exposing the Registry.
- For an internal-only Registry, run from a maintenance environment with cluster network and DNS
access. Use
image-registry.cpaas-system.svc:5000and the Registry service CA. You do not need to expose an external Ingress for cleanup.
An administrator can obtain the internal service CA from the operand namespace:
Set the endpoint and CA bundle for the selected path. The bundle must validate the endpoint's
certificate chain and hostname. The examples pass it explicitly to curl. On Linux,
SSL_CERT_FILE supplies it to each direct ac invocation. On macOS or Windows, add the CA to the
client's system trust store before login and extraction. The environment variable does not replace
that step. See Configure client trust.
A 401 response is the expected unauthenticated challenge. It confirms reachability but does not
establish permission. Extract the image to establish a baseline before entering maintenance:
Expected result: the image filesystem is extracted successfully. Repeat with every critical image and required platform, each time using a fresh directory. Resolve any failure before cleanup. Keep these endpoint, authentication, and verification variables in the same shell throughout the maintenance procedure.
Record the current settings and suspend scheduled pruning to prevent overlapping cleanup:
Wait until every existing pruner Job has a terminal Complete or Failed condition. Suspending the
schedule does not stop an existing Job. Pause workflows that change images and prevent other
clients from writing throughout garbage collection and verification. Read-only mode alone does
not block direct backend writers or finish requests already in flight.
Collect Already Unlinked Blobs
Use standalone GC after storage manifest links have been removed. It does not unlink manifests based on Image API retention. After stopping writers, follow the enabling steps in Enable read-only mode. Wait for the requested Config generation to reconcile and the Registry rollout to complete; keep read-only mode enabled until blob verification finishes. Do not run metadata pruning in this mode; Image API writes and deletes are blocked.
Preview storage garbage collection:
Expected result:
- The command previews eligible unreferenced blobs and does not delete them.
Run registry garbage collection only after reviewing the preview:
Expected result:
- The command removes eligible unreferenced blobs from Registry storage.
Verify blob availability before restoring the previous settings.
Verify Blob Availability
Repeat the baseline check with the same immutable image reference and platform. Extract into a fresh directory to read the image layers without a local runtime cache:
Expected result: extraction completes and writes the image filesystem to $VERIFY_DIR. Repeat for
every critical image and required platform checked before cleanup. An ac image info inspection
alone does not verify layer availability. Remove temporary authentication and image directories
after verification and any investigation are complete.
Restore the Previous Settings
After successful verification, restore the recorded read-only setting while keeping writers isolated and scheduled pruning suspended:
Continue only when Pods are present, no row has a deletion timestamp, and every read-only value
matches EXPECTED_REGISTRY_READ_ONLY (empty when the recorded setting was false). Repeat this
check until all old Pods have terminated. Resume writers only after successful verification and
only if the Registry is intended to be writable. After maintenance, restore the recorded schedule state:
Verify that the rollout completes and both settings match their recorded values. An originally suspended schedule must remain suspended. If any check fails, keep the maintenance controls and schedule suspension in place while investigating.