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

Changing the Container Runtime from Docker to containerd

Dockershim has been removed as of Kubernetes 1.24. To keep pace with the community's technology roadmap, improve cluster stability and resource efficiency, and ensure compatibility with and continuous support from Kubernetes, you are advised to migrate the container runtime from Docker to containerd, which is officially recommended.

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

  • The migration of the node container runtime will rebuild the service pods running on the node. Theoretically, services may be interrupted for a short period of time. Therefore, you are advised to ensure that the pods are deployed in HA mode and test the migration impact in the test environment before migrating the services to the production environment during off-peak hours to minimize risks.
  • 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. Ensure that you have read and understood the Image Management Service Statement.
  9. Click Submit. If the node status is Installing, the node is being reset.

    When the node status is Running, you can see that the node runtime is switched to containerd. You can log in to the node and run containerd commands such as crictl to view information about the containers running on the node.

  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 as large as 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