#Registry v2: Accessing the Registry

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

#Prerequisites

• Registry v2 is installed and available in the target cluster.
• The image namespace exists.
• The current user or service account has the required namespace permissions.

#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.

Registry v2 uses ImageStream layer authorization:

For role binding examples, see Managing Registry v2 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

For a custom service account, make sure it has pull permission in the image namespace. The Operator injects the managed pull secret when Registry v2 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:

kubectl -n team-b get serviceaccount app-puller \
  -o jsonpath='{.imagePullSecrets[*].name}{"\n"}'

Expected result:

• The command returns at least one image pull secret name.

If no pull secret is listed, 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

Verify the rollout:

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

#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 Docker-compatible auth file, set DOCKER_CONFIG or use --to:

export DOCKER_CONFIG=/tmp/registry-auth

ac registry login \
  --registry registry.example.com \
  --to "$DOCKER_CONFIG/config.json"

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