Skip to content

Commit 4f244bc

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #25787 from SergeyKanzhelev/migrateFromDockershim
Migrating from dockershim documentation
2 parents 008e41f + b10decb commit 4f244bc

File tree

3 files changed

+186
-0
lines changed

3 files changed

+186
-0
lines changed

‎content/en/docs/tasks/administer-cluster/migrating-from-dockershim/_index.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: "Migrating from dockershim"
3+
weight: 10
4+
content_type: task
5+
---
6+
7+
<!-- overview -->
8+
9+
This section presents information you need to know when migrating from
10+
dockershim to other container runtimes.
11+
12+
Since the announcement of [dockershim deprecation](/blog/2020/12/08/kubernetes-1-20-release-announcement/#dockershim-deprecation)
13+
in Kubernetes 1.20, there were questions on how this will affect various workloads and Kubernetes
14+
installations. You can find this blog post useful to understand the problem better: [Dockershim Deprecation FAQ](/blog/2020/12/02/dockershim-faq/)
15+
16+
It is recommended to migrate from dockershim to alternative container runtimes.
17+
Check out [container runtimes](/docs/setup/production-environment/container-runtimes/)
18+
section to know your options. Make sure to
19+
[report issues](https://github.com/kubernetes/kubernetes/issues) you encountered
20+
with the migration. So the issue can be fixed in a timely manner and your cluster would be
21+
ready for dockershim removal.

‎content/en/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-deprecation-affects-you.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Check whether Dockershim deprecation affects you
3+
content_type: task
4+
reviewers:
5+
- SergeyKanzhelev
6+
weight: 20
7+
---
8+
9+
<!-- overview -->
10+
11+
The `dockershim` component of Kubernetes allows to use Docker as a Kubernetes's
12+
{{< glossary_tooltip text="container runtime" term_id="container-runtime" >}}.
13+
Kubernetes' built-in `dockershim` component was deprecated in release v1.20.
14+
15+
This page explains how your cluster could be using Docker as a container runtime,
16+
provides details on the role that `dockershim` plays when in use, and shows steps
17+
you can take to check whether any workloads could be affected by `dockershim` deprecation.
18+
19+
## Finding if your app has a dependencies on Docker {#find-docker-dependencies}
20+
21+
If you are using Docker for building your application containers, you can still
22+
run these containers on any container runtime. This use of Docker does not count
23+
as a dependency on Docker as a container runtime.
24+
25+
When alternative container runtime is used, executing Docker commands may either
26+
not work or yield unexpected output. This is how you can find whether you have a
27+
dependency on Docker:
28+
29+
1. Make sure no privileged Pods execute Docker commands.
30+
2. Check that scripts and apps running on nodes outside of Kubernetes
31+
infrastructure do not execute Docker commands. It might be:
32+
- SSH to nodes to troubleshoot;
33+
- Node startup scripts;
34+
- Monitoring and security agents installed on nodes directly.
35+
3. Third-party tools that perform above mentioned privileged operations. See
36+
[Migrating telemetry and security agents from dockershim](/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents)
37+
for more information.
38+
4. Make sure there is no indirect dependencies on dockershim behavior.
39+
This is an edge case and unlikely to affect your application. Some tooling may be configured
40+
to react to Docker-specific behaviors, for example, raise alert on specific metrics or search for
41+
a specific log message as part of troubleshooting instructions.
42+
If you have such tooling configured, test the behavior on test
43+
cluster before migration.
44+
45+
## Dependency on Docker explained {#role-of-dockershim}
46+
47+
A [container runtime](/docs/concepts/containers/#container-runtimes) is software that can
48+
execute the containers that make up a Kubernetes pod. Kubernetes is responsible for orchestration
49+
and scheduling of Pods; on each node, the {{< glossary_tooltip text="kubelet" term_id="kubelet" >}}
50+
uses the container runtime interface as an abstraction so that you can use any compatible
51+
container runtime.
52+
53+
In its earliest releases, Kubernetes offered compatibility with just one container runtime: Docker.
54+
Later in the Kubernetes project's history, cluster operators wanted to adopt additional container runtimes.
55+
The CRI was designed to allow this kind of flexibility - and the kubelet began supporting CRI. However,
56+
because Docker existed before the CRI specification was invented, the Kubernetes project created an
57+
adapter component, `dockershim`. The dockershim adapter allows the kubelet to interact with Docker as
58+
if Docker were a CRI compatible runtime.
59+
60+
You can read about it in [Kubernetes Containerd integration goes GA](/blog/2018/05/24/kubernetes-containerd-integration-goes-ga/) blog post.
61+
62+
![Dockershim vs. CRI with Containerd](/images/blog/2018-05-24-kubernetes-containerd-integration-goes-ga/cri-containerd.png)
63+
64+
Switching to Containerd as a container runtime eliminates the middleman. All the
65+
same containers can be run by container runtimes like Containerd as before. But
66+
now, since containers schedule directly with the container runtime, they are not visible to Docker.
67+
So any Docker tooling or fancy UI you might have used
68+
before to check on these containers is no longer available.
69+
70+
You cannot get container information using `docker ps` or `docker inspect`
71+
commands. As you cannot list containers, you cannot get logs, stop containers,
72+
or execute something inside container using `docker exec`.
73+
74+
{{< note >}}
75+
76+
If you're running workloads via Kubernetes, the best way to stop a container is through
77+
the Kubernetes API rather than directly through the container runtime (this advice applies
78+
for all container runtimes, not just Docker).
79+
80+
{{< /note >}}
81+
82+
You can still pull images or build them using `docker build` command. But images
83+
built or pulled by Docker would not be visible to container runtime and
84+
Kubernetes. They needed to be pushed to some registry to allow them to be used
85+
by Kubernetes.

‎content/en/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Migrating telemetry and security agents from dockershim
3+
content_type: task
4+
reviewers:
5+
- SergeyKanzhelev
6+
weight: 70
7+
---
8+
9+
<!-- overview -->
10+
11+
With Kubernetes 1.20 dockershim was deprecated. From the
12+
[Dockershim Deprecation FAQ](/blog/2020/12/02/dockershim-faq/)
13+
you might already know that most apps do not have a direct dependency on runtime hosting
14+
containers. However, there are still a lot of telemetry and security agents
15+
that has a dependency on docker to collect containers metadata, logs and
16+
metrics. This document aggregates information on how to detect these
17+
dependencies and links on how to migrate these agents to use generic tools or
18+
alternative runtimes.
19+
20+
## Telemetry and security agents
21+
22+
There are a few ways agents may run on Kubernetes cluster. Agents may run on
23+
nodes directly or as DaemonSets.
24+
25+
### Why do telemetry agents rely on Docker?
26+
27+
Historically, Kubernetes was built on top of Docker. Kubernetes is managing
28+
networking and scheduling, Docker was placing and operating containers on a
29+
node. So you can get scheduling-related metadata like a pod name from Kubernetes
30+
and containers state information from Docker. Over time more runtimes were
31+
created to manage containers. Also there are projects and Kubernetes features
32+
that generalize container status information extraction across many runtimes.
33+
34+
Some agents are tied specifically to the Docker tool. The agents may run
35+
commands like [`docker ps`](https://docs.docker.com/engine/reference/commandline/ps/)
36+
or [`docker top`](https://docs.docker.com/engine/reference/commandline/top/) to list
37+
containers and processes or [docker logs](https://docs.docker.com/engine/reference/commandline/logs/)
38+
to subscribe on docker logs. With the deprecating of Docker as a container runtime,
39+
these commands will not work any longer.
40+
41+
### Identify DaemonSets that depend on Docker {#identify-docker-dependency}
42+
43+
If a pod wants to make calls to the `dockerd` running on the node, the pod must either:
44+
45+
- mount the filesystem containing the Docker daemon's privileged socket, as a
46+
{{< glossary_tooltip text="volume" term_id="volume" >}}; or
47+
- mount the specific path of the Docker daemon's privileged socket directly, also as a volume.
48+
49+
For example: on COS images, Docker exposes its Unix domain socket at
50+
`/var/run/docker.sock` This means that the pod spec will include a
51+
`hostPath` volume mount of `/var/run/docker.sock`.
52+
53+
Here's a sample shell script to find Pods that have a mount directly mapping the
54+
Docker socket. This script outputs the namespace and name of the pod. You can
55+
remove the grep `/var/run/docker.sock` to review other mounts.
56+
57+
```bash
58+
kubectl get pods --all-namespaces \
59+
-o=jsonpath='{range .items[*]}{"\n"}{.metadata.namespace}{":\t"}{.metadata.name}{":\t"}{range .spec.volumes[*]}{.hostPath.path}{", "}{end}{end}' \
60+
| sort \
61+
| grep '/var/run/docker.sock'
62+
```
63+
64+
{{< note >}}
65+
There are alternative ways for a pod to access Docker on the host. For instance, the parent
66+
directory `/var/run` may be mounted instead of the full path (like in [this
67+
example](https://gist.github.com/itaysk/7bc3e56d69c4d72a549286d98fd557dd)).
68+
The script above only detects the most common uses.
69+
{{< /note >}}
70+
71+
### Detecting Docker dependency from node agents
72+
73+
In case your cluster nodes are customized and install additional security and
74+
telemetry agents on the node, make sure to check with the vendor of the agent whether it has dependency on Docker.
75+
76+
### Telemetry and security agent vendors
77+
78+
We keep the work in progress version of migration instructions for various telemetry and security agent vendors
79+
in [Google doc](https://docs.google.com/document/d/1ZFi4uKit63ga5sxEiZblfb-c23lFhvy6RXVPikS8wf0/edit#).
80+
Please contact the vendor to get up to date instructions for migrating from dockershim.

0 commit comments

Comments
 (0)