Using images in cluster

To use images from a custom registry inside the DKP cluster where it is deployed, use the methods described below.

Prerequisites

Access to the registry is provided via Ingress, which exposes the service at payload-registry.${PUBLIC_DOMAIN}. The certificate for HTTPS is issued automatically according to the certificate management settings.

When using a custom Certificate Authority (CA) or another CA that cannot be verified by cluster nodes, you must add the appropriate configuration for an additional registry. Otherwise, cluster nodes will not be able to pull images due to certificate verification errors.

Using images for authentication with Kubernetes tokens

To use Kubernetes tokens as imagePullSecrets:

1. Create a ServiceAccount and grant it access using PayloadRepositoryAccess (see RBAC and PayloadRepositoryAccess):

   d8 k create serviceaccount my-pull-sa

2. Create a Secret to be used as imagePullSecrets:

   apiVersion: v1
   kind: Secret
   metadata:
     name: my-pull-secret
     annotations:
       payload-registry.deckhouse.io/service-account.name: my-pull-sa
   type: kubernetes.io/dockerconfigjson
   data:
     # Temporary value that will be overwritten with actual credentials.
     .dockerconfigjson: eyJhdXRocyI6e319

   The specified Secret will be automatically deleted when the corresponding ServiceAccount is deleted.

3. Verify that the data in the Secret has been updated:

   d8 k get secret my-pull-secret -o yaml

   Example output:

   apiVersion: v1
   kind: Secret
   metadata:
     name: my-pull-secret
     annotations:
       payload-registry.deckhouse.io/expires-at: "2026-03-06T02:14:19Z"
       payload-registry.deckhouse.io/hash: e3ba7bd9aeae15fdbce8ae1eed05f26732ebd82e4563115d34f335702071929e
       payload-registry.deckhouse.io/service-account.name: my-pull-sa
       payload-registry.deckhouse.io/service-account.uid: f847810d-bcdd-42b8-9f95-2c2d8d10bc8c
   type: kubernetes.io/dockerconfigjson
   data:
     # Value filled with actual credentials.
     .dockerconfigjson: ...

   The presence of these annotations indicates that the credentials for accessing the registry have been successfully added and will be kept up to date.

   Data in the Secret is valid for 24 hours from the last update. The expiration time is shown in the payload-registry.deckhouse.io/expires-at annotation. Data is updated some time before the expiration.

4. Add imagePullSecrets to the cluster component and specify the image:

   apiVersion: v1
   kind: Pod
   metadata:
     name: ubuntu
   spec:
     containers:
       - name: ubuntu
         image: payload-registry.${PUBLIC_DOMAIN}/project-1/ubuntu:latest
     imagePullSecrets:
       - name: my-pull-secret

Using images in static user configuration (deprecated)

To use the static user configuration:

1. Configure a user with READ/FULL access to the project. Example:

   apiVersion: deckhouse.io/v1alpha1
   kind: ModuleConfig
   metadata:
     name: payload-registry
   spec:
     version: 1
     enabled: true
     settings:
       users:
         user-1:
           # Bcrypt hash of the password `password123`.
           passwordHash: "$2y$10$CeP/hYvBJ05Ih2azafVyIuuMRpf60am4z6USm4jhHfUPsFDBAmn/u"
           projects:
           - name: "project-1"
             subPath: "*"
             access: READ

2. Create a Secret in the project namespace project-1 using the following command:

   d8 k create secret docker-registry my-img-pull-secret \
   --docker-server="https://payload-registry.${PUBLIC_DOMAIN}" \
   --docker-username=user-1 \
   --docker-password=password123 \
   --namespace=project-1

3. Add imagePullSecrets to the cluster component and specify the image:

   apiVersion: v1
   kind: Pod
   metadata:
     name: ubuntu
   spec:
     containers:
       - name: ubuntu
         image: payload-registry.${PUBLIC_DOMAIN}/project-1/ubuntu:latest
     imagePullSecrets:
       - name: my-img-pull-secret