How to Migrate to the registry module?
During the migration, Containerd v1 will switch to the new registry configuration format. Containerd v2 uses the new format by default. For more details, see the section with a description of configuration methods.
For containerd v2
-
Switch to using the
registry
module. To do this, specify theUnmanaged
mode parameters in thedeckhouse
moduleConfig
. If you are using a registry other thanregistry.deckhouse.ru
, refer to thedeckhouse
module documentation for proper configuration.You can view the current registry settings using the following command:
d8 k -n d8-system exec -it svc/deckhouse-leader -c deckhouse -- deckhouse-controller global values | yq e '.modulesImages.registry' -
Specify this configuration when setting up the
Unmanaged
mode:apiVersion: deckhouse.io/v1alpha1 kind: ModuleConfig metadata: name: deckhouse spec: version: 1 enabled: true settings: registry: mode: Unmanaged unmanaged: imagesRepo: registry.deckhouse.ru/deckhouse/ee scheme: HTTPS license: <LICENSE_KEY> # Replace with your license key
-
Wait for the switch to complete. Example status output:
conditions: # ... - lastTransitionTime: "..." message: "" reason: "" status: "True" type: Ready hash: .. mode: Unmanaged target_mode: Unmanaged
For Containerd v1
- During the switch, containerd v1 will be restarted.
- During the switch, containerd v1 will be migrated to the new registry configuration scheme.
- During the switch, custom registry configurations for containerd v1 will be temporarily unavailable.
-
Make sure that nodes with containerd v1 do not have any custom registry configurations located in the
/etc/containerd/conf.d
directory. -
If configurations are present, you need to migrate to the new registry configuration format in containerd. To do this, add new configuration files to the
/etc/containerd/registry.d
directory. These configurations will take effect after switching to theregistry
module. To add configurations, prepare aNodeGroupConfiguration
. For more details, see the section with a description of configuration methods. Example:apiVersion: deckhouse.io/v1alpha1 kind: NodeGroupConfiguration metadata: name: containerd-additional-config-auth.sh spec: # The step can be arbitrary, as restarting the containerd service is not required weight: 0 bundles: - '*' nodeGroups: - "*" content: | # Copyright 2023 Flant JSC # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. REGISTRY_URL=private.registry.example mkdir -p "/etc/containerd/registry.d/${REGISTRY_URL}" bb-sync-file "/etc/containerd/registry.d/${REGISTRY_URL}/hosts.toml" - << EOF [host] [host."https://${REGISTRY_URL}"] capabilities = ["pull", "resolve"] [host."https://${REGISTRY_URL}".auth] username = "username" password = "password" EOF
-
Apply the
NodeGroupConfiguration
. Wait until the configuration files appear in the/etc/containerd/registry.d
directory on all nodes. -
Verify that the configurations are working correctly. To do this, use the following command:
# For HTTPS: ctr -n k8s.io images pull --hosts-dir=/etc/containerd/registry.d/ private.registry.example/registry/path:tag # For HTTP: ctr -n k8s.io images pull --hosts-dir=/etc/containerd/registry.d/ --plain-http private.registry.example/registry/path:tag
-
Switch to using the
registry
module. To do this, specify theUnmanaged
mode parameters in thedeckhouse
moduleConfig
. If you are using a registry other thanregistry.deckhouse.ru
, refer to thedeckhouse
module documentation for proper configuration.You can view the current registry settings using the following command:
d8 k -n d8-system exec -it svc/deckhouse-leader -c deckhouse -- deckhouse-controller global values | yq e '.modulesImages.registry' -
Specify this configuration when setting up the
Unmanaged
mode:apiVersion: deckhouse.io/v1alpha1 kind: ModuleConfig metadata: name: deckhouse spec: version: 1 enabled: true settings: registry: mode: Unmanaged unmanaged: imagesRepo: registry.deckhouse.ru/deckhouse/ee scheme: HTTPS license: <LICENSE_KEY> # Replace with your license key
-
After applying, wait for the following message to appear in the switch status:
Example output:
conditions: # ... - lastTransitionTime: "2025-08-13T15:22:34Z" message: | Check current nodes configuration 2/2 node(s) Unready: - master-0: has custom toml merge containerd configuration - worker-5e389be0-578df-s5sm5: has custom toml merge containerd configuration reason: Processing status: "False" type: ContainerdConfigPreflightReady
This message means that there are old registry configurations on the nodes located in the
/etc/containerd/conf.d
directory. The switch to the new containerd configuration is currently blocked. To allow the switch, you need to remove the old configuration files. -
Remove the old configuration files to allow switching to the
registry
module. To do this, create aNodeGroupConfiguration
, for example:apiVersion: deckhouse.io/v1alpha1 kind: NodeGroupConfiguration metadata: name: containerd-additional-config-auth.sh spec: # To add a file before the '032_configure_containerd.sh' step weight: 0 bundles: - '*' nodeGroups: - "*" content: | # Copyright 2023 Flant JSC # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. file="/etc/containerd/conf.d/old-config.toml" [ -f "$file" ] && rm -f "$file"
-
After removing the old configurations, make sure that the switch has resumed. Example of the switch status:
conditions: # ... - lastTransitionTime: "2025-08-13T16:42:09Z" message: "" reason: "" status: "True" type: ContainerdConfigPreflightReady
-
Wait for the switch to complete. Example of the switch status:
conditions: # ... - lastTransitionTime: "..." message: "" reason: "" status: "True" type: Ready hash: .. mode: Unmanaged target_mode: Unmanaged
How to Migrate Back from the Registry Module?
- This is a deprecated registry management format.
- During the switch, containerd v1 will be restarted.
- During the switch, containerd v1 will be migrated to the legacy registry configuration scheme.
- During the switch, custom registry configurations for containerd v1 will be temporarily unavailable.
-
Switch the registry to
Unmanaged
mode. If you are using a registry other thanregistry.deckhouse.ru
, refer to thedeckhouse
module documentation for proper configuration.Example configuration:
apiVersion: deckhouse.io/v1alpha1 kind: ModuleConfig metadata: name: deckhouse spec: version: 1 enabled: true settings: registry: mode: Unmanaged unmanaged: imagesRepo: registry.deckhouse.ru/deckhouse/ee scheme: HTTPS license: <LICENSE_KEY>
-
Check the switch status using the instruction. Example output:
conditions: # ... - lastTransitionTime: "..." message: "" reason: "" status: "True" type: Ready hash: .. mode: Unmanaged target_mode: Unmanaged
-
Switch the registry to the non-configurable
Unmanaged
mode. Example configuration:apiVersion: deckhouse.io/v1alpha1 kind: ModuleConfig metadata: name: deckhouse spec: version: 1 enabled: true settings: registry: mode: Unmanaged
-
Check the switch status using the instruction. Example output:
conditions: # ... - lastTransitionTime: "..." message: "" reason: "" status: "True" type: Ready hash: .. mode: Unmanaged target_mode: Unmanaged
-
If containerd v1 is used and custom registry configurations are applied in the cluster, they must be replaced with the old format. To do this, prepare the registry configurations in the old format. These configurations do not need to be applied at this stage. Example configuration:
apiVersion: deckhouse.io/v1alpha1 kind: NodeGroupConfiguration metadata: name: containerd-additional-config-auth.sh spec: # To add a file before the '032_configure_containerd.sh' step weight: 31 bundles: - '*' nodeGroups: - "*" content: | # Copyright 2023 Flant JSC # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. REGISTRY_URL=private.registry.example mkdir -p /etc/containerd/conf.d bb-sync-file /etc/containerd/conf.d/additional_registry.toml - << EOF [plugins] [plugins."io.containerd.grpc.v1.cri"] [plugins."io.containerd.grpc.v1.cri".registry] [plugins."io.containerd.grpc.v1.cri".registry.mirrors] [plugins."io.containerd.grpc.v1.cri".registry.mirrors."${REGISTRY_URL}"] endpoint = ["https://${REGISTRY_URL}"] [plugins."io.containerd.grpc.v1.cri".registry.configs] [plugins."io.containerd.grpc.v1.cri".registry.configs."${REGISTRY_URL}".auth] username = "username" password = "password" # OR auth = "dXNlcm5hbWU6cGFzc3dvcmQ=" EOF
-
Delete the
registry-bashible-config
secret. This will trigger containerd v1 to switch back to the legacy registry format:d8 k -n d8-system delete secret registry-bashible-config
-
After deletion, wait for the switch to complete. Use the instruction to track the progress. Example output:
conditions: # ... - lastTransitionTime: "..." message: "" reason: "" status: "True" type: Ready hash: .. mode: Unmanaged target_mode: Unmanaged
-
If containerd v1 is used, apply the previously prepared
NodeGroupConfiguration
with custom registry configurations. -
Disable the
registry
module. Example:apiVersion: deckhouse.io/v1alpha1 kind: ModuleConfig metadata: name: registry spec: enabled: false settings: {} version: 1
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 modul e is ready to operate. |