⚠️ This is an automatically published staged repository for Kubernetes.
Contributions, including issues and pull requests, should be made to the main Kubernetes repository: https://github.com/kubernetes/kubernetes.
This repository is read-only for importing, and not used for direct contributions.
See CONTRIBUTING.md for more details.

Purpose

This repository contains the definitions for the Container Runtime Interface (CRI). CRI is a plugin interface which enables kubelet to use a wide variety of container runtimes, without the need to recompile. CRI consists of a protocol buffers and gRPC API. Read more about CRI API at kubernetes docs.

The repository kubernetes/cri-api is a mirror of https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/cri-api. Please do not file issues or submit PRs against the kubernetes/cri-api repository as it is readonly, all development is done in kubernetes/kubernetes.

The CRI API is defined in kubernetes/kubernetes repository and is only intended to be used for kubelet to container runtime interactions, or for node-level troubleshooting using a tool such as crictl. It is not a common purpose container runtime API for general use, and is intended to be Kubernetes-centric. We try to avoid it, but there may be logic within a container runtime that optimizes for the order or specific parameters of call(s) that the kubelet makes.

Version skew policy and feature development

Please read about:

• CRI API version skew policy
• Kubernetes feature development and container runtimes

Community, discussion, contribution, and support

Learn how to engage with the Kubernetes community on the community page.

You can reach the maintainers of this repository at:

• Slack: #sig-node (on https://kubernetes.slack.com -- get an invite at slack.kubernetes.io)
• Mailing List: https://groups.google.com/a/kubernetes.io/g/sig-node

Issues can be filed at https://github.com/kubernetes/kubernetes/issues. See CONTRIBUTING.md.

Code of Conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.

Contribution Guidelines

See CONTRIBUTING.md for more information. Please note that kubernetes/cri-api is a readonly mirror repository, all development is done at kubernetes/kubernetes.

Change history

Here is the change history of the Container Runtime Interface protocol. The change history is maintained manually:

v1.36

git diff v1.35.0 v1.36.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• [KEP-5825] cri-api: Add streaming RPCs for CRI list operations

  • Added streaming alternatives to list methods to avoid gRPC message size limits: StreamPodSandboxes, StreamContainers, StreamContainerStats, StreamPodSandboxStats, StreamPodSandboxMetrics, and StreamImages.
  • Added corresponding request and response types for the new streaming methods.

• Stricter image reference meaning

  • Clarified that PullImageResponse.image_ref MUST match Image.id, Container.image_id, and ContainerStatus.image_id.

• [KEP-5365] Implement Image Volume with Digest

  • Added image_ref field to the type ImageSpec.

• Update OCI image volume type description to remove "noexec" attribute

  • Updated comment on the Mount type.

• Add alpha-2 stage implementation for UserNamespacesHostNetworkSupport

  • Added user_namespaces_host_network field to the type RuntimeFeatures.

• Clarify RemoveImage CRI API call

  • Added comments to RemoveImage and ImageFsInfo explaining behavior when an image is referenced by multiple tags.

v1.35

git diff v1.34.0 1.35.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

No changes

v1.34

git diff v1.33.0 v1.34.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• Removed the gogo dependency
• Added debug_redact flags to the following fields of AuthConfig: password, auth, identity_token, registry_token.

v1.33

git diff v1.32.0 v1.33.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• Clarify the behavior when the host_port value is set to 0 in CRI

  • Added clarifying comment to the [host_port] field of [PortMapping].

• [KEP-4639] Graduate image volume sources to beta

  • Added image_sub_path to the type Mount to represent the subpath inside the image to mount.

• [FG:InPlacePodVerticalScaling] Add UpdatePodSandboxResources CRI method

  • New method UpdatePodSandboxResources to synchronously updates the PodSandboxConfig with the pod-level resource configuration.
  • Added the UpdatePodSandboxResourcesRequest type to pass as an argument to UpdatePodSandboxResources.
  • Added the UpdatePodSandboxResourcesResponse empty type to return from the UpdatePodSandboxResources.

• Withdraw alpha support for HostNetwork containers on Windows

  • Added clarifying comment on the network field of the type WindowsNamespaceOption as HostNetwork containers are not supported.

• Surface Pressure Stall Information (PSI) metrics

  • Added io field to the types LinuxPodSandboxStats and ContainerStats to represent the IO usage.
  • Added psi field to the type CpuUsage.
  • Added types IoUsage, PsiStats, and PsiData to represent IO usage and PSI statistics.

• KEP 4960: Container Stop Signals

  • Added the field stop_signal to the ContainerConfig type.
  • Added the enum Signal listing all possible stop signals.

v1.32

git diff v1.31.0 v1.32.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• CRI: Add field to support CPU affinity on Windows
  • CRI field affinity_cpus to WindowsContainerResources struct to support CPU affinity on Windows. This field will be used by Windows CPU manager to set the logical processors to affinitize for a particular container down to containerd/hcsshim.

v1.31

git diff v1.30.0 v1.31.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• KEP-3619: Add NodeStatus.Features.SupplementalGroupsPolicy API and e2e

  • Added features field to the type StatusResponse for the runtime to kubelet handshake on what features are supported

