cri-dockerd

This adapter provides a shim for Docker Engine that lets you control Docker via the Kubernetes Container Runtime Interface.

IMPORTANT

For users running 0.2.5 or above, the default network plugin is cni. Kubernetes 1.24+ has removed kubenet and other network plumbing from upstream as part of the dockershim removal/deprecation. In order for a cluster to become operational, Calico, Flannel, Weave, or another CNI should be used.

For CI workflows, basic functionality can be provided via containernetworking/plugins.

Motivation

Mirantis and Docker have agreed to partner to maintain the shim code standalone outside Kubernetes, as a conformant CRI interface for the Docker Engine API. For Mirantis customers, that means that Docker Engine’s commercially supported version, Mirantis Container Runtime (MCR), will be CRI compliant. This means that you can continue to build Kubernetes based on the Docker Engine as before, just switching from the built in dockershim to the external one.

Mirantis and Docker intend to work together on making sure it continues to work as well as before and that it passes all the conformance tests and continues to work just like the built in version did. Mirantis will be using this in Mirantis Kubernetes Engine, and Docker will continue to ship this shim in Docker Desktop.

You can find more information about the context for this tool in Don't Panic: Kubernetes and Docker and on the Mirantis blog.

Using cri-dockerd

Install

The easiest way to install cri-dockerd is to use one of the pre-built binaries or packages from the releases page. There are numerous supported platforms and using a pre-built package will install the binary and setup your system to run it as a service.

Please refer to your platform's documentation for how to install a package for additional help with these.

Advanced Setup

Installing manually

Note: the release packages will install to /usr/bin which is reserved for binaries managed by a package manager. Manual installation doesn't involve a package manager and thus uses /usr/local/bin and the service file must be edited to reflect this.

If you would like to install the project manually, you will need to place the binary somewhere in your PATH and setup a service to run it. The following command is a manual install for a Linux system using systemd:

install -o root -g root -m 0755 cri-dockerd /usr/local/bin/cri-dockerd
install packaging/systemd/* /etc/systemd/system
sed -i -e 's,/usr/bin/cri-dockerd,/usr/local/bin/cri-dockerd,' /etc/systemd/system/cri-docker.service
systemctl daemon-reload
systemctl enable --now cri-docker.socket

To use with Kubernetes

The default network plugin for cri-dockerd is set to cni on Linux. To change this, --network-plugin=${plugin} can be passed in as a command line argument if invoked manually, or the systemd unit file (/usr/lib/systemd/system/cri-docker.service if not enabled yet, or /etc/systemd/system/multi-user.target.wants/cri-docker.service as a symlink if it is enabled) should be edited to add this argument, followed by systemctl daemon-reload and restarting the service (if running)

Development

Building

If you would like to build the project yourself, you will need to have Go installed. You can find directions for installing the latest version on its website:

Install the latest version of Go

Once you have Go installed, you can build the project by running the following command:

make cri-dockerd

This will output the binary to the project's root directory as cri-dockerd. You can then run it directly or install it using the manual process above.

To build for a specific architecture, add ARCH= as an argument, where ARCH is a known build target for Go.

Development Setup

When developing, it is nice to have a separate environment to test in so that you don't have to worry about breaking your system. An easy way to do this is by setting up a minikube cluster since it uses cri-dockerd by default. You can grab the latest version from their repo's releases page:

You must grab the latest release from their release's page. The version installed by their Getting Started page is not compatible with the latest version of cri-dockerd.

Install the latest version of minikube

You'll then be able to create a cluster in minikube's VM by running:

minikube start

Once the cluster is up, we have a make command that will build cri-dockerd and swap it out for the version running in the cluster. You can run this command by running:

make dev