Registry Module: FAQ

How to prepare containerd v1?

Example directory structure for Mirror Auth configuration:

tree /etc/containerd/registry.d
.
├── registry.d8-system.svc:5001
│   ├── ca.crt
│   └── hosts.toml
└── registry.deckhouse.ru
    ├── ca.crt
    └── hosts.toml

Example hosts.toml configuration:

[host]
  [host."https://registry.deckhouse.ru"]
    capabilities = ["pull", "resolve"]
    skip_verify = true
    ca = ["/path/to/ca.crt"]
    [host."https://registry.deckhouse.ru".auth]
      username = "username"
      password = "password"
      # If providing auth string:
      auth = "<base64>"

Before switching, make sure there are no custom registry configurations present on nodes with containerd v1 in the /etc/containerd/conf.d directory.

If such configurations exist:

1. Create new Mirror Auth configurations in the /etc/containerd/registry.d directory. Example:

   apiVersion: deckhouse.io/v1alpha1
   kind: NodeGroupConfiguration
   metadata:
     name: custom-registry
   spec:
     bundles:
       - '*'
     content: |
       #!/bin/bash
       REGISTRY_ADDRESS="registry.io"
       REGISTRY_SCHEME="https"
       host_toml=$(cat <<EOF
       [host]
         [host."https://registry.deckhouse.ru"]
           capabilities = ["pull", "resolve"]
           skip_verify = true
           ca = ["/path/to/ca.crt"]
           [host."https://registry.deckhouse.ru".auth]
             username = "username"
             password = "password"
             # If providing auth string:
             auth = "<base64>"
       EOF
       )
       mkdir -p "/etc/containerd/registry.d/${REGISTRY_ADDRESS}"
       echo "$host_toml" > "/etc/containerd/registry.d/${REGISTRY_ADDRESS}/hosts.toml"
     nodeGroups:
       - '*'
     weight: 0
   

   To test the configuration:

   # HTTPS:
   ctr -n k8s.io images pull --hosts-dir=/etc/containerd/registry.d/ registry.io/registry/path:tag
   
   # HTTP:
   ctr -n k8s.io images pull --hosts-dir=/etc/containerd/registry.d/ --plain-http registry.io/registry/path:tag
   

2. Delete auth configurations from the /etc/containerd/conf.d directory.

How to switch back to the previous containerd v1 auth configuration?

1. Switch the registry mode to Unmanaged.

2. Check the switching status using this guide. Example output:

   conditions:
   # ...
   - lastTransitionTime: "..."
     message: ""
     reason: ""
     status: "True"
     type: Ready
   hash: ..
   mode: Unmanaged
   target_mode: Unmanaged
   

3. Delete the secret registry-bashible-config:

   d8 k -n d8-system delete secret registry-bashible-config
   

4. After deleting the secret, wait for the auth configuration to switch back to the legacy one in Containerd V1.

   You can use this guide to track the switch. Example output:

   conditions:
   # ...
   - lastTransitionTime: "..."
     message: ""
     reason: ""
     status: "True"
     type: Ready
   hash: ..
   mode: Unmanaged
   target_mode: Unmanaged
   

How to check the registry mode switch status?

The status of the registry mode switch can be retrieved using the following command:

d8 k -n d8-system -o yaml get secret registry-state | yq -C -P '.data | del .state | map_values(@base64d) | .conditions = (.conditions | from_yaml)'

Example output:

conditions:
  - lastTransitionTime: "2025-07-15T12:52:46Z"
    message: 'registry.deckhouse.ru: all 157 items are checked'
    reason: Ready
    status: "True"
    type: RegistryContainsRequiredImages
  - lastTransitionTime: "2025-07-11T11:59:03Z"
    message: ""
    reason: ""
    status: "True"
    type: ContainerdConfigPreflightReady
  - lastTransitionTime: "2025-07-15T12:47:47Z"
    message: ""
    reason: ""
    status: "True"
    type: TransitionContainerdConfigReady
  - lastTransitionTime: "2025-07-15T12:52:48Z"
    message: ""
    reason: ""
    status: "True"
    type: InClusterProxyReady
  - lastTransitionTime: "2025-07-15T12:54:53Z"
    message: ""
    reason: ""
    status: "True"
    type: DeckhouseRegistrySwitchReady
  - lastTransitionTime: "2025-07-15T12:55:48Z"
    message: ""
    reason: ""
    status: "True"
    type: FinalContainerdConfigReady
  - lastTransitionTime: "2025-07-15T12:55:48Z"
    message: ""
    reason: ""
    status: "True"
    type: Ready
mode: Direct
target_mode: Direct

The output displays the status of the switch process. Each condition can have a status of True or False, and may contain a message field with additional details.

Description of conditions: