How to prepare containerd v1?
When switching to the Direct
mode, the containerd v1 service will be restarted.
The authorization configuration will be switched to Mirror Auth (this configuration is used by default in Containerd V2
).
After switching back to Unmanaged
, the updated authorization configuration will remain unchanged.
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:
- After deleting custom registry configurations from the
/etc/containerd/conf.d
directory, the containerd service will be restarted. The removed configurations will no longer work. - New Mirror Auth configurations added to
/etc/containerd/registry.d
will only take effect after switching toDirect
mode.
-
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
-
Delete auth configurations from the
/etc/containerd/conf.d
directory.
How to switch back to the previous containerd v1 auth configuration?
This containerd configuration format is deprecated.
- This switch is only possible from the
Unmanaged
mode. - When switching to the legacy
Containerd V1
auth configuration, any custom configurations in/etc/containerd/registry.d
will stop working. - Custom registry configurations for the legacy auth format (using
/etc/containerd/conf.d
) can only be applied after switching to the legacy mode.
-
Switch the registry mode to
Unmanaged
. -
Check the switching status using this guide. Example output:
conditions: # ... - lastTransitionTime: "..." message: "" reason: "" status: "True" type: Ready hash: .. mode: Unmanaged target_mode: Unmanaged
-
Delete the secret registry-bashible-config:
d8 k -n d8-system delete secret registry-bashible-config
-
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:
Condition | Description |
---|---|
ContainerdConfigPreflightReady |
State of the containerd configuration preflight check. Verifies there are no custom containerd auth configurations on the nodes. |
TransitionContainerdConfigReady |
State of preparing the containerd configuration for the new mode. Verifies that the configuration contains both the old and new mode settings. |
FinalContainerdConfigReady |
State of finalizing the switch to the new containerd mode. Verifies that the containerd configuration has been successfully applied and contains only the new mode settings. |
DeckhouseRegistrySwitchReady |
State of switching Deckhouse and its components to use the new registry. True means Deckhouse successfully switched and is ready to operate. |
InClusterProxyReady |
State of In-Cluster Proxy readiness. Checks that the In-Cluster Proxy has started successfully and is running. |
CleanupInClusterProxy |
State of cleaning up the In-Cluster Proxy if it is not needed in the selected mode. Verifies that all related resources have been removed. |
Ready |
Overall state of registry readiness in the selected mode. Indicates that all other conditions are met and the module is ready to operate. |