Accessing the Registry

Access Alauda Container Platform Registry from inside the cluster, from external clients, or through the Image API.

Prerequisites

  • Alauda Container Platform Registry is installed and available in the target cluster.
  • The image namespace team-a exists. The cross-namespace workload example also requires team-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-a to team-b:app-puller before 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 ac CLI 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:v1 to 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:

ValueDescription
team-aNamespace that owns my-app:v1 and the first example workload.
team-bNamespace for the workload that pulls the image from team-a.
registry.example.comVerified external Registry hostname, including a port if required, without a scheme or path.
source.example.com/source-team/my-app:v1Existing source image to publish to the Registry. You need read access to it.
<digest>The 64-character hexadecimal suffix of a SHA-256 digest. The example commands supply sha256:.
REGISTRY_AUTH_FILEAbsolute path to the local auth file selected during login.

For ac Image API commands, select the Operator-managed Registry backend:

ac config set-registry-mode modern

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:

OperationTypical roleImage API permission
Pullsystem:image-pullerimage.alauda.io imagestreams/layers get
Pushsystem:image-pusherimage.alauda.io imagestreams/layers update
Deletesystem:image-deleterimage.alauda.io imagestreamtags delete

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:

image-registry.cpaas-system.svc:5000

Example workload image reference:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: team-a
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      serviceAccountName: default
      containers:
        - name: app
          image: image-registry.cpaas-system.svc:5000/team-a/my-app:v1

Save the manifest as my-app.yaml and apply it:

kubectl apply -f my-app.yaml
kubectl -n team-a rollout status deployment/my-app --timeout=300s
kubectl -n team-a get pods -l app=my-app

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:

kubectl create serviceaccount app-puller -n team-b

Verify that the ServiceAccount references its managed pull Secret. The annotation identifies the managed Secret even when the ServiceAccount has other pull Secrets:

PULL_SECRET="$(
  kubectl -n team-b get serviceaccount app-puller \
    -o jsonpath='{.metadata.annotations.imageregistry\.operator\.alauda\.io/internal-registry-pull-secret-ref}'
)"
test -n "$PULL_SECRET" || {
  echo "The managed pull Secret has not been injected yet." >&2
  exit 1
}

PULL_SECRET_REFERENCE="$(
  kubectl -n team-b get serviceaccount app-puller \
    -o jsonpath="{.imagePullSecrets[?(@.name==\"$PULL_SECRET\")].name}"
)"
test "$PULL_SECRET_REFERENCE" = "$PULL_SECRET" || {
  echo "The managed pull Secret is not referenced by the ServiceAccount yet." >&2
  exit 1
}
printf 'Managed pull Secret: %s\n' "$PULL_SECRET"

Check the Secret's management label, service account annotation, and expiry annotation. The commands display metadata only:

kubectl -n team-b get secret "$PULL_SECRET" \
  -o go-template='Managed: {{index .metadata.labels "imageregistry.operator.alauda.io/managed-pull-secret"}}
Service account: {{index .metadata.annotations "imageregistry.operator.alauda.io/internal-registry-auth-token.service-account"}}
Expiry: {{index .metadata.annotations "imageregistry.operator.alauda.io/internal-registry-auth-token.expiry"}}
'
date -u '+Current UTC: %Y-%m-%dT%H:%M:%SZ'

Expected results:

  • The managed Secret named by the annotation is present in ServiceAccount.imagePullSecrets.
  • Managed is true and Service account is app-puller.
  • Expiry is present and later than Current 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:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: team-b
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      serviceAccountName: app-puller
      containers:
        - name: app
          image: image-registry.cpaas-system.svc:5000/team-a/my-app:v1
          imagePullPolicy: Always

Save the manifest as my-app-app-puller.yaml and apply it:

kubectl apply -f my-app-app-puller.yaml

Verify the rollout:

kubectl -n team-b rollout status deployment/my-app --timeout=300s
kubectl -n team-b get pods -l app=my-app

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:

REGISTRY_AUTH_DIR="$(mktemp -d "${TMPDIR:-/tmp}/registry-auth.XXXXXX")"
export REGISTRY_AUTH_FILE="$REGISTRY_AUTH_DIR/config.json"

ac registry login \
  --registry registry.example.com \
  --to "$REGISTRY_AUTH_FILE"

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:

ac image info registry.example.com/team-a/my-app:v1 \
  --show-multiarch \
  --registry-config="$REGISTRY_AUTH_FILE"

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:

ac registry login \
  --registry registry.example.com \
  --auth-basic='<username>:<password>' \
  --to "$REGISTRY_AUTH_FILE"

--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:

ac image mirror \
  source.example.com/source-team/my-app:v1 \
  registry.example.com/team-a/my-app:v1 \
  --keep-manifest-list \
  --dry-run \
  --registry-config="$REGISTRY_AUTH_FILE"

The preview lists the planned copy without validating remote images or permissions. Publish with the same source and options:

ac image mirror \
  source.example.com/source-team/my-app:v1 \
  registry.example.com/team-a/my-app:v1 \
  --keep-manifest-list \
  --registry-config="$REGISTRY_AUTH_FILE"

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::

ac image info 'registry.example.com/team-a/my-app@sha256:<digest>' \
  --show-multiarch \
  --registry-config="$REGISTRY_AUTH_FILE"

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.