You are viewing documentation for Kubernetes version: v1.23
Kubernetes v1.23 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.
Migrate Docker Engine nodes from dockershim to cri-dockerd
This page shows you how to migrate your Docker Engine nodes to use cri-dockerd
instead of dockershim. Follow these steps if your clusters run Kubernetes 1.23
or earlier and you want to continue using Docker Engine after
you upgrade to Kubernetes 1.24 and later, or if you just want to move off the
dockershim component.
What is cri-dockerd?
In Kubernetes 1.23 and earlier, Docker Engine used a component called the
dockershim to interact with Kubernetes system components such as the kubelet.
The dockershim component is deprecated and will be removed in Kubernetes 1.24. A
third-party replacement, cri-dockerd
, is available. The cri-dockerd
adapter
lets you use Docker Engine through the Container Runtime Interface.
cri-dockerd
, you aren't affected by the dockershim removal.
Before you begin, Check whether your nodes use the dockershim.
If you want to migrate to cri-dockerd
so that you can continue using Docker
Engine as your container runtime, you should do the following for each affected
node:
- Install
cri-dockerd
. - Cordon and drain the node.
- Configure the kubelet to use
cri-dockerd
. - Restart the kubelet.
- Verify that the node is healthy.
Test the migration on non-critical nodes first.
You should perform the following steps for each node that you want to migrate
to cri-dockerd
.
Before you begin
cri-dockerd
installed and started on each node.- A network plugin.
Cordon and drain the node
-
Cordon the node to stop new Pods scheduling on it:
kubectl cordon <NODE_NAME>
Replace
<NODE_NAME>
with the name of the node. -
Drain the node to safely evict running Pods:
kubectl drain <NODE_NAME> \ --ignore-daemonsets
Configure the kubelet to use cri-dockerd
The following steps apply to clusters set up using the kubeadm tool. If you use a different tool, you should modify the kubelet using the configuration instructions for that tool.
- Open
/var/lib/kubelet/kubeadm-flags.env
on each affected node. - Modify the
--container-runtime-endpoint
flag tounix:///var/run/cri-dockerd.sock
.
The kubeadm tool stores the node's socket as an annotation on the Node
object
in the control plane. To modify this socket for each affected node:
-
Edit the YAML representation of the
Node
object:KUBECONFIG=/path/to/admin.conf kubectl edit no <NODE_NAME>
Replace the following:
/path/to/admin.conf
: the path to the kubectl configuration file,admin.conf
.<NODE_NAME>
: the name of the node you want to modify.
-
Change
kubeadm.alpha.kubernetes.io/cri-socket
from/var/run/dockershim.sock
tounix:///var/run/cri-dockerd.sock
. -
Save the changes. The
Node
object is updated on save.
Restart the kubelet
systemctl restart kubelet
Verify that the node is healthy
To check whether the node uses the cri-dockerd
endpoint, follow the
instructions in Find out which runtime you use.
The --container-runtime-endpoint
flag for the kubelet should be unix:///var/run/cri-dockerd.sock
.
Uncordon the node
Uncordon the node to let Pods schedule on it:
kubectl uncordon <NODE_NAME>
What's next
Items on this page refer to third party products or projects that provide functionality required by Kubernetes. The Kubernetes project authors aren't responsible for those third-party products or projects. See the CNCF website guidelines for more details.
You should read the content guide before proposing a change that adds an extra third-party link.