CRI: the Container Runtime Interface

What is CRI?

CRI (Container Runtime Interface) consists of a protobuf API, specifications/requirements (to-be-added), and libraries for container runtimes to integrate with kubelet on a node. CRI is currently in Alpha.

In the future, we plan to add more developer tools such as the CRI validation tests.

Why develop CRI?

Prior to the existence of CRI, container runtimes (e.g., docker, rkt) were integrated with kubelet through implementing an internal, high-level interface in kubelet. The entrance barrier for runtimes was high because the integration required understanding the internals of kubelet and contributing to the main Kubernetes repository. More importantly, this would not scale because every new addition incurs a significant maintenance overhead in the main Kubernetes repository.

Kubernetes aims to be extensible. CRI is one small, yet important step to enable pluggable container runtimes and build a healthier ecosystem.

How to use CRI?

For Kubernetes 1.6+:

  1. Start the image and runtime services on your node. You can have a single service acting as both image and runtime services.
  2. Set the kubelet flags
    • Pass the unix socket(s) to which your services listen to kubelet: --container-runtime-endpoint and --image-service-endpoint.
    • Use the “remote” runtime by --container-runtime=remote.

CRI is still young and we are actively incorporating feedback from developers to improve the API. Although we strive to maintain backward compatibility, developers should expect occasional API breaking changes.

For Kubernetes 1.5, additional flags are required: - Set apiserver flag --feature-gates=StreamingProxyRedirects=true. - Set kubelet flag --experimental-cri=true.

Does Kubelet use CRI today?

Yes, Kubelet always uses CRI except for using the rktnetes integration.

The old, pre-CRI Docker integration was removed in 1.7.

Specifications, design documents and proposals

The Kubernetes 1.5 blog post on CRI serves as a general introduction.

Below is a mixed list of CRI specifications/requirements, design docs and proposals. We are working on adding more documentation for the API.

Work-In-Progress CRI runtimes

Status update

Kubernetes v1.7 release (Docker-CRI integration GA, container metrics API)

  • The Docker CRI integration has been promoted to GA.
  • The legacy, non-CRI Docker integration has been completely removed from Kubelet. The deprecated --enable-cri flag has been removed.
  • CRI has been extended to support collecting container metrics from the runtime.

Kubernetes v1.6 release (Docker-CRI integration Beta)

The Docker CRI integration has been promoted to Beta, and been enabled by default in Kubelet. - Upgrade: It is recommended to drain your node before upgrading the Kubelet. If you choose to perform in-place upgrade, the Kubelet will restart all Kubernetes-managed containers on the node. - Resource usage and performance: There is no performance regression in our measurement. The memory usage of Kubelet increases slightly (~0.27MB per pod) due to the additional gRPC serialization for CRI. - Disable: To disable the Docker CRI integration and fall back to the old implementation, set --enable-cri=false. Note that the old implementation has been deprecated and is scheduled to be removed in the next release. You are encouraged to migrate to CRI as early as possible. - Others: The Docker container naming/labeling scheme has changed significantly in 1.6. This is perceived as implementation detail and should not be relied upon by any external tools or scripts.

Kubernetes v1.5 release (CRI v1alpha1)

CRI known issues:

  • #27097: Container metrics are not yet defined in CRI.
  • #36401: The new container log path/format is not yet supported by the logging pipeline (e.g., fluentd, GCL).
  • CRI may not be compatible with other experimental features (e.g., Seccomp).
  • Streaming server needs to be hardened.
    • #36666: Authentication.
    • #36187: Avoid including user data in the redirect URL.

Docker CRI integration known issues

  • Docker compatibility: Support only Docker v1.11 and v1.12.
  • Network:
    • #35457: Does not support host ports.
    • #37315: Does not support bandwidth shaping.
  • Exec/attach/port-forward (streaming requests):
    • #35747: Does not support nsenter as the exec handler (--exec-handler=nsenter).
    • Also see CRI 1.5 known issues for limitations on CRI streaming.