Help Center/ Cloud Container Engine/ User Guide/ Nodes/ Node O&M/ Changing the Container Runtime from Docker to containerd
Updated on 2026-06-16 GMT+08:00
View PDF
Share

Changing the Container Runtime from Docker to containerd

Dockershim was removed in Kubernetes 1.24. To maintain compatibility with upstream Kubernetes, ensure continuous support, and improve cluster stability and resource efficiency, migrate the container runtime from Docker to containerd, which is the officially recommended runtime.

containerd is an industry-standard container runtime supported by Kubernetes. Compared with Docker, containerd occupies fewer resources, starts containers faster, and is more stable and secure.

Prerequisites

Precautions

  • Migrating a node's container runtime rebuilds all service pods on that node, which may cause brief service interruptions. To minimize risk, ensure pods are deployed in HA mode, validate the migration impact in a test environment, and perform production migrations during off-peak hours.
  • containerd does not support image building. After the migration is complete, you cannot use Docker Build to build images on the containerd nodes, but image pull is not affected. For other differences between Docker and containerd, see Container Runtimes.
  • If you have configured node affinity policies for the workloads deployed on the original Docker nodes or node pool, configure affinity policies for the workloads to run on the new containerd nodes or node pool. In this case, you can perform a rolling upgrade to add affinity configurations for the workloads to run on the new containerd nodes or node pool without deleting the existing node affinity configurations. After the rolling upgrade is complete and there are no problems through sufficient tests, delete the affinity configurations on the old Docker nodes.

Migrating from Docker to containerd in the Default Node Pool

You can reset the Docker nodes to containerd nodes.

If the node resource usages are high, resetting an existing Docker node may cause pods on the node to fail to be rebuilt after migration. You can add nodes as needed to avoid this problem.

  1. Log in to the CCE console and click the cluster name to access the cluster console.
  2. In the navigation pane, choose Nodes. On the displayed page, click the Nodes tab.
  3. Select a Docker node in the cluster, and choose More > Disable Scheduling.
  4. Choose More > Drain Node.

  5. On the displayed page, enable Forcible Drain and click OK.

  6. After the drainage is complete, select the node in the node list and choose More > Reset Node.
  7. Set the container runtime to containerd. You can adjust other parameters as needed or retain them as set during creation.

  8. Click Next: Confirm.
  9. Read the instructions, select the check box for confirmation, and click Submit. If the node status is Installing, the node is being reset.

    When the node status is Running, check whether the node runtime has switched to containerd by logging into the node and running commands such as crictl ps or crictl inspect to view container information.

  10. Repeat the preceding steps until Docker on all nodes is replaced with containerd.

Migrating from Docker to containerd in a Custom Node Pool

You can select any method to migrate Docker nodes.

Method 1: Performing a Rolling Update

You can update a node pool to change the runtime of the node pool from Docker to containerd, retain other configurations, and then update the nodes in the node pool in rolling mode.

  1. Log in to the CCE console and click the cluster name to access the cluster console.
  2. Choose Nodes in the navigation pane. In the right pane, click the Node Pools tab. Locate the target Docker node pool and click Update.

  3. On the slide-out panel, set the container runtime to containerd and modify other parameters as needed.

  4. Wait until the node pool is updated. After the update is complete, new nodes in the node pool use containerd, and "Node pool updated" is displayed for existing nodes in the node pool. You can reset these nodes to change the runtime to containerd.

    You can also choose More > Synchronize next to the node pool name and reset all nodes in the node pool in batches.

    If the resource usages in a node pool are high, resetting an existing Docker node in this pool may cause pods on the node to fail to be rebuilt after migration. You can add nodes to this pool as needed to avoid this problem.

Method 2: Creating a containerd Node Pool

You can copy a node pool, set the container runtime of the new node pool to containerd, and keep other configurations the same as those of the original Docker node pool.

  1. Log in to the CCE console and click the cluster name to access the cluster console.
  2. Choose Nodes in the navigation pane. On the Node Pools tab, locate the Docker node pool to be copied and choose More > Copy.

  3. On the slide-out panel, set the container runtime to containerd and modify other parameters as needed to create the node pool.

  4. Scale the created containerd node pool to the size of the original Docker node pool and delete nodes from the Docker node pool one by one.

    Rolling migration is preferred. Add some containerd nodes and then delete some Docker nodes until the number of nodes in the new containerd node pool is the same as that in the original Docker node pool.

    If you have configured node affinity policies for the workloads deployed on the original Docker nodes or node pool, configure affinity policies for the workloads to run on the new containerd nodes or node pool. In this case, you can add affinity configurations for the workloads to run on the new containerd nodes or node pool without deleting the existing node affinity configurations. After the rolling upgrade is complete and there are no problems through sufficient tests, delete the affinity configurations on the old Docker nodes.

  5. Delete the original Docker node pool.
Parent Topic: Node O&M