From b10decb87caac82046da85f77cf11438a41aa542 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 15 Jan 2021 22:16:26 +0000 Subject: [PATCH] migrating from dockershim --- .../migrating-from-dockershim/_index.md | 21 +++++ ...k-if-dockershim-deprecation-affects-you.md | 85 +++++++++++++++++++ ...migrating-telemetry-and-security-agents.md | 80 +++++++++++++++++ 3 files changed, 186 insertions(+) create mode 100755 content/en/docs/tasks/administer-cluster/migrating-from-dockershim/_index.md create mode 100644 content/en/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-deprecation-affects-you.md create mode 100644 content/en/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents.md diff --git a/content/en/docs/tasks/administer-cluster/migrating-from-dockershim/_index.md b/content/en/docs/tasks/administer-cluster/migrating-from-dockershim/_index.md new file mode 100755 index 0000000000000..6a186e3766b61 --- /dev/null +++ b/content/en/docs/tasks/administer-cluster/migrating-from-dockershim/_index.md @@ -0,0 +1,21 @@ +--- +title: "Migrating from dockershim" +weight: 10 +content_type: task +--- + + + +This section presents information you need to know when migrating from +dockershim to other container runtimes. + +Since the announcement of [dockershim deprecation](/blog/2020/12/08/kubernetes-1-20-release-announcement/#dockershim-deprecation) +in Kubernetes 1.20, there were questions on how this will affect various workloads and Kubernetes +installations. You can find this blog post useful to understand the problem better: [Dockershim Deprecation FAQ](/blog/2020/12/02/dockershim-faq/) + +It is recommended to migrate from dockershim to alternative container runtimes. +Check out [container runtimes](/docs/setup/production-environment/container-runtimes/) +section to know your options. Make sure to +[report issues](https://github.com/kubernetes/kubernetes/issues) you encountered +with the migration. So the issue can be fixed in a timely manner and your cluster would be +ready for dockershim removal. diff --git a/content/en/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-deprecation-affects-you.md b/content/en/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-deprecation-affects-you.md new file mode 100644 index 0000000000000..766db38485062 --- /dev/null +++ b/content/en/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-deprecation-affects-you.md @@ -0,0 +1,85 @@ +--- +title: Check whether Dockershim deprecation affects you +content_type: task +reviewers: +- SergeyKanzhelev +weight: 20 +--- + + + +The `dockershim` component of Kubernetes allows to use Docker as a Kubernetes's +{{< glossary_tooltip text="container runtime" term_id="container-runtime" >}}. +Kubernetes' built-in `dockershim` component was deprecated in release v1.20. + +This page explains how your cluster could be using Docker as a container runtime, +provides details on the role that `dockershim` plays when in use, and shows steps +you can take to check whether any workloads could be affected by `dockershim` deprecation. + +## Finding if your app has a dependencies on Docker {#find-docker-dependencies} + +If you are using Docker for building your application containers, you can still +run these containers on any container runtime. This use of Docker does not count +as a dependency on Docker as a container runtime. + +When alternative container runtime is used, executing Docker commands may either +not work or yield unexpected output. This is how you can find whether you have a +dependency on Docker: + +1. Make sure no privileged Pods execute Docker commands. +2. Check that scripts and apps running on nodes outside of Kubernetes + infrastructure do not execute Docker commands. It might be: + - SSH to nodes to troubleshoot; + - Node startup scripts; + - Monitoring and security agents installed on nodes directly. +3. Third-party tools that perform above mentioned privileged operations. See + [Migrating telemetry and security agents from dockershim](/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents) + for more information. +4. Make sure there is no indirect dependencies on dockershim behavior. + This is an edge case and unlikely to affect your application. Some tooling may be configured + to react to Docker-specific behaviors, for example, raise alert on specific metrics or search for + a specific log message as part of troubleshooting instructions. + If you have such tooling configured, test the behavior on test + cluster before migration. + +## Dependency on Docker explained {#role-of-dockershim} + +A [container runtime](/docs/concepts/containers/#container-runtimes) is software that can +execute the containers that make up a Kubernetes pod. Kubernetes is responsible for orchestration +and scheduling of Pods; on each node, the {{< glossary_tooltip text="kubelet" term_id="kubelet" >}} +uses the container runtime interface as an abstraction so that you can use any compatible +container runtime. + +In its earliest releases, Kubernetes offered compatibility with just one container runtime: Docker. +Later in the Kubernetes project's history, cluster operators wanted to adopt additional container runtimes. +The CRI was designed to allow this kind of flexibility - and the kubelet began supporting CRI. However, +because Docker existed before the CRI specification was invented, the Kubernetes project created an +adapter component, `dockershim`. The dockershim adapter allows the kubelet to interact with Docker as +if Docker were a CRI compatible runtime. + +You can read about it in [Kubernetes Containerd integration goes GA](/blog/2018/05/24/kubernetes-containerd-integration-goes-ga/) blog post. + +![Dockershim vs. CRI with Containerd](/images/blog/2018-05-24-kubernetes-containerd-integration-goes-ga/cri-containerd.png) + +Switching to Containerd as a container runtime eliminates the middleman. All the +same containers can be run by container runtimes like Containerd as before. But +now, since containers schedule directly with the container runtime, they are not visible to Docker. +So any Docker tooling or fancy UI you might have used +before to check on these containers is no longer available. + +You cannot get container information using `docker ps` or `docker inspect` +commands. As you cannot list containers, you cannot get logs, stop containers, +or execute something inside container using `docker exec`. + +{{< note >}} + +If you're running workloads via Kubernetes, the best way to stop a container is through +the Kubernetes API rather than directly through the container runtime (this advice applies +for all container runtimes, not just Docker). + +{{< /note >}} + +You can still pull images or build them using `docker build` command. But images +built or pulled by Docker would not be visible to container runtime and +Kubernetes. They needed to be pushed to some registry to allow them to be used +by Kubernetes. diff --git a/content/en/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents.md b/content/en/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents.md new file mode 100644 index 0000000000000..dd813754e4ab4 --- /dev/null +++ b/content/en/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents.md @@ -0,0 +1,80 @@ +--- +title: Migrating telemetry and security agents from dockershim +content_type: task +reviewers: +- SergeyKanzhelev +weight: 70 +--- + + + +With Kubernetes 1.20 dockershim was deprecated. From the +[Dockershim Deprecation FAQ](/blog/2020/12/02/dockershim-faq/) +you might already know that most apps do not have a direct dependency on runtime hosting +containers. However, there are still a lot of telemetry and security agents +that has a dependency on docker to collect containers metadata, logs and +metrics. This document aggregates information on how to detect these +dependencies and links on how to migrate these agents to use generic tools or +alternative runtimes. + +## Telemetry and security agents + +There are a few ways agents may run on Kubernetes cluster. Agents may run on +nodes directly or as DaemonSets. + +### Why do telemetry agents rely on Docker? + +Historically, Kubernetes was built on top of Docker. Kubernetes is managing +networking and scheduling, Docker was placing and operating containers on a +node. So you can get scheduling-related metadata like a pod name from Kubernetes +and containers state information from Docker. Over time more runtimes were +created to manage containers. Also there are projects and Kubernetes features +that generalize container status information extraction across many runtimes. + +Some agents are tied specifically to the Docker tool. The agents may run +commands like [`docker ps`](https://docs.docker.com/engine/reference/commandline/ps/) +or [`docker top`](https://docs.docker.com/engine/reference/commandline/top/) to list +containers and processes or [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) +to subscribe on docker logs. With the deprecating of Docker as a container runtime, +these commands will not work any longer. + +### Identify DaemonSets that depend on Docker {#identify-docker-dependency} + +If a pod wants to make calls to the `dockerd` running on the node, the pod must either: + +- mount the filesystem containing the Docker daemon's privileged socket, as a + {{< glossary_tooltip text="volume" term_id="volume" >}}; or +- mount the specific path of the Docker daemon's privileged socket directly, also as a volume. + +For example: on COS images, Docker exposes its Unix domain socket at +`/var/run/docker.sock` This means that the pod spec will include a +`hostPath` volume mount of `/var/run/docker.sock`. + +Here's a sample shell script to find Pods that have a mount directly mapping the +Docker socket. This script outputs the namespace and name of the pod. You can +remove the grep `/var/run/docker.sock` to review other mounts. + +```bash +kubectl get pods --all-namespaces \ +-o=jsonpath='{range .items[*]}{"\n"}{.metadata.namespace}{":\t"}{.metadata.name}{":\t"}{range .spec.volumes[*]}{.hostPath.path}{", "}{end}{end}' \ +| sort \ +| grep '/var/run/docker.sock' +``` + +{{< note >}} +There are alternative ways for a pod to access Docker on the host. For instance, the parent +directory `/var/run` may be mounted instead of the full path (like in [this +example](https://gist.github.com/itaysk/7bc3e56d69c4d72a549286d98fd557dd)). +The script above only detects the most common uses. +{{< /note >}} + +### Detecting Docker dependency from node agents + +In case your cluster nodes are customized and install additional security and +telemetry agents on the node, make sure to check with the vendor of the agent whether it has dependency on Docker. + +### Telemetry and security agent vendors + +We keep the work in progress version of migration instructions for various telemetry and security agent vendors +in [Google doc](https://docs.google.com/document/d/1ZFi4uKit63ga5sxEiZblfb-c23lFhvy6RXVPikS8wf0/edit#). +Please contact the vendor to get up to date instructions for migrating from dockershim.