You can configure containerd v2 as the primary container runtime either at the cluster level or for specific node groups. This runtime option enables the use of cgroups v2, provides improved security, and allows more flexible resource management.

Requirements

Migration to containerd v2 is possible under the following conditions:

  • Nodes meet the requirements described in the cluster-wide parameters.
  • The node kernel version is not in the range 6.12.0–6.12.28 or 6.14.0–6.14.6 (these versions are affected by CVE-2025-37999 in EROFS).
  • There are no custom configurations on the server in /etc/containerd/conf.d (example of a custom configuration).

If any of the requirements described in the general cluster parameters are not met, Deckhouse Virtualization Platform adds the label node.deckhouse.io/containerd-v2-unsupported to the node. If the node has custom configurations in /etc/containerd/conf.d, the label node.deckhouse.io/containerd-config=custom is added to it.

If one of these labels is present, changing the spec.cri.type parameter for the node group will be unavailable. Nodes that do not meet the migration conditions can be viewed using the following commands:

d8 k get node -l node.deckhouse.io/containerd-v2-unsupported
d8 k get node -l node.deckhouse.io/containerd-config=custom

Additionally, a administrator can verify if a specific node meets the requirements using the following commands:

uname -r | cut -d- -f1
stat -f -c %T /sys/fs/cgroup
systemctl --version | awk 'NR==1{print $2}'
modprobe -qn erofs && echo "TRUE" || echo "FALSE"
ls -l /etc/containerd/conf.d

How to enable containerd v2

During migration the directory /var/lib/containerd will be cleared, causing all pod images to be re-pulled, and the node will reboot.

Also note that this is a disruptive update. If spec.disruptions.approvalMode: Manual is set for a node group, run the update on the respective nodes with the annotation: d8 k annotate node <NODE-NAME> update.node.deckhouse.io/disruption-approved=.

You can enable containerd v2 in two ways:

  1. For the entire cluster. Set the value ContainerdV2 for the defaultCRI parameter in the ClusterConfiguration resource. This value will apply to all NodeGroup objects where spec.cri.type is not explicitly defined.

    Example:

    apiVersion: deckhouse.io/v1
kind: ClusterConfiguration
...
defaultCRI: ContainerdV2

  2. For a specific node group. Set ContainerdV2 in the spec.cri.type parameter of the NodeGroup object.

    Example:

    apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: worker
spec:
  cri:
    type: ContainerdV2

    When migrating to containerd v2 Deckhouse Kubernetes Platform will begin sequentially updating the nodes.

Additional resources