FAQ

How to create a new PVC?

To create a new PVC, follow these steps:

1. Disable garbage collection (GC). In the ModuleConfig, set the settings.gc.enabled parameter 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:

   Check the job queue before disabling:

   d8 k -n d8-payload-registry get jobs

   Example output:

   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
   

   Check GC job pods before disabling:

   d8 k -n d8-payload-registry get pods -l "component=gc"

   Example output:

   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
   

   Check the job queue after disabling:

   d8 k -n d8-payload-registry get jobs

   Example output:

   No resources found in d8-payload-registry namespace.
   

   Check GC job pods after disabling:

   d8 k -n d8-payload-registry get pods -l "component=gc"

   Example output:

   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:

   d8 k -n d8-payload-registry get pvc

   Example output:

   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:

   d8 k -n d8-payload-registry get deployment/registry -o yaml | grep 'registry-2'

   Example output:

   claimName: registry-2
   

5. Enable garbage collection (GC). In the module manifest, set 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.

   d8 k -n d8-payload-registry delete pvc/registry

   Example output:

   persistentvolumeclaim "registry" deleted
   

How is the registry monitored?

When the monitoring stack is enabled, the module ships its own metrics and alerts (requires Prometheus / operator-prometheus):

• Cluster (infra) alerts for administrators: registry/apiserver unavailable, high 5xx error rate, push/pull failures, high latency, and failed garbage-collection jobs.
• Project alerts routed to the tenant: per-project storage usage reaching 80% (warning) and 90% (critical) of the project’s own quota (the PayloadRegistryQuota limit). These carry the project namespace label.
• A Grafana dashboard (“Payload registry”, in the Kubernetes folder): request rate (pull/push/delete), error rate, latency, in-flight requests, and per-project storage versus quota.

The registry traffic metrics come from the registry itself (registry_http_*); per-project storage usage is exported by the aggregated apiserver as payload_registry_project_storage_bytes / payload_registry_project_storage_quota_bytes.

How do I get alerted when a workload can’t pull its image from the registry?

Enable Deckhouse extended monitoring on the namespaces whose workloads pull images from this registry, by adding the label to the namespace:

d8 k label namespace <your-namespace> extended-monitoring.deckhouse.io/enabled=""

The image-availability-exporter then checks that the images referenced by Deployments/StatefulSets/DaemonSets/CronJobs in that namespace actually exist and are pullable, and raises <Kind>ImageAbsent, <Kind>RegistryUnavailable, <Kind>AuthenticationFailure and <Kind>AuthorizationFailure alerts against this registry — no extra configuration on the payload-registry side is required.