Kubernetes 1.24 removed Dockershim and dropped support for Docker as a built-in container runtime. ACK no longer supports Docker as the container runtime in version 1.24 and later. To upgrade an ACK cluster to Kubernetes 1.24 or later, migrate the node container runtime from Docker to containerd first.
Containerd is an industry-standard container runtime with faster startup times, lower resource usage, and is more secure than Docker.
Before you begin
In most cases, workloads don't depend on the container runtime directly—Docker's own backend calls containerd—so the migration should be transparent to running applications.
Migrate your staging environment first, then migrate your production environment during off-peak hours.
Migration options
Two methods are available for migrating the node container runtime.
Option 1: Upgrade the existing node pool (recommended)
Use the Kubelet Update feature on the Node Pools page. This method automatically replaces the system disk of each node.
Back up any data on node system disks before starting. System disks are replaced during the upgrade. Data disks are not affected.
Log in to the Container Service Management Console. In the left navigation pane, click Clusters.
Click the name of your cluster. In the left navigation pane, choose Nodes > Node Pools.
In the Actions column of the target node pool, click
> Kubelet Update.Review the runtime upgrade details and click Precheck. After the pre-check passes, follow the on-screen instructions to complete the upgrade.
For parameter details, see Upgrade a node pool.
Option 2: Create a new node pool and migrate workloads (Optional)
Create a new node pool with the containerd runtime, then gradually shift workloads to it before decommissioning the old pool.
Create and manage a node pool and set the container runtime to containerd.
Scale out the new node pool to add nodes.
Cordon the old node pool, or use node labels to reschedule workloads to the new pool.
Migrate all workloads to the new node pool.
Decommission the old node pool.
For instructions on cordoning nodes, see Drain a node and manage its schedulability.
How disk replacement upgrades work
When you use Option 1, ACK performs a disk replacement upgrade for each node in sequence:
Drain the node and set it as unschedulable.
Shut down the ECS instance.
Replace the system disk. The system disk ID changes, but the disk type, instance IP address, and elastic network interface (ENI) MAC address remain unchanged.
Reinitialize the node and install the containerd runtime.
Restart the node and set it as schedulable once it's ready.
Post-migration considerations
Docker commands and APIs are no longer available on nodes. After the migration, Docker no longer manages the container lifecycle. Use containerd commands instead. For the containerd equivalents of common Docker commands, see Comparison of containerd, sandboxed containers, and Docker runtimes.
Docker Build is not available on cluster nodes. Containerd does not include a built-in image building tool. Pulling images is unaffected. If you previously built images on cluster nodes, use one of these alternatives:
Alibaba Cloud Container Registry (ACR) — recommended: ACR builds images using BuildKit, Docker's official image building tool. Create an ACR instance and configure build rules based on a Dockerfile to trigger automatic builds. The resulting image is pushed directly to your image repository. See Build images using an Enterprise Edition instance.
A dedicated ECS instance: Create a separate ECS instance, install Docker on it, and run Docker commands to build images. See Install and use Docker and Docker Compose.
Review Dockerfile configurations. The main Dockerfile syntax is unchanged. Check base image compatibility, environment variable settings, and runtime command definitions to make sure images build and run correctly in the containerd environment.
FAQ
How long does each node upgrade take?
Without a snapshot, each node upgrade typically takes less than 8 minutes. If you create a snapshot during the upgrade, the upgrade starts after the snapshot is created—ACK allows up to 40 minutes for snapshot creation. If the snapshot isn't ready within 40 minutes, the node upgrade times out and fails (without starting the upgrade on that node).
If you don't store business data on system disks, skip snapshot creation to keep upgrade times short.
How are nodes upgraded in batches?
Batch sizes follow an exponential pattern: 1, 2, 4, 8, and so on, until the configured maximum concurrent upgrade count is reached. After that, each batch upgrades that many nodes. For example, with a maximum of 4 concurrent upgrades, the batches are 1, 2, 4, 4, 4.
Will my services be interrupted during the upgrade?
Nodes are drained during the upgrade. Services are unaffected if your pods implement graceful shutdown and you have multiple replicas running on different nodes. To prevent all replicas of the same application from being upgraded in the same batch, set the maximum concurrent upgrade count to fewer than the number of pod replicas.
Can I roll back after the migration?
No. Rollback is not supported.
Is data on nodes lost during the migration?
System disks are replaced. Back up any important data on system disks before starting. Data disks are not affected.
Does the node IP address change when the system disk is replaced?
No. The system disk ID changes, but the disk type, instance IP address, and ENI MAC address remain unchanged. See Replace the system disk of an instance (change the OS).
After upgrading to containerd, the Docker directory still occupies disk space. How do I clean it up?
The Docker directory in the data disk may contain container files, images, logs, and file paths you created. If these are no longer needed, manually delete the Docker directory from the data disk after the migration.