#Accessing the Registry

Use this page to access Alauda Container Platform Registry from inside the cluster, from external clients, and through the Image API.

#Prerequisites

• Alauda Container Platform Registry is installed and available in the target cluster.
• The image namespace exists.
• The current user or service account has the required namespace permissions.
• The ac CLI is installed and authenticated when you use the Registry or Image API commands.

For ac Image API commands, select the ACP 4.4 Registry backend:

ac config set-registry-mode modern

#Required Namespace Permissions

Your user account or workload service account must have permissions in the namespace that owns the image repository. Ask a namespace administrator to grant the required image roles when you need cross-namespace access.

The Registry uses ImageStream layer authorization:

Additional Registry roles (system:image-signature-writer, system:image-registry-catalog-reader, and system:image-registry-metrics-reader) are listed in the full permission table in Managing access and cleanup.

For role binding examples, see Managing access and cleanup.

#Access the Registry from Inside the Cluster

Use the internal service address for workloads inside the cluster:

image-registry.image-registry-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.image-registry-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 results:

• 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, make sure it has pull permission in the image namespace. The Operator injects the managed pull secret when the Registry is configured to manage service account pull secrets.

Create the service account in the workload namespace:

kubectl create serviceaccount app-puller -n team-b

Have a namespace administrator grant the service account pull permission in the image namespace:

kubectl create rolebinding image-puller-app-puller \
  --clusterrole=system:image-puller \
  --serviceaccount=team-b:app-puller \
  -n team-a

Verify that the managed pull secret is injected:

PULL_SECRET="$(
  kubectl -n team-b get serviceaccount app-puller \
    -o jsonpath='{.imagePullSecrets[0].name}'
)"
test -n "$PULL_SECRET" || {
  echo "The managed pull Secret has not been injected yet." >&2
  exit 1
}
printf 'Managed pull Secret: %s\n' "$PULL_SECRET"
kubectl -n team-b get secret "$PULL_SECRET" \
  -o jsonpath='{.data}' | wc -c

Expected result:

• The command prints a managed pull Secret name and a non-zero data size. Do not print or decode the Secret data.

The controller refreshes managed pull credentials asynchronously. If no pull Secret is listed, wait for reconciliation and ask a Registry administrator to verify that managed service account pull secrets are enabled and that the workload namespace is not ignored.

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.image-registry-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

For external access, use ac registry login to write credentials for a account that has namespace permissions:

ac registry login \
  --registry registry.example.com

To write credentials to a specific OCI registry auth file, use --to:

mkdir -p /tmp/registry-auth

ac registry login \
  --registry registry.example.com \
  --to /tmp/registry-auth/config.json

export REGISTRY_AUTH_FILE=/tmp/registry-auth/config.json

The command writes credentials for registry.example.com to the specified auth file. Use the exported REGISTRY_AUTH_FILE with ac image commands that need Registry authentication.

If the registry uses a private CA, configure client trust before push and pull operations. Use --insecure only for an HTTP endpoint or a non-production test certificate that the client does not trust.

#Push and Pull Images

Tag and push an image:

nerdctl tag my-app:latest registry.example.com/team-a/my-app:v1
nerdctl push registry.example.com/team-a/my-app:v1

Pull by tag:

nerdctl pull registry.example.com/team-a/my-app:v1

Pull by digest:

nerdctl pull registry.example.com/team-a/my-app@sha256:<digest>

#Query Image API Resources

List ImageStreams:

kubectl get imagestreams.image.alauda.io -A
ac get imagestreams -A

Show one ImageStream:

ac get imagestreams my-app -n team-a -o yaml

Show the current and historical digest for a tag:

ac get imagestreamtags my-app:v1 -n team-a -o wide

Show the Image metadata for a digest:

ac get imagestreamimages my-app@sha256:<digest> -n team-a -o yaml

List cluster-scoped Image resources through the current modern registry mode:

ac config set-registry-mode modern
ac get images
ac get images -o yaml

For namespace-scoped repository views, query ImageStream resources instead of passing a Registry URL override:

ac get imagestreams -n team-a
ac get imagestreamtags my-app:v1 -n team-a -o wide