Skip to main content

Connect to the container registry

Your cluster loads images from public registries without any further configuration. For private registries, store the access details as a secret of type docker-registry and reference them in your workloads.

Prerequisites​

  • A Kubernetes cluster with the status Running and a verified connection via kubectl

Create access credentials as a secret​

kubectl create secret docker-registry registry-credentials \
  --docker-server=registry.example.com \
  --docker-username=<benutzername> \
  --docker-password=<passwort-oder-token> \
  --namespace=produktion

The parameters in detail:

  • --docker-server – Registry address, without specifying a protocol
  • --docker-username – Username or account name
  • --docker-password – Password or – preferably – an access token
Warnung

A secret is only valid within a single namespace. If you are using multiple namespaces, create the secret in each one.

Check secret:

kubectl get secret registry-credentials -n produktion

Using a secret in deployment​

In the pod template, reference the secret using imagePullSecrets:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
  namespace: produktion
spec:
  replicas: 2
  selector:
    matchLabels:
      app: app
  template:
    metadata:
      labels:
        app: app
    spec:
      imagePullSecrets:
        - name: registry-credentials
      containers:
        - name: app
          image: registry.example.com/team/app:1.4.2
          ports:
            - containerPort: 8080

How to use:

kubectl apply -f deployment.yaml

Configure the registry for all workloads in a namespace​

To ensure that not every manifest needs to include the reference, add the secret to the namespace’s default service account:

kubectl patch serviceaccount default \
  -n produktion \
  -p '{"imagePullSecrets":[{"name":"registry-credentials"}]}'

All pods that use this service account will then automatically retrieve the credentials. Pods that are already running must be restarted for this to take effect:

kubectl rollout restart deployment app -n produktion

Troubleshooting​

If you encounter any problems, please check the pod status first:

kubectl get pods -n produktion
kubectl describe pod <pod-name> -n produktion

The Events section identifies the cause:

StatusMeaning
ImagePullBackOffThe image could not be loaded – check credentials, image name or tag
ErrImagePullThe loading process has failed; if the error persists, the status will change to ImagePullBackOff
unauthorized in the eventsThe credentials are incorrect or the secret is missing from the namespace
manifest unknown in the eventsThe image exists, but the specified tag does not

Common causes:

  • The secret is in a different namespace to the pod.
  • The value specified under --docker-server differs from the registry portion of the image name. Both must match.
  • The token used has expired or does not have read permissions.

Recommendations​

  • Use access tokens with read permissions instead of account passwords.
  • Set fixed tags or digests instead of latest so that it remains clear which version has been rolled out.
  • Use RBAC to restrict who is allowed to read secrets – see Setting up RoleBindings.
Last updated on