Document and announce migration guide for Dockershim

[dims]

In the KEP-2221: Removing dockershim from kubelet KEP:
https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/2221-remove-dockershim/README.md

we have a line item that says:

• Document and announce migration guide

We need to have this ready by 1.24, so we should start earlier in 1.23 itself.

There are a bunch of things we can draw inspiration from:

• https://kubernetes.io/blog/2020/12/02/dockershim-faq/
• https://www.gremlin.com/blog/ensuring-a-smooth-kubernetes-dockershim-deprecation-with-chaos-engineering/
• https://www.youtube.com/watch?v=fl7_4hjT52g&ab_channel=GoogleOpenSource
• https://kruyt.org/migrate-docker-containerd-kubernetes/
• https://mohitgoyal.co/2021/03/30/another-blog-on-docker-depreciation-in-kubernetes-and-what-needs-to-be-done-about-it/

and we have some info already in our docs:

• https://kubernetes.io/docs/tasks/administer-cluster/migrating-from-dockershim/

cc @SergeyKanzhelev @endocrimes @adisky @ehashman

[dims]

/sig node
/sig docs

[Debanitrkl]

I can work on this
/assign

[SergeyKanzhelev]

Yes, this was created as a starting point: https://kubernetes.io/docs/tasks/administer-cluster/migrating-from-dockershim/

Step by step migration is different depending on where k8s is run. One specific issue tracking this: kubernetes/website#25879

also another clarification is needed here: kubernetes/website#28449

[SergeyKanzhelev]

Filed another one: kubernetes/website#29665

[SergeyKanzhelev]

KEP xref: kubernetes/enhancements#2221 for tracking

[PranshuSrivastava]

Hey, can I also work on this?

[PranshuSrivastava]

/assign

[Debanitrkl]

Started this https://hackmd.io/@XzECIhDGRqCtGVrLiJFzxQ/rkyZS_JQF for the documentation, will be updating here

[SergeyKanzhelev]

@Debanitrkl if you want to take an individual item like kubernetes/website#25879 - it is very straightforward to write. Issue points to a similar document, need to explain how to drain node, stop kubelet, change config, start kubelet back. Only missing step comparing to the linked document is how to change configuration.

[Debanitrkl]

Okay alright, will begin with that issue

[PranshuSrivastava]

Started this https://hackmd.io/@XzECIhDGRqCtGVrLiJFzxQ/rkyZS_JQF for the documentation, will be updating here

I will also be adding to this file.

[adisky]

Consolidating all the issues

kubernetes/website#25879 : Create a doc to explain how to change the runtime (mostly moving away from dockershim)
helpful docs:

• https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/#upgrade-worker-nodes - --
• https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/configure-cgroup-driver/#migrating-to-the-systemd-driver

kubernetes/website#29665: Dockershim deprecation: Private registries support with Containerd
helpful doc:

• https://github.com/containerd/containerd/blob/main/docs/cri/registry.md

kubernetes/website#28449: Deprecation of the Docker container runtime should be clear in /docs/setup/production-environment/container-runtimes/
(This one is easy fix, only to add a deprecation warning)

[adisky]

We also need to update the guide for running local-up-cluster.sh to use CRI runtimes rather than docker https://github.com/kubernetes/community/blob/master/contributors/devel/running-locally.md

[sftim]

/triage accepted
for SIG Docs

[sftim]

Triaging for SIG Docs
/priority important-soon

[sftim]

#97252 is the actual code change BTW

[shannonxtreme]

Since this issue is focused on the basic migration guide, let's discuss the structure. @SergeyKanzhelev @sftim please feel free to correct or add to this.

---

Migrate from Docker to containerd

• Overview of the page, who it applies to (people using Docker in Kubernetes who are upgrading to 1.24+), and why containerd. Mention slight differences for other preferred runtimes and to see their install instructions for help with those.

Before you begin

• Standard before you begin and version check
• kubeadm (is this required? What are the alternatives?)

