Accessing the Registry
Access Alauda Container Platform Registry from inside the cluster, from external clients, or through the Image API.
TOC
PrerequisitesRequired Namespace PermissionsAccess the Registry from Inside the ClusterAuthenticate an External OCI ClientPublish and Inspect ImagesQuery Image API ResourcesPrerequisites
- Alauda Container Platform Registry is installed and available in the target cluster.
- The image namespace
team-aexists. The cross-namespace workload example also requiresteam-b. - A namespace administrator has granted the required namespace permissions
to your account and the workload service account. For the cross-namespace example, grant pull
access in
team-atoteam-b:app-pullerbefore deploying the workload. - Managed service account pull Secrets are enabled in the namespaces used by the workload examples. Ask a Registry administrator to confirm this setting.
- The
acCLI is installed and authenticated when you use the Registry or Image API commands. - Your account can get ServiceAccounts and Secrets in the workload namespace to check their metadata. Ask a namespace administrator to run the checks if your account lacks this access.
- Publish
team-a/my-app:v1to the Registry before deploying either workload. See Publish and inspect images if the image is not available yet.
Run CLI commands on your developer machine or in a CI environment with access to the target cluster. Replace the example values before running the commands:
For ac Image API commands, select the Operator-managed Registry backend:
Required Namespace Permissions
Your user account or workload service account needs permissions in the namespace that owns the image repository. Ask a namespace administrator to grant these permissions.
The Registry uses ImageStream layer authorization:
Image API commands can require additional resource permissions. See
Delete image references for the read and
delete permissions required by ac delete images.
Access the Registry from Inside the Cluster
By default, Registry operands run in cpaas-system. For a custom operand namespace, use the value
recorded in Config/cluster.metadata.annotations[imageregistry.operator.alauda.io/operand-namespace].
Use the internal service address for workloads inside the cluster:
Example workload image reference:
Save the manifest as my-app.yaml and apply it:
Expected result: the Deployment is created in team-a and its Pod becomes ready using the internal
Registry image.
The image repository path is namespace-scoped. Use <registry-host>/<namespace>/<repository>:<tag>;
do not include additional path segments after the namespace.
For a custom service account, complete the cross-namespace permission prerequisite before deploying the workload. The Operator injects a managed pull Secret when the Registry is configured to manage service account pull Secrets in that namespace.
Create the service account in the workload namespace:
Verify that the ServiceAccount references its managed pull Secret. The annotation identifies the managed Secret even when the ServiceAccount has other pull Secrets:
Check the Secret's management label, service account annotation, and expiry annotation. The commands display metadata only:
Expected results:
- The managed Secret named by the annotation is present in
ServiceAccount.imagePullSecrets. ManagedistrueandService accountisapp-puller.Expiryis present and later thanCurrent UTC. Do not continue if expiry is missing or expired.
The controller creates a Secret stub before populating it with credentials. It refreshes the credentials asynchronously. If any check fails, wait for reconciliation and repeat both verification blocks. If the metadata remains incomplete, ask a Registry administrator to verify that managed service account pull Secrets are enabled and that the workload namespace is not ignored. Do not display or decode credential data. A successful workload rollout verifies that the credentials can pull the image.
Use the service account in the workload:
Save the manifest as my-app-app-puller.yaml and apply it:
Verify the rollout:
Expected results:
- The rollout completes successfully.
- The Pod is ready and does not report an image pull error. If the Pod is in
ImagePullBackOff, verify the ServiceAccount permission, injected pull Secret, internal service address, and image repository path.
Authenticate an External OCI Client
Obtain a reachable HTTPS Registry hostname from a Registry administrator. An Ingress status address alone does not establish a usable Registry hostname. If the registry uses a private CA, configure client trust before login. Write credentials for a account with namespace permissions:
Keep this shell open, or export the same REGISTRY_AUTH_FILE path before running the verification
and publishing blocks below.
The example creates a dedicated authentication file. When updating an existing valid JSON file, the CLI preserves unrelated settings and other Registry credentials. Login fails without overwriting an invalid file.
The selected file must store credentials directly. Login fails without changing the file if it delegates this Registry to an external credential helper. The dedicated file in this example has no helper configuration.
Login writes credentials for registry.example.com to the specified auth file. Verify image access
by inspecting an existing image that your account can pull. If team-a/my-app:v1 has not
been published yet, complete Publish and inspect images first:
Expected result: the command returns the image digest and metadata. Writing the auth file alone does not verify image permissions. For another OCI client, configure it to read the same auth file.
For a registry account that uses basic credentials, pass them explicitly:
--to and --registry-config (or -a) select the login output file. When neither is supplied,
the CLI uses the configured client auth directory, then the user's standard client auth file, and
finally config.json. Use an explicit path in automation so subsequent commands read the same file.
Use --skip-check only when you need the file before the endpoint is reachable. For login,
--insecure also bypasses the endpoint check. It does not configure trust for later commands.
For controlled HTTP or untrusted-certificate tests, pass --insecure separately to the direct image
commands.
Publish and Inspect Images
Use ac image mirror to publish an existing source image without a local container runtime. Both
registries must be reachable from your machine. For a private source, the selected auth file must
also contain credentials for the source host.
If your image exists only in a local container runtime, use that runtime's OCI client to publish it
first. The client must be installed and its runtime must be running. The image must exist in the
selected local image store. The ac examples below require a full source Registry
reference. A local-only name such as my-app:latest is not sufficient.
Preview copying the source image to the destination repository:
The preview lists the planned copy without validating remote images or permissions. Publish with the same source and options:
Verify the published tag with the ac image info command in
Authenticate an external OCI client.
Use the returned digest to inspect an immutable image reference. Replace <digest> with only the
hexadecimal suffix after sha256::
Expected result: the tag and digest queries identify the same published manifest or image index.
Workloads can now pull image-registry.cpaas-system.svc:5000/team-a/my-app:v1 with the required
service account permissions. To copy files to your machine, see
Work with OCI images directly.
Query Image API Resources
Inspect ImageStreams, tag history, or ImageDigest metadata with
Query images and ImageStreams.
ImageStream API resources, including the ac get imagestreamimages query, are namespace-scoped.
Listing ImageDigest objects requires cluster-scoped read permission.