---
# System prepended metadata

title: Removing dockershim from kubelet

---

---
title: Removing dockershim from kubelet 
authors:
  - "@resouer"
  - "@derekwaynecarr"
  - "@dims"
owning-sig: sig-node
reviewers:
  - "@yujuhong"
  - "@dchen1107"
  - "@derekwaynecarr"
  - "@dashpole"
  - "@sjennning"
approvers:
  - "@DawnChen"
  - "@yujuhong"
  - "@dashpole"
  - "@sjennning"
creation-date: 2020-09-14
last-updated: 2020-09-14
status: provisional
---

# Removing dockershim from kubelet

## Table of Contents

- [Terms](#terms)
- [Summary](#summary)
- [Motivation](#motivation)
  * [Pros](#pros)
  * [Cons](#cons)
  * [Goals](#goals)
  * [Non-Goals](#non-goals)
- [Proposal](#proposal)
  * [Dockershim removal plan](#dockershim-removal-plan)
  * [Dockershim removal criteria](#dockershim-removal-criteria)
  * [Test Plan](#test-plan)
  * [Graduation Criteria](#graduation-criteria)
- [Implementation History](#implementation-history)

## Terms

- **CRI:** Container Runtime Interface – a plugin interface which enables kubelet to use a wide variety of container runtimes, without the need to recompile.


## Summary

CRI for docker (i.e. dockershim) is currently a built-in container runtime in kubelet code base. This proposal aims at a deprecation and subsequent removal of dockershim from kubelet.

## Motivation

In Kubernetes, CRI is the used as the "default" container runtime, while currently the CRI of docker (a.k.a. dockershim) is part of kubelet code and coupled with kubelet's lifecycle. 

This is not ideal as kubelet then has dependency on specific container runtime which leads to maintenance burden for not only developers in sig-node, but also cluster administrators when critical issues (e.g. runc CVE) happen to container runtimes. The pros of removing dockershim is straightforward:

### Pros
- Docker is not special and should be just a CRI implementation just like every other CRI implementation in our ecosystem. 
- Currently, dockershim "enjoys" some backdoors for various reasons (see [legacyLogProvider](https://cs.k8s.io/?q=legacyLogProvider&i=nope&files=&repos=kubernetes/kubernetes) for example) . Removing these "features" should eliminate maintenance burden of kubelet.
- A cri-dockerd can be maintained independently by folks who are interested in keeping this functionality
- Over time we can remove vendored docker dependencies in kubelet.

Having said that, cons of removal built-in dockershim requires lots of attention:

### Cons
- Deployment pain with a new binary in addition to kubelet.
  - An additional component may aggravate the complexity currently. It may be relieved with docker version evolutions.
- The number of affected users maybe large.
  - Users must change existing use experience when using Kubernetes and docker.
  - Users have to change their existing workflows to adapt to this new changes.
  - And other unrecorded stuff.
- Updating all the eco-system tools to avoid dependencies on docker.
- Many people use the built in dockershim for in-cluster image build. While that may not be something we recommend for a variety of reasons, it will be a breaking change for these users.
- CRI is still in alpha，should probably get a 1.0 out there splitting out dockershim completely from kubelet. There needs to be another KEP for graduating the CRI API version.
- Existing CNI and CSI plugins may also be affected.
- cri-dockerd will vendor kubernetes/kubernetes, that may be tough.
- cri-dockerd as an independent software running on node should be allocated enough resource to guarantee its availability.

> You can check [the discussion in sig-node mailing list](https://groups.google.com/forum/#!msg/kubernetes-sig-node/0qVzfugYhro/l6Au216XAgAJ) for more details. 

### Goals

- A concrete dockershim removal criteria.
- A brief plan to remove dockershim spanning multiple releases.

### Non-Goals

- Refactoring or re-design of dockershim itself due to deprecation.

## Proposal

### Dockershim removal criteria

- CRI itself is alpha. So we need another KEP to graduate CRI API.
- kubelet has no dependency on dockershim/docker in its whole lifecycle. This is already done using the `dockerless` tag
- All node related features are CRI generic and have no "back door" dependency on dockershim/docker.
- Deprecate and remove, or replace all Docker-specific features.
- Reasonable benchmark result of performance degradation after moving dockershim to out-of-tree.
- E2E test framework has been updated with fully support of out-of-tree CRI container runtime.

### Dockershim removal plan

Step 1: Deprecate in-tree dockershim and decouple dockershim from kubelet.

Target releases: 1.20, 1.21, 1.22

Actions:

- Mark in-tree dockershim as "maintenance mode":
  - CRI generic changes/features can continue on dockershim.
  - WIP efforts on dockershim can continue and go to complete.
  - dockershim/docker specific changes/features should be rejected.
- Deprecate the legacy features of dockershim in kubelet by providing a specific timeline. Currently, kubelet still has:
  - vendored dockershim 
  - flags that are used to configure dockershim.
  - support to get container logs when docker uses journald as the driver.
  - logic of moving docker processes to a given cgroup
  - TBD anything else?
- Ensure e2e/Node e2e test framework is CRI generic and test cases are independent of container runtime.
- Refactoring e2e/Node e2e test framework to include CRI for docker installation (or use other CRI container runtime).
  - Ensure cluster/node e2e are 100% CRI focused.
  - Ensure test-infra install appropriate CRI implementations in e2e machines. 
- Ensure Windows scenarios that currently depend on docker are fully supported in alternative CRI implementations

Step 2: Completely remove in-tree dockershim from kubelet.

Target releases: Deprecation should be for at least a year. So the earliest possible release after that time period.

Actions:

- Document and announce migration guide.
- Delete in-tree dockershim code from kubelet after certain "grace period".


### Test Plan

_To be filled until targeted at a release._

### Graduation Criteria

_To be filled until targeted at a release._

## Implementation History

- 2020-09-21: Initial KEP sent out for discussion & reviewing.