Find your container runtime

• Use the content in the existing how-to

Check for Docker dependencies

• Use the guidance in (or link to) the existing page.

Use the systemd cgroup driver

• Use the instructions in Migrating to systemd

Migrate worker nodes to containerd

For each worker node using Docker, do the following:

1. Cordon
2. Drain
3. Uninstall Docker
4. Install containerd
5. Change kubeadm flags to point to the new endpoint and systemd
6. Start the kubelet
7. Describe the node
8. Uncordon the node

Repeat for every worker node. Then find the container runtime again to verify it's migrated.

Migrate control plane nodes to containerd

Warn about kubelet and control plane unavailability if control plane is a single node.

Steps are same as worker nodes. Tips for troubleshooting:

• Use journalctl and crictl to follow logs
• Reset the node after draining it

What's next

• Add guide for installing crictl
• Link to https://kubernetes.io/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents/

[shannonxtreme]

I'm happy to take this on and draft a page up for review, using Sergey's existing page as a base :)

[Debanitrkl]

@shannonxtreme I'm working on this kubernetes/website#30141 here see if you could help out

[mrbobbytables]

@shannonxtreme @Debanitrkl

• Cordon
• Drain
• Uninstall Docker
• Install containerd
• Change kubeadm flags to point to the new endpoint and systemd
• Start the kubelet
• Describe the node
• Uncordon the node

One optional step to potentially include might be the export of images from docker to import into containerd. It doesn't necessarily have to be a step, but a callout or FYI for folk to automate if they don't want to potentially retrigger downloading images again (there are sadly a fair amount of people with 10GB+ images 😬 ). It could even be a 1 liner that pipes from docker save to ctr -n=k8s.io images import

[afbjorklund]

It could even be a 1 liner that pipes from docker save to ctr -n=k8s.io images import

Too bad that crictl doesn't handle "load", but I suppose it's docker push and crictl pull

[afbjorklund]

Add guide for installing crictl

https://kubernetes.io/docs/tasks/debug-application-cluster/crictl/

[sftim]

callout or FYI for folk to automate if they don't want to potentially retrigger downloading images again (there are sadly a fair amount of people with 10GB+ images grimacing )

MVP: point out that it's something to consider

[endocrimes]

There's also https://github.com/containerd/nerdctl#whale-nerdctl-load - (and nerdctl in general) for helping folks through the transition.

[afbjorklund]

There's also https://github.com/containerd/nerdctl#whale-nerdctl-load - (and nerdctl in general) for helping folks through the transition.

And there is as well sudo podman load, if deciding to replace docker with cri-o instead of replacing docker with containerd.

https://docs.podman.io/en/latest/markdown/podman-load.1.html

[sftim]

@afbjorklund I recommend shifting this kind of discussion into issue 106917 - https://github.com/kubernetes/kubernetes/issues/106917

I'd like to treat this issue is a parent / umbrella issue for work we've already accepted.

[afbjorklund]

Missed that it was only about containerd, sorry

[nate-double-u]

/milestone 1.24

[k8s-ci-robot]

@nate-double-u: The provided milestone is not valid for this repository. Milestones in this repository: [next-candidate, v1.16, v1.17, v1.18, v1.19, v1.20, v1.21, v1.22, v1.23, v1.24, v1.25, v1.26]

Use /milestone clear to clear the milestone.

In response to this:

/milestone 1.24

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[chrisnegus]

The PRs associated with the issue represent a lot of good work. They seem to all be merged or closed at this point. I'm going to close this Issue now. However, please feel free to reopen or, better yet, open a new issue if we have missed any work still needing to be done on this topic.
/close

[k8s-ci-robot]

@chrisnegus: Closing this issue.

In response to this:

The PRs associated with the issue represent a lot of good work. They seem to all be merged or closed at this point. I'm going to close this Issue now. However, please feel free to reopen or, better yet, open a new issue if we have missed any work still needing to be done on this topic.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.