Alauda Container Platform

Registry v2: Accessing the Registry

Use this page to access Registry v2 from inside the cluster, from external clients, and through the ACP Image API.

TOC

PrerequisitesGrant Namespace PermissionsAccess the Registry from Inside the ClusterAuthenticate an External OCI ClientPush and Pull ImagesQuery Image API ResourcesDelete Image ReferencesCheck Registry Pods, Logs, and Metrics

Prerequisites

  • The Registry Operator is installed.
  • Config/cluster is Managed.
  • image-registry, image-api-server, and node-ca are ready.
  • The current user or ServiceAccount has the required namespace permissions.

Grant Namespace Permissions

Grant pull permission to a user:

kubectl create rolebinding image-puller-user \
  --clusterrole=system:image-puller \
  --user=<username> \
  -n <image-namespace>

Grant push permission to a user:

kubectl create rolebinding image-pusher-user \
  --clusterrole=system:image-pusher \
  --user=<username> \
  -n <image-namespace>

Grant pull permission to a ServiceAccount in another namespace:

kubectl create rolebinding image-puller-sa \
  --clusterrole=system:image-puller \
  --serviceaccount=<workload-namespace>:<serviceaccount-name> \
  -n <image-namespace>

Registry v2 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 API delete permissions for the target image metadata
Prunesystem:image-prunerImage API prune and layer inspection permissions

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

For a custom ServiceAccount, grant pull permission in the image namespace and let the Operator inject the managed pull Secret:

kubectl create serviceaccount app-puller -n team-b

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

Authenticate an External OCI Client

For external access, log in with an ACP account that has namespace permissions:

nerdctl login registry.example.com \
  -u <ACP-USERNAME> \
  -p <ACP-PASSWORD>

If the Registry uses a private CA or an HTTP endpoint in a non-production test environment, configure the client trust or use the client's insecure-registry option.

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 Registry HTTP image repositories visible to the current user:

ac get images --registry-url=https://registry.example.com
ac get images -n team-a --registry-url=https://registry.example.com

Delete Image References

Preview deletion first:

ac delete images \
  --repo=team-a/my-app:v1 \
  --registry-url=https://registry.example.com

Confirm deletion:

ac delete images \
  --repo=team-a/my-app:v1 \
  --registry-url=https://registry.example.com \
  --confirm

Deletion removes image metadata references. Run prune and GC separately when you need storage reclamation.

Check Registry Pods, Logs, and Metrics

Check Registry Pods:

kubectl -n image-registry-system get pods -l app.kubernetes.io/name=image-registry

View Registry logs:

kubectl -n image-registry-system logs deployment/image-registry -c registry

Check metrics access from a monitoring ServiceAccount:

kubectl auth can-i get pods -n image-registry-system \
  --as=system:serviceaccount:cpaas-system:prometheus-sa