• KEP-3619: Fine-grained SupplementalGroups control

  • Added supplemental_groups_policy field to types LinuxContainerSecurityContext and LinuxSandboxSecurityContext
  • Added user field to the type ContainerStatus to represent actual user for the container

• [KEP-4639] Add OCI VolumeSource CRI API

  • Added image field to the type Mount to represent the OCI VolumeSource

v1.30

git diff v1.29.0 v1.30.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• Recursive Read-only (RRO) mounts

  • Added RuntimeHandler and RuntimeHandlerFeatures type
  • Added recursive_read_only field to type Mount
  • Added runtime_handlers field to type StatusResponse

• Add user_namespaces field to RuntimeHandlerFeatures

  • Added user_namespaces field to type RuntimeHandlerFeatures

• Add image_id to CRI Container message

  • Added image_id field to type Container

• Add image_id to CRI ContainerStatus message

  • Added image_id field to type ContainerStatus

v1.29

git diff v1.28.0 v1.29.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• Add runtime handler field to ImageSpec struct

  • Added runtime_handler field to type ImageSpec

• Add container filesystem to the ImageFsInfoResponse

  • Added container_filesystems field to type ImageFsInfoResponse

v1.28

git diff v1.27.0 v1.28.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• cri-api: fix comment lines about PROPAGATION_PRIVATE

  • Fixed comment lines about PROPAGATION_PRIVATE

• Add user specified image to CRI ContainerConfig

  • Added the user_specified_image field to type ImageSpec

• kubelet: get cgroup driver config from CRI

  • Added rpc for querying runtime configuration
  • Added cavieats about cgroup driver field

• Add swap to stats to Summary API and Prometheus endpoints (/stats/summary and /metrics/resource)

  • Added SwapUsage type
  • Added SwapUsage field to ContainerStats type

• Expose commit memory used in WindowsMemoryUsage struct

  • Added the commit_memory_bytes field to type WindowsMemoryUsage

v1.27

git diff v1.26.0 v1.27.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• CRI: Add CDI device info for containers

  • New type CDIDevice was introduced and added to container config

• Add mappings for volumes

  • Added new fields to the type Mount expressing runtime UID/GID mappings for the mount.

v1.26

git diff v1.25.0 v1.26.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• CRI: Add Windows Podsandbox Stats

  • Added fields to the type WindowsPodSandboxStats expressing stats required to be collected from windows pods.

• Windows hostnetwork alpha

  • New type WindowsNamespaceOption introduced
  • The type WindowsSandboxSecurityContext has a new field namespace_options of type WindowsNamespaceOption

• Improve the API description of PodSecurityContext.SupplementalGroups to clarify its unfamiliar behavior

  • Clarified the expected behavior of SupplementalGroups field of PodSecurityContext

• Add Support for Evented PLEG

  • The type ContainerEventResponse updated: the field pod_sandbox_metadata removed and fields pod_sandbox_status and containers_statuses added.
  • The type PodSandboxStatusResponse has a new fields containers_statuses and timestamp

v1.25

git diff v1.24.0 v1.25.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• kubelet: add CRI definitions for user namespaces

  • The new type UserNamespace introduced to represent user namespaces id mapping
  • The type NamespaceOption has a new field userns_options of type UserNamespace

• Minimal checkpointing support

  • The new method CheckpointContainer introduced with the corresponding request and response types

• Update CRI API to support Evented PLEG

  • The new streaming method GetContainerEvents is introduced with the corresponding request and response types

• CRI changes to support in-place pod resize

  • The new type ContainerResources is introduced
  • The type ContainerStatus has a new field resources of type ContainerResources
  • The semantic of UpdateContainerResources updated. The method must be implemented as synchronous and return error on failure

v1.24

git diff v1.23.0 v1.24.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• Update CRI-API Capabilities to include a field that allows us to set ambient capabilities

  • The type Capability has a new string field add_ambient_capabilities

• CRI-API - Add rootfs size to WindowsContainerResources

  • The type WindowsContainerResources has a new int64 field rootfs_size_in_bytes

v1.23

git diff v1.22.0 v1.23.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• CRI: add fields for pod level stats to satisfy the /stats/summary API

  • New functions PodSandboxStats, ListPodSandboxStats with the corresponding types of request and response objects are introduced

• pass sandbox resource requirements over CRI

  • New fields on LinuxPodSandboxConfig: overhead and resources of type LinuxContainerResources.

• prevents garbage collection from removing pinned images

  • The type Image has a new boolean field pinned

v1.22

git diff v1.21.0 v1.22.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• Windows host process support

  • PodSandboxConfig has windows field of type WindowsPodSandboxConfig
  • New type WindowsPodSandboxConfig introduced
  • New type WindowsSandboxSecurityContext introduced
  • The type WindowsContainerSecurityContext has a new host_process boolean field

• Feature: add unified on CRI to support cgroup v2

  • The type LinuxContainerResources has a new field unified which is a map of strings

• Alpha node swap support

  • The type LinuxContainerResources has a new memory_swap_limit_in_bytes int64 field

v1.21

git diff v1.20.0 v1.21.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

No changes

v1.20

git diff v1.19.0 v1.20.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto

• CRI v1 introduced