Module payload-registry: FAQ

How to generate a passwordHash?

To generate a bcrypt hash, use the htpasswd command:

$ htpasswd -Bnb "${USER_NAME}" "${PASSWORD}" | cut -d: -f2

The generated hash should be specified in the users.${USER_NAME}.passwordHash field. Example:

$ htpasswd -Bnb "user-1" "password123" | cut -d: -f2
$2y$05$KbQy.oSLGCS.mm0SIkLtIOYu.G1Lcp8iyPMLfK/Id9AO7nJYmdLXa

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: payload-registry
spec:
  version: 1
  enabled: true
  settings:
    users:
      user-1:
        passwordHash: "$2y$05$KbQy.oSLGCS.mm0SIkLtIOYu.G1Lcp8iyPMLfK/Id9AO7nJYmdLXa"
        projects: []

How to add an image to a project?

1. To add an image to a project, you need to configure a user with FULL access rights to the project. Example configuration:

   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$05$KbQy.oSLGCS.mm0SIkLtIOYu.G1Lcp8iyPMLfK/Id9AO7nJYmdLXa"
           - name: "project-1"
             subPath: "*"
             access: FULL
   

2. To be able to push images to the project, the namespace with the project’s name must exist in the cluster.

   $ kubectl create namespace project-1
   

3. Log in to the payload registry from your machine:

   $ docker login payload-registry.${PUBLIC_DOMAIN} -u user-1 -p password123
   

4. Create and push the image to the payload registry:

   $ docker tag ubuntu:latest payload-registry.${PUBLIC_DOMAIN}/project-1/ubuntu:latest
   $ docker push payload-registry.${PUBLIC_DOMAIN}/project-1/ubuntu:latest
   

5. Verify the presence of the image in the payload registry. Example check using the crane command:

   $ crane auth login payload-registry.${PUBLIC_DOMAIN} -u user-1 -p password123
   $ crane catalog payload-registry.${PUBLIC_DOMAIN}
   

How to set up imagePullSecrets to access a project?

1. To create imagePullSecrets, configure a user with READ/FULL access rights 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$05$KbQy.oSLGCS.mm0SIkLtIOYu.G1Lcp8iyPMLfK/Id9AO7nJYmdLXa"
           - name: "project-1"
             subPath: "*"
             access: READ
   

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

   $ kubectl 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 a 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:
     - my-img-pull-secret
   

How to create a new PVC?

1. Disable garbage collection (GC). Change the settings.gc.enabled parameter value to false:

   apiVersion: deckhouse.io/v1alpha1
   kind: ModuleConfig
   metadata:
     name: payload-registry
   spec:
     version: 1
     enabled: true
     settings:
       gc:
         enabled: false
       ...
   

2. Wait for GC to be disabled. Ensure that all completed jobs are deleted:

   Before disabling:

   $ kubectl -n d8-payload-registry get jobs
   NAME                          STATUS     COMPLETIONS   DURATION   AGE
   registry-gc-20251008-111705   Complete   1/1           12s        2m48s
   registry-gc-20251008-111805   Complete   1/1           3s         107s
   registry-gc-20251008-111905   Complete   1/1           3s         47s
   
   $ kubectl -n d8-payload-registry get pods -l "component=gc"
   NAME                                READY   STATUS              RESTARTS   AGE
   registry-gc-20251008-111905-zv7hh   0/1     Completed           0          2m2s
   registry-gc-20251008-112006-zs69r   0/1     Completed           0          62s
   registry-gc-20251008-112105-bblpx   0/1     ContainerCreating   0          3s
   

   After disabling:

   $ kubectl -n d8-payload-registry get jobs
   No resources found in d8-payload-registry namespace.
   
   $ kubectl -n d8-payload-registry get pods -l "component=gc"
   No resources found in d8-payload-registry namespace.
   

3. Specify the new PVC parameters in the settings.persistence section. Provide a new name in the name field to create a new PVC:

   apiVersion: deckhouse.io/v1alpha1
   kind: ModuleConfig
   metadata:
     name: payload-registry
   spec:
     enabled: true
     settings:
       gc:
         enabled: false
       ...
   
       # Old PVC settings
       # The name field defaults to `registry`
       # persistence:
       #  size: 10Gi
   
       # New PVC settings with name `registry-2`
       # New PVC is Initialized with a New storageClass
       persistence:
         name: registry-2
         storageClass: network-ssd
         size: 10Gi
     ...
   

4. Apply the changes. Wait for the new PVC to be created and connected to the registry.

   Check the creation of the PVC:

   $ kubectl -n d8-payload-registry get pvc
   NAME         STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   VOLUMEATTRIBUTESCLASS   AGE
   registry     Bound    pvc-09cb5d2e-6529-4759-adca-56aa20aead80   10Gi       RWO            network-hdd    <unset>                 92m
   registry-2   Bound    pvc-b3f037d2-d3fa-4b2c-8ae1-e9af75ff14d5   10Gi       RWO            network-ssd    <unset>                 60s
   

   Check the connection of the PVC to the registry:

   $ kubectl -n d8-payload-registry get deployment/registry -o yaml | grep 'registry-2'
   claimName: registry-2
   

5. Enable garbage collection (GC) by setting the settings.gc.enabled parameter to true:

   apiVersion: deckhouse.io/v1alpha1
   kind: ModuleConfig
   metadata:
     name: payload-registry
   spec:
     version: 1
     enabled: true
     settings:
       gc:
         enabled: true
       ...
   
       persistence:
         name: registry-2
         storageClass: network-ssd
         size: 10Gi
   

6. If necessary, delete the old PVC. The old PVC can be reattached by performing a similar connection procedure.

   Deleting the PVC:

   This step will result in the loss of data stored in the old PVC.

   $ kubectl -n d8-payload-registry delete pvc/registry
   persistentvolumeclaim "registry" deleted