/*
Copyright 2020 The Kubernetes Authors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
// To regenerate api.pb.go run `hack/update-codegen.sh protobindings`
syntax = "proto3";
package runtime.v1;
option go_package = "k8s.io/cri-api/pkg/apis/runtime/v1";
import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.goproto_stringer_all) = false;
option (gogoproto.stringer_all) = true;
option (gogoproto.goproto_getters_all) = true;
option (gogoproto.marshaler_all) = true;
option (gogoproto.sizer_all) = true;
option (gogoproto.unmarshaler_all) = true;
option (gogoproto.goproto_unrecognized_all) = false;
// Runtime service defines the public APIs for remote container runtimes
service RuntimeService {
// Version returns the runtime name, runtime version, and runtime API version.
rpc Version(VersionRequest) returns (VersionResponse) {}
// RunPodSandbox creates and starts a pod-level sandbox. Runtimes must ensure
// the sandbox is in the ready state on success.
rpc RunPodSandbox(RunPodSandboxRequest) returns (RunPodSandboxResponse) {}
// StopPodSandbox stops any running process that is part of the sandbox and
// reclaims network resources (e.g., IP addresses) allocated to the sandbox.
// If there are any running containers in the sandbox, they must be forcibly
// terminated.
// This call is idempotent, and must not return an error if all relevant
// resources have already been reclaimed. kubelet will call StopPodSandbox
// at least once before calling RemovePodSandbox. It will also attempt to
// reclaim resources eagerly, as soon as a sandbox is not needed. Hence,
// multiple StopPodSandbox calls are expected.
rpc StopPodSandbox(StopPodSandboxRequest) returns (StopPodSandboxResponse) {}
// RemovePodSandbox removes the sandbox. If there are any running containers
// in the sandbox, they must be forcibly terminated and removed.
// This call is idempotent, and must not return an error if the sandbox has
// already been removed.
rpc RemovePodSandbox(RemovePodSandboxRequest) returns (RemovePodSandboxResponse) {}
// PodSandboxStatus returns the status of the PodSandbox. If the PodSandbox is not
// present, returns an error.
rpc PodSandboxStatus(PodSandboxStatusRequest) returns (PodSandboxStatusResponse) {}
// ListPodSandbox returns a list of PodSandboxes.
rpc ListPodSandbox(ListPodSandboxRequest) returns (ListPodSandboxResponse) {}
// CreateContainer creates a new container in specified PodSandbox
rpc CreateContainer(CreateContainerRequest) returns (CreateContainerResponse) {}
// StartContainer starts the container.
rpc StartContainer(StartContainerRequest) returns (StartContainerResponse) {}
// StopContainer stops a running container with a grace period (i.e., timeout).
// This call is idempotent, and must not return an error if the container has
// already been stopped.
// The runtime must forcibly kill the container after the grace period is
// reached.
rpc StopContainer(StopContainerRequest) returns (StopContainerResponse) {}
// RemoveContainer removes the container. If the container is running, the
// container must be forcibly removed.
// This call is idempotent, and must not return an error if the container has
// already been removed.
rpc RemoveContainer(RemoveContainerRequest) returns (RemoveContainerResponse) {}
// ListContainers lists all containers by filters.
rpc ListContainers(ListContainersRequest) returns (ListContainersResponse) {}
// ContainerStatus returns status of the container. If the container is not
// present, returns an error.
rpc ContainerStatus(ContainerStatusRequest) returns (ContainerStatusResponse) {}
// UpdateContainerResources updates ContainerConfig of the container synchronously.
// If runtime fails to transactionally update the requested resources, an error is returned.
rpc UpdateContainerResources(UpdateContainerResourcesRequest) returns (UpdateContainerResourcesResponse) {}
// ReopenContainerLog asks runtime to reopen the stdout/stderr log file
// for the container. This is often called after the log file has been
// rotated. If the container is not running, container runtime can choose
// to either create a new log file and return nil, or return an error.
// Once it returns error, new container log file MUST NOT be created.
rpc ReopenContainerLog(ReopenContainerLogRequest) returns (ReopenContainerLogResponse) {}
// ExecSync runs a command in a container synchronously.
rpc ExecSync(ExecSyncRequest) returns (ExecSyncResponse) {}
// Exec prepares a streaming endpoint to execute a command in the container.
rpc Exec(ExecRequest) returns (ExecResponse) {}
// Attach prepares a streaming endpoint to attach to a running container.
rpc Attach(AttachRequest) returns (AttachResponse) {}
// PortForward prepares a streaming endpoint to forward ports from a PodSandbox.
rpc PortForward(PortForwardRequest) returns (PortForwardResponse) {}
// ContainerStats returns stats of the container. If the container does not
// exist, the call returns an error.
rpc ContainerStats(ContainerStatsRequest) returns (ContainerStatsResponse) {}
// ListContainerStats returns stats of all running containers.
rpc ListContainerStats(ListContainerStatsRequest) returns (ListContainerStatsResponse) {}
// PodSandboxStats returns stats of the pod sandbox. If the pod sandbox does not
// exist, the call returns an error.
rpc PodSandboxStats(PodSandboxStatsRequest) returns (PodSandboxStatsResponse) {}
// ListPodSandboxStats returns stats of the pod sandboxes matching a filter.
rpc ListPodSandboxStats(ListPodSandboxStatsRequest) returns (ListPodSandboxStatsResponse) {}
// UpdateRuntimeConfig updates the runtime configuration based on the given request.
rpc UpdateRuntimeConfig(UpdateRuntimeConfigRequest) returns (UpdateRuntimeConfigResponse) {}
// Status returns the status of the runtime.
rpc Status(StatusRequest) returns (StatusResponse) {}
// CheckpointContainer checkpoints a container
rpc CheckpointContainer(CheckpointContainerRequest) returns (CheckpointContainerResponse) {}
// GetContainerEvents gets container events from the CRI runtime
rpc GetContainerEvents(GetEventsRequest) returns (stream ContainerEventResponse) {}
// ListMetricDescriptors gets the descriptors for the metrics that will be returned in ListPodSandboxMetrics.
// This list should be static at startup: either the client and server restart together when
// adding or removing metrics descriptors, or they should not change.
// Put differently, if ListPodSandboxMetrics references a name that is not described in the initial
// ListMetricDescriptors call, then the metric will not be broadcasted.
rpc ListMetricDescriptors(ListMetricDescriptorsRequest) returns (ListMetricDescriptorsResponse) {}
// ListPodSandboxMetrics gets pod sandbox metrics from CRI Runtime
rpc ListPodSandboxMetrics(ListPodSandboxMetricsRequest) returns (ListPodSandboxMetricsResponse) {}
// RuntimeConfig returns configuration information of the runtime.
// A couple of notes:
// - The RuntimeConfigRequest object is not to be confused with the contents of UpdateRuntimeConfigRequest.
// The former is for having runtime tell Kubelet what to do, the latter vice versa.
// - It is the expectation of the Kubelet that these fields are static for the lifecycle of the Kubelet.
// The Kubelet will not re-request the RuntimeConfiguration after startup, and CRI implementations should
// avoid updating them without a full node reboot.
rpc RuntimeConfig(RuntimeConfigRequest) returns (RuntimeConfigResponse) {}
}
// ImageService defines the public APIs for managing images.
service ImageService {
// ListImages lists existing images.
rpc ListImages(ListImagesRequest) returns (ListImagesResponse) {}
// ImageStatus returns the status of the image. If the image is not
// present, returns a response with ImageStatusResponse.Image set to
// nil.
rpc ImageStatus(ImageStatusRequest) returns (ImageStatusResponse) {}
// PullImage pulls an image with authentication config.
rpc PullImage(PullImageRequest) returns (PullImageResponse) {}
// RemoveImage removes the image.
// This call is idempotent, and must not return an error if the image has
// already been removed.
rpc RemoveImage(RemoveImageRequest) returns (RemoveImageResponse) {}
// ImageFSInfo returns information of the filesystem that is used to store images.
rpc ImageFsInfo(ImageFsInfoRequest) returns (ImageFsInfoResponse) {}
}
message VersionRequest {
// Version of the kubelet runtime API.
string version = 1;
}
message VersionResponse {
// Version of the kubelet runtime API.
string version = 1;
// Name of the container runtime.
string runtime_name = 2;
// Version of the container runtime. The string must be
// semver-compatible.
string runtime_version = 3;
// API version of the container runtime. The string must be
// semver-compatible.
string runtime_api_version = 4;
}
// DNSConfig specifies the DNS servers and search domains of a sandbox.
message DNSConfig {
// List of DNS servers of the cluster.
repeated string servers = 1;
// List of DNS search domains of the cluster.
repeated string searches = 2;
// List of DNS options. See https://linux.die.net/man/5/resolv.conf
// for all available options.
repeated string options = 3;
}
enum Protocol {
TCP = 0;
UDP = 1;
SCTP = 2;
}
// PortMapping specifies the port mapping configurations of a sandbox.
message PortMapping {
// Protocol of the port mapping.
Protocol protocol = 1;
// Port number within the container. Default: 0 (not specified).
int32 container_port = 2;
// Port number on the host. Default: 0 (not specified).
int32 host_port = 3;
// Host IP.
string host_ip = 4;
}
enum MountPropagation {
// No mount propagation ("rprivate" in Linux terminology).
PROPAGATION_PRIVATE = 0;
// Mounts get propagated from the host to the container ("rslave" in Linux).
PROPAGATION_HOST_TO_CONTAINER = 1;
// Mounts get propagated from the host to the container and from the
// container to the host ("rshared" in Linux).
PROPAGATION_BIDIRECTIONAL = 2;
}
// Mount specifies a host volume to mount into a container.
message Mount {
// Path of the mount within the container.
string container_path = 1;
// Path of the mount on the host. Has to be empty if the image field below
// is provided, because those fields are mutually exclusive. If the image
// field below is nil and the host path doesn't exist, then runtimes should
// report an error. If the hostpath is a symbolic link, runtimes should
// follow the symlink and mount the real destination to container.
string host_path = 2;
// If set, the mount is read-only.
bool readonly = 3;
// If set, the mount needs SELinux relabeling.
bool selinux_relabel = 4;
// Requested propagation mode.
MountPropagation propagation = 5;
// UidMappings specifies the runtime UID mappings for the mount.
repeated IDMapping uidMappings = 6;
// GidMappings specifies the runtime GID mappings for the mount.
repeated IDMapping gidMappings = 7;
// If set to true, the mount is made recursive read-only.
// In this CRI API, recursive_read_only is a plain true/false boolean, although its equivalent
// in the Kubernetes core API is a quaternary that can be nil, "Enabled", "IfPossible", or "Disabled".
// kubelet translates that quaternary value in the core API into a boolean in this CRI API.
// Remarks:
// - nil is just treated as false
// - when set to true, readonly must be explicitly set to true, and propagation must be PRIVATE (0).
// - (readonly == false && recursive_read_only == false) does not make the mount read-only.
bool recursive_read_only = 8;
// Mount an image reference (image ID, with or without digest), which is a
// special use case for image volume mounts. If this field is set, then
// host_path should be unset. All OCI mounts are per feature definition
// readonly. The kubelet does an PullImage RPC and evaluates the returned
// PullImageResponse.image_ref value, which is then set to the
// ImageSpec.image field. Runtimes are expected to mount the image as
// required.
// Introduced in the OCI Volume Source KEP: https://kep.k8s.io/4639
ImageSpec image = 9;
}
// IDMapping describes host to container ID mappings for a pod sandbox.
message IDMapping {
// HostId is the id on the host.
uint32 host_id = 1;
// ContainerId is the id in the container.
uint32 container_id = 2;
// Length is the size of the range to map.
uint32 length = 3;
}
// A NamespaceMode describes the intended namespace configuration for each
// of the namespaces (Network, PID, IPC) in NamespaceOption. Runtimes should
// map these modes as appropriate for the technology underlying the runtime.
enum NamespaceMode {
// A POD namespace is common to all containers in a pod.
// For example, a container with a PID namespace of POD expects to view
// all of the processes in all of the containers in the pod.
POD = 0;
// A CONTAINER namespace is restricted to a single container.
// For example, a container with a PID namespace of CONTAINER expects to
// view only the processes in that container.
CONTAINER = 1;
// A NODE namespace is the namespace of the Kubernetes node.
// For example, a container with a PID namespace of NODE expects to view
// all of the processes on the host running the kubelet.
NODE = 2;
// TARGET targets the namespace of another container. When this is specified,
// a target_id must be specified in NamespaceOption and refer to a container
// previously created with NamespaceMode CONTAINER. This containers namespace
// will be made to match that of container target_id.
// For example, a container with a PID namespace of TARGET expects to view
// all of the processes that container target_id can view.
TARGET = 3;
}
// UserNamespace describes the intended user namespace configuration for a pod sandbox.
message UserNamespace {
// Mode is the NamespaceMode for this UserNamespace.
// Note: NamespaceMode for UserNamespace currently supports only POD and NODE, not CONTAINER OR TARGET.
NamespaceMode mode = 1;
// Uids specifies the UID mappings for the user namespace.
repeated IDMapping uids = 2;
// Gids specifies the GID mappings for the user namespace.
repeated IDMapping gids = 3;
}
// NamespaceOption provides options for Linux namespaces.
message NamespaceOption {
// Network namespace for this container/sandbox.
// Note: There is currently no way to set CONTAINER scoped network in the Kubernetes API.
// Namespaces currently set by the kubelet: POD, NODE
NamespaceMode network = 1;
// PID namespace for this container/sandbox.
// Note: The CRI default is POD, but the v1.PodSpec default is CONTAINER.
// The kubelet's runtime manager will set this to CONTAINER explicitly for v1 pods.
// Namespaces currently set by the kubelet: POD, CONTAINER, NODE, TARGET
NamespaceMode pid = 2;
// IPC namespace for this container/sandbox.
// Note: There is currently no way to set CONTAINER scoped IPC in the Kubernetes API.
// Namespaces currently set by the kubelet: POD, NODE
NamespaceMode ipc = 3;
// Target Container ID for NamespaceMode of TARGET. This container must have been
// previously created in the same pod. It is not possible to specify different targets
// for each namespace.
string target_id = 4;
// UsernsOptions for this pod sandbox.
// The Kubelet picks the user namespace configuration to use for the pod sandbox. The mappings
// are specified as part of the UserNamespace struct. If the struct is nil, then the POD mode
// must be assumed. This is done for backward compatibility with older Kubelet versions that
// do not set a user namespace.
UserNamespace userns_options = 5;
}
// SupplementalGroupsPolicy defines how supplemental groups
// of the first container processes are calculated.
enum SupplementalGroupsPolicy {
// Merge means that the container's provided SupplementalGroups
// and FsGroup (specified in SecurityContext) will be merged with
// the primary user's groups as defined in the container image
// (in /etc/group).
Merge = 0;
// Strict means that the container's provided SupplementalGroups
// and FsGroup (specified in SecurityContext) will be used instead of
// any groups defined in the container image.
Strict = 1;
}
// Int64Value is the wrapper of int64.
message Int64Value {
// The value.
int64 value = 1;
}
// LinuxSandboxSecurityContext holds linux security configuration that will be
// applied to a sandbox. Note that:
// 1) It does not apply to containers in the pods.
// 2) It may not be applicable to a PodSandbox which does not contain any running
// process.
message LinuxSandboxSecurityContext {
// Configurations for the sandbox's namespaces.
// This will be used only if the PodSandbox uses namespace for isolation.
NamespaceOption namespace_options = 1;
// Optional SELinux context to be applied.
SELinuxOption selinux_options = 2;
// UID to run sandbox processes as, when applicable.
Int64Value run_as_user = 3;
// GID to run sandbox processes as, when applicable. run_as_group should only
// be specified when run_as_user is specified; otherwise, the runtime MUST error.
Int64Value run_as_group = 8;
// If set, the root filesystem of the sandbox is read-only.
bool readonly_rootfs = 4;
// List of groups applied to the first process run in each container.
// supplemental_groups_policy can control how groups will be calculated.
repeated int64 supplemental_groups = 5;
// supplemental_groups_policy defines how supplemental groups of the first
// container processes are calculated.
// Valid values are "Merge" and "Strict".
// If not specified, "Merge" is used.
SupplementalGroupsPolicy supplemental_groups_policy = 11;
// Indicates whether the sandbox will be asked to run a privileged
// container. If a privileged container is to be executed within it, this
// MUST be true.
// This allows a sandbox to take additional security precautions if no
// privileged containers are expected to be run.
bool privileged = 6;
// Seccomp profile for the sandbox.
SecurityProfile seccomp = 9;
// AppArmor profile for the sandbox.
SecurityProfile apparmor = 10;
// Seccomp profile for the sandbox, candidate values are:
// * runtime/default: the default profile for the container runtime
// * unconfined: unconfined profile, ie, no seccomp sandboxing
// * localhost/<full-path-to-profile>: the profile installed on the node.
// <full-path-to-profile> is the full path of the profile.
// Default: "", which is identical with unconfined.
string seccomp_profile_path = 7 [deprecated=true];
}
// A security profile which can be used for sandboxes and containers.
message SecurityProfile {
// Available profile types.
enum ProfileType {
// The container runtime default profile should be used.
RuntimeDefault = 0;
// Disable the feature for the sandbox or the container.
Unconfined = 1;
// A pre-defined profile on the node should be used.
Localhost = 2;
}
// Indicator which `ProfileType` should be applied.
ProfileType profile_type = 1;
// Indicates that a pre-defined profile on the node should be used.
// Must only be set if `ProfileType` is `Localhost`.
// For seccomp, it must be an absolute path to the seccomp profile.
// For AppArmor, this field is the AppArmor `<profile name>/`
string localhost_ref = 2;
}
// LinuxPodSandboxConfig holds platform-specific configurations for Linux
// host platforms and Linux-based containers.
message LinuxPodSandboxConfig {
// Parent cgroup of the PodSandbox.
// The cgroupfs style syntax will be used, but the container runtime can
// convert it to systemd semantics if needed.
string cgroup_parent = 1;
// LinuxSandboxSecurityContext holds sandbox security attributes.
LinuxSandboxSecurityContext security_context = 2;
// Sysctls holds linux sysctls config for the sandbox.
map<string, string> sysctls = 3;
// Optional overhead represents the overheads associated with this sandbox
LinuxContainerResources overhead = 4;
// Optional resources represents the sum of container resources for this sandbox
LinuxContainerResources resources = 5;
}
// PodSandboxMetadata holds all necessary information for building the sandbox name.
// The container runtime is encouraged to expose the metadata associated with the
// PodSandbox in its user interface for better user experience. For example,
// the runtime can construct a unique PodSandboxName based on the metadata.
message PodSandboxMetadata {
// Pod name of the sandbox. Same as the pod name in the Pod ObjectMeta.
string name = 1;
// Pod UID of the sandbox. Same as the pod UID in the Pod ObjectMeta.
string uid = 2;
// Pod namespace of the sandbox. Same as the pod namespace in the Pod ObjectMeta.
string namespace = 3;
// Attempt number of creating the sandbox. Default: 0.
uint32 attempt = 4;
}
// PodSandboxConfig holds all the required and optional fields for creating a
// sandbox.
message PodSandboxConfig {
// Metadata of the sandbox. This information will uniquely identify the
// sandbox, and the runtime should leverage this to ensure correct
// operation. The runtime may also use this information to improve UX, such
// as by constructing a readable name.
PodSandboxMetadata metadata = 1;
// Hostname of the sandbox. Hostname could only be empty when the pod
// network namespace is NODE.
string hostname = 2;
// Path to the directory on the host in which container log files are
// stored.
// By default the log of a container going into the LogDirectory will be
// hooked up to STDOUT and STDERR. However, the LogDirectory may contain
// binary log files with structured logging data from the individual
// containers. For example, the files might be newline separated JSON
// structured logs, systemd-journald journal files, gRPC trace files, etc.
// E.g.,
// PodSandboxConfig.LogDirectory = `/var/log/pods/<NAMESPACE>_<NAME>_<UID>/`
// ContainerConfig.LogPath = `containerName/Instance#.log`
string log_directory = 3;
// DNS config for the sandbox.
DNSConfig dns_config = 4;
// Port mappings for the sandbox.
repeated PortMapping port_mappings = 5;
// Key-value pairs that may be used to scope and select individual resources.
map<string, string> labels = 6;
// Unstructured key-value map that may be set by the kubelet to store and
// retrieve arbitrary metadata. This will include any annotations set on a
// pod through the Kubernetes API.
//
// Annotations MUST NOT be altered by the runtime; the annotations stored
// here MUST be returned in the PodSandboxStatus associated with the pod
// this PodSandboxConfig creates.
//
// In general, in order to preserve a well-defined interface between the
// kubelet and the container runtime, annotations SHOULD NOT influence
// runtime behaviour.
//
// Annotations can also be useful for runtime authors to experiment with
// new features that are opaque to the Kubernetes APIs (both user-facing
// and the CRI). Whenever possible, however, runtime authors SHOULD
// consider proposing new typed fields for any new features instead.
map<string, string> annotations = 7;
// Optional configurations specific to Linux hosts.
LinuxPodSandboxConfig linux = 8;
// Optional configurations specific to Windows hosts.
WindowsPodSandboxConfig windows = 9;
}
message RunPodSandboxRequest {
// Configuration for creating a PodSandbox.
PodSandboxConfig config = 1;
// Named runtime configuration to use for this PodSandbox.
// If the runtime handler is unknown, this request should be rejected. An
// empty string should select the default handler, equivalent to the
// behavior before this feature was added.
// See https://git.k8s.io/enhancements/keps/sig-node/585-runtime-class
string runtime_handler = 2;
}
message RunPodSandboxResponse {
// ID of the PodSandbox to run.
string pod_sandbox_id = 1;
}
message StopPodSandboxRequest {
// ID of the PodSandbox to stop.
string pod_sandbox_id = 1;
}
message StopPodSandboxResponse {}
message RemovePodSandboxRequest {
// ID of the PodSandbox to remove.
string pod_sandbox_id = 1;
}
message RemovePodSandboxResponse {}
message PodSandboxStatusRequest {
// ID of the PodSandbox for which to retrieve status.
string pod_sandbox_id = 1;
// Verbose indicates whether to return extra information about the pod sandbox.
bool verbose = 2;
}
// PodIP represents an ip of a Pod
message PodIP{
// an ip is a string representation of an IPv4 or an IPv6
string ip = 1;
}
// PodSandboxNetworkStatus is the status of the network for a PodSandbox.
// Currently ignored for pods sharing the host networking namespace.
message PodSandboxNetworkStatus {
// IP address of the PodSandbox.
string ip = 1;
// list of additional ips (not inclusive of PodSandboxNetworkStatus.Ip) of the PodSandBoxNetworkStatus
repeated PodIP additional_ips = 2;
}
// Namespace contains paths to the namespaces.
message Namespace {
// Namespace options for Linux namespaces.
NamespaceOption options = 2;
}
// LinuxSandboxStatus contains status specific to Linux sandboxes.
message LinuxPodSandboxStatus {
// Paths to the sandbox's namespaces.
Namespace namespaces = 1;
}
enum PodSandboxState {
SANDBOX_READY = 0;
SANDBOX_NOTREADY = 1;
}
// PodSandboxStatus contains the status of the PodSandbox.
message PodSandboxStatus {
// ID of the sandbox.
string id = 1;
// Metadata of the sandbox.
PodSandboxMetadata metadata = 2;
// State of the sandbox.
PodSandboxState state = 3;
// Creation timestamp of the sandbox in nanoseconds. Must be > 0.
int64 created_at = 4;
// Network contains network status if network is handled by the runtime.
PodSandboxNetworkStatus network = 5;
// Linux-specific status to a pod sandbox.
LinuxPodSandboxStatus linux = 6;
// Labels are key-value pairs that may be used to scope and select individual resources.
map<string, string> labels = 7;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding PodSandboxConfig used to
// instantiate the pod sandbox this status represents.
map<string, string> annotations = 8;
// runtime configuration used for this PodSandbox.
string runtime_handler = 9;
}
message PodSandboxStatusResponse {
// Status of the PodSandbox.
PodSandboxStatus status = 1;
// Info is extra information of the PodSandbox. The key could be arbitrary string, and
// value should be in json format. The information could include anything useful for
// debug, e.g. network namespace for linux container based container runtime.
// It should only be returned non-empty when Verbose is true.
map<string, string> info = 2;
// Container statuses
repeated ContainerStatus containers_statuses = 3;
// Timestamp in nanoseconds at which container and pod statuses were recorded
int64 timestamp = 4;
}
// PodSandboxStateValue is the wrapper of PodSandboxState.
message PodSandboxStateValue {
// State of the sandbox.
PodSandboxState state = 1;
}
// PodSandboxFilter is used to filter a list of PodSandboxes.
// All those fields are combined with 'AND'
message PodSandboxFilter {
// ID of the sandbox.
string id = 1;
// State of the sandbox.
PodSandboxStateValue state = 2;
// LabelSelector to select matches.
// Only api.MatchLabels is supported for now and the requirements
// are ANDed. MatchExpressions is not supported yet.
map<string, string> label_selector = 3;
}
message ListPodSandboxRequest {
// PodSandboxFilter to filter a list of PodSandboxes.
PodSandboxFilter filter = 1;
}
// PodSandbox contains minimal information about a sandbox.
message PodSandbox {
// ID of the PodSandbox.
string id = 1;
// Metadata of the PodSandbox.
PodSandboxMetadata metadata = 2;
// State of the PodSandbox.
PodSandboxState state = 3;
// Creation timestamps of the PodSandbox in nanoseconds. Must be > 0.
int64 created_at = 4;
// Labels of the PodSandbox.
map<string, string> labels = 5;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding PodSandboxConfig used to
// instantiate this PodSandbox.
map<string, string> annotations = 6;
// runtime configuration used for this PodSandbox.
string runtime_handler = 7;
}
message ListPodSandboxResponse {
// List of PodSandboxes.
repeated PodSandbox items = 1;
}
message PodSandboxStatsRequest {
// ID of the pod sandbox for which to retrieve stats.
string pod_sandbox_id = 1;
}
message PodSandboxStatsResponse {
PodSandboxStats stats = 1;
}
// PodSandboxStatsFilter is used to filter the list of pod sandboxes to retrieve stats for.
// All those fields are combined with 'AND'.
message PodSandboxStatsFilter {
// ID of the pod sandbox.
string id = 1;
// LabelSelector to select matches.
// Only api.MatchLabels is supported for now and the requirements
// are ANDed. MatchExpressions is not supported yet.
map<string, string> label_selector = 2;
}
message ListPodSandboxStatsRequest {
// Filter for the list request.
PodSandboxStatsFilter filter = 1;
}
message ListPodSandboxStatsResponse {
// Stats of the pod sandbox.
repeated PodSandboxStats stats = 1;
}
// PodSandboxAttributes provides basic information of the pod sandbox.
message PodSandboxAttributes {
// ID of the pod sandbox.
string id = 1;
// Metadata of the pod sandbox.
PodSandboxMetadata metadata = 2;
// Key-value pairs that may be used to scope and select individual resources.
map<string,string> labels = 3;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding PodSandboxStatus used to
// instantiate the PodSandbox this status represents.
map<string,string> annotations = 4;
}
// PodSandboxStats provides the resource usage statistics for a pod.
// The linux or windows field will be populated depending on the platform.
message PodSandboxStats {
// Information of the pod.
PodSandboxAttributes attributes = 1;
// Stats from linux.
LinuxPodSandboxStats linux = 2;
// Stats from windows.
WindowsPodSandboxStats windows = 3;
}
// LinuxPodSandboxStats provides the resource usage statistics for a pod sandbox on linux.
message LinuxPodSandboxStats {
// CPU usage gathered for the pod sandbox.
CpuUsage cpu = 1;
// Memory usage gathered for the pod sandbox.
MemoryUsage memory = 2;
// Network usage gathered for the pod sandbox
NetworkUsage network = 3;
// Stats pertaining to processes in the pod sandbox.
ProcessUsage process = 4;
// Stats of containers in the measured pod sandbox.
repeated ContainerStats containers = 5;
}
// WindowsPodSandboxStats provides the resource usage statistics for a pod sandbox on windows
message WindowsPodSandboxStats {
// CPU usage gathered for the pod sandbox.
WindowsCpuUsage cpu = 1;
// Memory usage gathered for the pod sandbox.
WindowsMemoryUsage memory = 2;
// Network usage gathered for the pod sandbox
WindowsNetworkUsage network = 3;
// Stats pertaining to processes in the pod sandbox.
WindowsProcessUsage process = 4;
// Stats of containers in the measured pod sandbox.
repeated WindowsContainerStats containers = 5;
}
// NetworkUsage contains data about network resources.
message NetworkUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Stats for the default network interface.
NetworkInterfaceUsage default_interface = 2;
// Stats for all found network interfaces, excluding the default.
repeated NetworkInterfaceUsage interfaces = 3;
}
// WindowsNetworkUsage contains data about network resources specific to Windows.
message WindowsNetworkUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Stats for the default network interface.
WindowsNetworkInterfaceUsage default_interface = 2;
// Stats for all found network interfaces, excluding the default.
repeated WindowsNetworkInterfaceUsage interfaces = 3;
}
// NetworkInterfaceUsage contains resource value data about a network interface.
message NetworkInterfaceUsage {
// The name of the network interface.
string name = 1;
// Cumulative count of bytes received.
UInt64Value rx_bytes = 2;
// Cumulative count of receive errors encountered.
UInt64Value rx_errors = 3;
// Cumulative count of bytes transmitted.
UInt64Value tx_bytes = 4;
// Cumulative count of transmit errors encountered.
UInt64Value tx_errors = 5;
}
// WindowsNetworkInterfaceUsage contains resource value data about a network interface specific for Windows.
message WindowsNetworkInterfaceUsage {
// The name of the network interface.
string name = 1;
// Cumulative count of bytes received.
UInt64Value rx_bytes = 2;
// Cumulative count of receive errors encountered.
UInt64Value rx_packets_dropped = 3;
// Cumulative count of bytes transmitted.
UInt64Value tx_bytes = 4;
// Cumulative count of transmit errors encountered.
UInt64Value tx_packets_dropped = 5;
}
// ProcessUsage are stats pertaining to processes.
message ProcessUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Number of processes.
UInt64Value process_count = 2;
}
// WindowsProcessUsage are stats pertaining to processes specific to Windows.
message WindowsProcessUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Number of processes.
UInt64Value process_count = 2;
}
// ImageSpec is an internal representation of an image.
message ImageSpec {
// Container's Image field (e.g. imageID or imageDigest).
string image = 1;
// Unstructured key-value map holding arbitrary metadata.
// ImageSpec Annotations can be used to help the runtime target specific
// images in multi-arch images.
map<string, string> annotations = 2;
// The container image reference specified by the user (e.g. image[:tag] or digest).
// Only set if available within the RPC context.
string user_specified_image = 18;
// Runtime handler to use for pulling the image.
// If the runtime handler is unknown, the request should be rejected.
// An empty string would select the default runtime handler.
string runtime_handler = 19;
}
message KeyValue {
string key = 1;
string value = 2;
}
// LinuxContainerResources specifies Linux specific configuration for
// resources.
message LinuxContainerResources {
// CPU CFS (Completely Fair Scheduler) period. Default: 0 (not specified).
int64 cpu_period = 1;
// CPU CFS (Completely Fair Scheduler) quota. Default: 0 (not specified).
int64 cpu_quota = 2;
// CPU shares (relative weight vs. other containers). Default: 0 (not specified).
int64 cpu_shares = 3;
// Memory limit in bytes. Default: 0 (not specified).
int64 memory_limit_in_bytes = 4;
// OOMScoreAdj adjusts the oom-killer score. Default: 0 (not specified).
int64 oom_score_adj = 5;
// CpusetCpus constrains the allowed set of logical CPUs. Default: "" (not specified).
string cpuset_cpus = 6;
// CpusetMems constrains the allowed set of memory nodes. Default: "" (not specified).
string cpuset_mems = 7;
// List of HugepageLimits to limit the HugeTLB usage of container per page size. Default: nil (not specified).
repeated HugepageLimit hugepage_limits = 8;
// Unified resources for cgroup v2. Default: nil (not specified).
// Each key/value in the map refers to the cgroup v2.
// e.g. "memory.max": "6937202688" or "io.weight": "default 100".
map<string, string> unified = 9;
// Memory swap limit in bytes. Default 0 (not specified).
int64 memory_swap_limit_in_bytes = 10;
}
// HugepageLimit corresponds to the file`hugetlb.<hugepagesize>.limit_in_byte` in container level cgroup.
// For example, `PageSize=1GB`, `Limit=1073741824` means setting `1073741824` bytes to hugetlb.1GB.limit_in_bytes.
message HugepageLimit {
// The value of PageSize has the format <size><unit-prefix>B (2MB, 1GB),
// and must match the <hugepagesize> of the corresponding control file found in `hugetlb.<hugepagesize>.limit_in_bytes`.
// The values of <unit-prefix> are intended to be parsed using base 1024("1KB" = 1024, "1MB" = 1048576, etc).
string page_size = 1;
// limit in bytes of hugepagesize HugeTLB usage.
uint64 limit = 2;
}
// SELinuxOption are the labels to be applied to the container.
message SELinuxOption {
string user = 1;
string role = 2;
string type = 3;
string level = 4;
}
// Capability contains the container capabilities to add or drop
// Dropping a capability will drop it from all sets.
// If a capability is added to only the add_capabilities list then it gets added to permitted,
// inheritable, effective and bounding sets, i.e. all sets except the ambient set.
// If a capability is added to only the add_ambient_capabilities list then it gets added to all sets, i.e permitted
// inheritable, effective, bounding and ambient sets.
// If a capability is added to add_capabilities and add_ambient_capabilities lists then it gets added to all sets, i.e.
// permitted, inheritable, effective, bounding and ambient sets.
message Capability {
// List of capabilities to add.
repeated string add_capabilities = 1;
// List of capabilities to drop.
repeated string drop_capabilities = 2;
// List of ambient capabilities to add.
repeated string add_ambient_capabilities = 3;
}
// LinuxContainerSecurityContext holds linux security configuration that will be applied to a container.
message LinuxContainerSecurityContext {
// Capabilities to add or drop.
Capability capabilities = 1;
// If set, run container in privileged mode.
// Privileged mode is incompatible with the following options. If
// privileged is set, the following features MAY have no effect:
// 1. capabilities
// 2. selinux_options
// 4. seccomp
// 5. apparmor
//
// Privileged mode implies the following specific options are applied:
// 1. All capabilities are added.
// 2. Sensitive paths, such as kernel module paths within sysfs, are not masked.
// 3. Any sysfs and procfs mounts are mounted RW.
// 4. AppArmor confinement is not applied.
// 5. Seccomp restrictions are not applied.
// 6. The device cgroup does not restrict access to any devices.
// 7. All devices from the host's /dev are available within the container.
// 8. SELinux restrictions are not applied (e.g. label=disabled).
bool privileged = 2;
// Configurations for the container's namespaces.
// Only used if the container uses namespace for isolation.
NamespaceOption namespace_options = 3;
// SELinux context to be optionally applied.
SELinuxOption selinux_options = 4;
// UID to run the container process as. Only one of run_as_user and
// run_as_username can be specified at a time.
Int64Value run_as_user = 5;
// GID to run the container process as. run_as_group should only be specified
// when run_as_user or run_as_username is specified; otherwise, the runtime
// MUST error.
Int64Value run_as_group = 12;
// User name to run the container process as. If specified, the user MUST
// exist in the container image (i.e. in the /etc/passwd inside the image),
// and be resolved there by the runtime; otherwise, the runtime MUST error.
string run_as_username = 6;
// If set, the root filesystem of the container is read-only.
bool readonly_rootfs = 7;
// List of groups applied to the first process run in each container.
// supplemental_groups_policy can control how groups will be calculated.
repeated int64 supplemental_groups = 8;
// supplemental_groups_policy defines how supplemental groups of the first
// container processes are calculated.
// Valid values are "Merge" and "Strict".
// If not specified, "Merge" is used.
SupplementalGroupsPolicy supplemental_groups_policy = 17;
// no_new_privs defines if the flag for no_new_privs should be set on the
// container.
bool no_new_privs = 11;
// masked_paths is a slice of paths that should be masked by the container
// runtime, this can be passed directly to the OCI spec.
repeated string masked_paths = 13;
// readonly_paths is a slice of paths that should be set as readonly by the
// container runtime, this can be passed directly to the OCI spec.
repeated string readonly_paths = 14;
// Seccomp profile for the container.
SecurityProfile seccomp = 15;
// AppArmor profile for the container.
SecurityProfile apparmor = 16;
// AppArmor profile for the container, candidate values are:
// * runtime/default: equivalent to not specifying a profile.
// * unconfined: no profiles are loaded
// * localhost/<profile_name>: profile loaded on the node
// (localhost) by name. The possible profile names are detailed at
// https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference
string apparmor_profile = 9 [deprecated=true];
// Seccomp profile for the container, candidate values are:
// * runtime/default: the default profile for the container runtime
// * unconfined: unconfined profile, ie, no seccomp sandboxing
// * localhost/<full-path-to-profile>: the profile installed on the node.
// <full-path-to-profile> is the full path of the profile.
// Default: "", which is identical with unconfined.
string seccomp_profile_path = 10 [deprecated=true];
}
// LinuxContainerConfig contains platform-specific configuration for
// Linux-based containers.
message LinuxContainerConfig {
// Resources specification for the container.
LinuxContainerResources resources = 1;
// LinuxContainerSecurityContext configuration for the container.
LinuxContainerSecurityContext security_context = 2;
}
message LinuxContainerUser {
// uid is the primary uid initially attached to the first process in the container
int64 uid = 1;
// gid is the primary gid initially attached to the first process in the container
int64 gid = 2;
// supplemental_groups are the supplemental groups initially attached to the first process in the container
repeated int64 supplemental_groups = 3;
}
// WindowsNamespaceOption provides options for Windows namespaces.
message WindowsNamespaceOption {
// Network namespace for this container/sandbox.
// Namespaces currently set by the kubelet: POD, NODE
NamespaceMode network = 1;
}
// WindowsSandboxSecurityContext holds platform-specific configurations that will be
// applied to a sandbox.
// These settings will only apply to the sandbox container.
message WindowsSandboxSecurityContext {
// User name to run the container process as. If specified, the user MUST
// exist in the container image and be resolved there by the runtime;
// otherwise, the runtime MUST return error.
string run_as_username = 1;
// The contents of the GMSA credential spec to use to run this container.
string credential_spec = 2;
// Indicates whether the container requested to run as a HostProcess container.
bool host_process = 3;
// Configuration for the sandbox's namespaces
WindowsNamespaceOption namespace_options = 4;
}
// WindowsPodSandboxConfig holds platform-specific configurations for Windows
// host platforms and Windows-based containers.
message WindowsPodSandboxConfig {
// WindowsSandboxSecurityContext holds sandbox security attributes.
WindowsSandboxSecurityContext security_context = 1;
}
// WindowsContainerSecurityContext holds windows security configuration that will be applied to a container.
message WindowsContainerSecurityContext {
// User name to run the container process as. If specified, the user MUST
// exist in the container image and be resolved there by the runtime;
// otherwise, the runtime MUST return error.
string run_as_username = 1;
// The contents of the GMSA credential spec to use to run this container.
string credential_spec = 2;
// Indicates whether a container is to be run as a HostProcess container.
bool host_process = 3;
}
// WindowsContainerConfig contains platform-specific configuration for
// Windows-based containers.
message WindowsContainerConfig {
// Resources specification for the container.
WindowsContainerResources resources = 1;
// WindowsContainerSecurityContext configuration for the container.
WindowsContainerSecurityContext security_context = 2;
}
// WindowsContainerResources specifies Windows specific configuration for
// resources.
message WindowsContainerResources {
// CPU shares (relative weight vs. other containers). Default: 0 (not specified).
int64 cpu_shares = 1;
// Number of CPUs available to the container. Default: 0 (not specified).
int64 cpu_count = 2;
// Specifies the portion of processor cycles that this container can use as a percentage times 100.
int64 cpu_maximum = 3;
// Memory limit in bytes. Default: 0 (not specified).
int64 memory_limit_in_bytes = 4;
// Specifies the size of the rootfs / scratch space in bytes to be configured for this container. Default: 0 (not specified).
int64 rootfs_size_in_bytes = 5;
// Optionally specifies the set of CPUs to affinitize for this container.
repeated WindowsCpuGroupAffinity affinity_cpus = 6;
}
// WindowsCpuGroupAffinity specifies the CPU mask and group to affinitize.
// This is similar to the following _GROUP_AFFINITY structure:
// https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/miniport/ns-miniport-_group_affinity
message WindowsCpuGroupAffinity {
// CPU mask relative to this CPU group.
uint64 cpu_mask = 1;
// Processor group the mask refers to, as returned by
// GetLogicalProcessorInformationEx.
uint32 cpu_group = 2;
}
// ContainerMetadata holds all necessary information for building the container
// name. The container runtime is encouraged to expose the metadata in its user
// interface for better user experience. E.g., runtime can construct a unique
// container name based on the metadata. Note that (name, attempt) is unique
// within a sandbox for the entire lifetime of the sandbox.
message ContainerMetadata {
// Name of the container. Same as the container name in the PodSpec.
string name = 1;
// Attempt number of creating the container. Default: 0.
uint32 attempt = 2;
}
// Device specifies a host device to mount into a container.
message Device {
// Path of the device within the container.
string container_path = 1;
// Path of the device on the host.
string host_path = 2;
// Cgroups permissions of the device, candidates are one or more of
// * r - allows container to read from the specified device.
// * w - allows container to write to the specified device.
// * m - allows container to create device files that do not yet exist.
string permissions = 3;
}
// CDIDevice specifies a CDI device information.
message CDIDevice {
// Fully qualified CDI device name
// for example: vendor.com/gpu=gpudevice1
// see more details in the CDI specification:
// https://github.com/container-orchestrated-devices/container-device-interface/blob/main/SPEC.md
string name = 1;
}
// ContainerConfig holds all the required and optional fields for creating a
// container.
message ContainerConfig {
// Metadata of the container. This information will uniquely identify the
// container, and the runtime should leverage this to ensure correct
// operation. The runtime may also use this information to improve UX, such
// as by constructing a readable name.
ContainerMetadata metadata = 1 ;
// Image to use.
ImageSpec image = 2;
// Command to execute (i.e., entrypoint for docker)
repeated string command = 3;
// Args for the Command (i.e., command for docker)
repeated string args = 4;
// Current working directory of the command.
string working_dir = 5;
// List of environment variable to set in the container.
repeated KeyValue envs = 6;
// Mounts for the container.
repeated Mount mounts = 7;
// Devices for the container.
repeated Device devices = 8;
// Key-value pairs that may be used to scope and select individual resources.
// Label keys are of the form:
// label-key ::= prefixed-name | name
// prefixed-name ::= prefix '/' name
// prefix ::= DNS_SUBDOMAIN
// name ::= DNS_LABEL
map<string, string> labels = 9;
// Unstructured key-value map that may be used by the kubelet to store and
// retrieve arbitrary metadata.
//
// Annotations MUST NOT be altered by the runtime; the annotations stored
// here MUST be returned in the ContainerStatus associated with the container
// this ContainerConfig creates.
//
// In general, in order to preserve a well-defined interface between the
// kubelet and the container runtime, annotations SHOULD NOT influence
// runtime behaviour.
map<string, string> annotations = 10;
// Path relative to PodSandboxConfig.LogDirectory for container to store
// the log (STDOUT and STDERR) on the host.
// E.g.,
// PodSandboxConfig.LogDirectory = `/var/log/pods/<NAMESPACE>_<NAME>_<UID>/`
// ContainerConfig.LogPath = `containerName/Instance#.log`
string log_path = 11;
// Variables for interactive containers, these have very specialized
// use-cases (e.g. debugging).
bool stdin = 12;
bool stdin_once = 13;
bool tty = 14;
// Configuration specific to Linux containers.
LinuxContainerConfig linux = 15;
// Configuration specific to Windows containers.
WindowsContainerConfig windows = 16;
// CDI devices for the container.
repeated CDIDevice CDI_devices = 17;
}
message CreateContainerRequest {
// ID of the PodSandbox in which the container should be created.
string pod_sandbox_id = 1;
// Config of the container.
ContainerConfig config = 2;
// Config of the PodSandbox. This is the same config that was passed
// to RunPodSandboxRequest to create the PodSandbox. It is passed again
// here just for easy reference. The PodSandboxConfig is immutable and
// remains the same throughout the lifetime of the pod.
PodSandboxConfig sandbox_config = 3;
}
message CreateContainerResponse {
// ID of the created container.
string container_id = 1;
}
message StartContainerRequest {
// ID of the container to start.
string container_id = 1;
}
message StartContainerResponse {}
message StopContainerRequest {
// ID of the container to stop.
string container_id = 1;
// Timeout in seconds to wait for the container to stop before forcibly
// terminating it. Default: 0 (forcibly terminate the container immediately)
int64 timeout = 2;
}
message StopContainerResponse {}
message RemoveContainerRequest {
// ID of the container to remove.
string container_id = 1;
}
message RemoveContainerResponse {}
enum ContainerState {
CONTAINER_CREATED = 0;
CONTAINER_RUNNING = 1;
CONTAINER_EXITED = 2;
CONTAINER_UNKNOWN = 3;
}
// ContainerStateValue is the wrapper of ContainerState.
message ContainerStateValue {
// State of the container.
ContainerState state = 1;
}
// ContainerFilter is used to filter containers.
// All those fields are combined with 'AND'
message ContainerFilter {
// ID of the container.
string id = 1;
// State of the container.
ContainerStateValue state = 2;
// ID of the PodSandbox.
string pod_sandbox_id = 3;
// LabelSelector to select matches.
// Only api.MatchLabels is supported for now and the requirements
// are ANDed. MatchExpressions is not supported yet.
map<string, string> label_selector = 4;
}
message ListContainersRequest {
ContainerFilter filter = 1;
}
// Container provides the runtime information for a container, such as ID, hash,
// state of the container.
message Container {
// ID of the container, used by the container runtime to identify
// a container.
string id = 1;
// ID of the sandbox to which this container belongs.
string pod_sandbox_id = 2;
// Metadata of the container.
ContainerMetadata metadata = 3;
// Spec of the image.
ImageSpec image = 4;
// Digested reference to the image in use.
string image_ref = 5;
// State of the container.
ContainerState state = 6;
// Creation time of the container in nanoseconds.
int64 created_at = 7;
// Key-value pairs that may be used to scope and select individual resources.
map<string, string> labels = 8;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding ContainerConfig used to
// instantiate this Container.
map<string, string> annotations = 9;
// Reference to the unique identifier of the image, on the node, as
// returned in the image service apis.
//
// Note: The image_ref above has been historically used by container
// runtimes to reference images by digest. The image_ref has been also used
// in the kubelet image garbage collection, which does not work with
// digests at all. To separate and avoid possible misusage, we now
// introduce the image_id field, which should always refer to a unique
// image identifier on the node.
string image_id = 10;
}
message ListContainersResponse {
// List of containers.
repeated Container containers = 1;
}
message ContainerStatusRequest {
// ID of the container for which to retrieve status.
string container_id = 1;
// Verbose indicates whether to return extra information about the container.
bool verbose = 2;
}
// ContainerStatus represents the status of a container.
message ContainerStatus {
// ID of the container.
string id = 1;
// Metadata of the container.
ContainerMetadata metadata = 2;
// Status of the container.
ContainerState state = 3;
// Creation time of the container in nanoseconds.
int64 created_at = 4;
// Start time of the container in nanoseconds. Default: 0 (not specified).
int64 started_at = 5;
// Finish time of the container in nanoseconds. Default: 0 (not specified).
int64 finished_at = 6;
// Exit code of the container. Only required when finished_at != 0. Default: 0.
int32 exit_code = 7;
// Spec of the image.
ImageSpec image = 8;
// Digested reference to the image in use.
string image_ref = 9;
// Brief CamelCase string explaining why container is in its current state.
// Must be set to "OOMKilled" for containers terminated by cgroup-based Out-of-Memory killer.
string reason = 10;
// Human-readable message indicating details about why container is in its
// current state.
string message = 11;
// Key-value pairs that may be used to scope and select individual resources.
map<string,string> labels = 12;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding ContainerConfig used to
// instantiate the Container this status represents.
map<string,string> annotations = 13;
// Mounts for the container.
repeated Mount mounts = 14;
// Log path of container.
string log_path = 15;
// Resource limits configuration of the container.
ContainerResources resources = 16;
// Reference to the unique identifier of the image, on the node, as
// returned in the image service apis.
//
// Note: The image_ref above has been historically used by container
// runtimes to reference images by digest. To separate and avoid possible
// misusage, we now introduce the image_id field, which should always refer
// to a unique image identifier on the node.
string image_id = 17;
// User identities initially attached to the container
ContainerUser user = 18;
}
message ContainerStatusResponse {
// Status of the container.
ContainerStatus status = 1;
// Info is extra information of the Container. The key could be arbitrary string, and
// value should be in json format. The information could include anything useful for
// debug, e.g. pid for linux container based container runtime.
// It should only be returned non-empty when Verbose is true.
map<string, string> info = 2;
}
// ContainerResources holds resource limits configuration for a container.
message ContainerResources {
// Resource limits configuration specific to Linux container.
LinuxContainerResources linux = 1;
// Resource limits configuration specific to Windows container.
WindowsContainerResources windows = 2;
}
message ContainerUser {
// User identities initially attached to first process in the Linux container.
// Note that the actual running identity can be changed if the process has enough privilege to do so.
LinuxContainerUser linux = 1;
// User identities initially attached to first process in the Windows container
// This is just reserved for future use.
// WindowsContainerUser windows = 2;
}
message UpdateContainerResourcesRequest {
// ID of the container to update.
string container_id = 1;
// Resource configuration specific to Linux containers.
LinuxContainerResources linux = 2;
// Resource configuration specific to Windows containers.
WindowsContainerResources windows = 3;
// Unstructured key-value map holding arbitrary additional information for
// container resources updating. This can be used for specifying experimental
// resources to update or other options to use when updating the container.
map<string, string> annotations = 4;
}
message UpdateContainerResourcesResponse {}
message ExecSyncRequest {
// ID of the container.
string container_id = 1;
// Command to execute.
repeated string cmd = 2;
// Timeout in seconds to stop the command. Default: 0 (run forever).
int64 timeout = 3;
}
message ExecSyncResponse {
// Captured command stdout output.
// The runtime should cap the output of this response to 16MB.
// If the stdout of the command produces more than 16MB, the remaining output
// should be discarded, and the command should proceed with no error.
// See CVE-2022-1708 and CVE-2022-31030 for more information.
bytes stdout = 1;
// Captured command stderr output.
// The runtime should cap the output of this response to 16MB.
// If the stderr of the command produces more than 16MB, the remaining output
// should be discarded, and the command should proceed with no error.
// See CVE-2022-1708 and CVE-2022-31030 for more information.
bytes stderr = 2;
// Exit code the command finished with. Default: 0 (success).
int32 exit_code = 3;
}
message ExecRequest {
// ID of the container in which to execute the command.
string container_id = 1;
// Command to execute.
repeated string cmd = 2;
// Whether to exec the command in a TTY.
bool tty = 3;
// Whether to stream stdin.
// One of `stdin`, `stdout`, and `stderr` MUST be true.
bool stdin = 4;
// Whether to stream stdout.
// One of `stdin`, `stdout`, and `stderr` MUST be true.
bool stdout = 5;
// Whether to stream stderr.
// One of `stdin`, `stdout`, and `stderr` MUST be true.
// If `tty` is true, `stderr` MUST be false. Multiplexing is not supported
// in this case. The output of stdout and stderr will be combined to a
// single stream.
bool stderr = 6;
}
message ExecResponse {
// Fully qualified URL of the exec streaming server.
string url = 1;
}
message AttachRequest {
// ID of the container to which to attach.
string container_id = 1;
// Whether to stream stdin.
// One of `stdin`, `stdout`, and `stderr` MUST be true.
bool stdin = 2;
// Whether the process being attached is running in a TTY.
// This must match the TTY setting in the ContainerConfig.
bool tty = 3;
// Whether to stream stdout.
// One of `stdin`, `stdout`, and `stderr` MUST be true.
bool stdout = 4;
// Whether to stream stderr.
// One of `stdin`, `stdout`, and `stderr` MUST be true.
// If `tty` is true, `stderr` MUST be false. Multiplexing is not supported
// in this case. The output of stdout and stderr will be combined to a
// single stream.
bool stderr = 5;
}
message AttachResponse {
// Fully qualified URL of the attach streaming server.
string url = 1;
}
message PortForwardRequest {
// ID of the container to which to forward the port.
string pod_sandbox_id = 1;
// Port to forward.
repeated int32 port = 2;
}
message PortForwardResponse {
// Fully qualified URL of the port-forward streaming server.
string url = 1;
}
message ImageFilter {
// Spec of the image.
ImageSpec image = 1;
}
message ListImagesRequest {
// Filter to list images.
ImageFilter filter = 1;
}
// Basic information about a container image.
message Image {
// ID of the image.
string id = 1;
// Other names by which this image is known.
repeated string repo_tags = 2;
// Digests by which this image is known.
repeated string repo_digests = 3;
// Size of the image in bytes. Must be > 0.
uint64 size = 4;
// UID that will run the command(s). This is used as a default if no user is
// specified when creating the container. UID and the following user name
// are mutually exclusive.
Int64Value uid = 5;
// User name that will run the command(s). This is used if UID is not set
// and no user is specified when creating container.
string username = 6;
// ImageSpec for image which includes annotations
ImageSpec spec = 7;
// Recommendation on whether this image should be exempt from garbage collection.
// It must only be treated as a recommendation -- the client can still request that the image be deleted,
// and the runtime must oblige.
bool pinned = 8;
}
message ListImagesResponse {
// List of images.
repeated Image images = 1;
}
message ImageStatusRequest {
// Spec of the image.
ImageSpec image = 1;
// Verbose indicates whether to return extra information about the image.
bool verbose = 2;
}
message ImageStatusResponse {
// Status of the image.
Image image = 1;
// Info is extra information of the Image. The key could be arbitrary string, and
// value should be in json format. The information could include anything useful
// for debug, e.g. image config for oci image based container runtime.
// It should only be returned non-empty when Verbose is true.
map<string, string> info = 2;
}
// AuthConfig contains authorization information for connecting to a registry.
message AuthConfig {
string username = 1;
string password = 2;
string auth = 3;
string server_address = 4;
// IdentityToken is used to authenticate the user and get
// an access token for the registry.
string identity_token = 5;
// RegistryToken is a bearer token to be sent to a registry
string registry_token = 6;
}
message PullImageRequest {
// Spec of the image.
ImageSpec image = 1;
// Authentication configuration for pulling the image.
AuthConfig auth = 2;
// Config of the PodSandbox, which is used to pull image in PodSandbox context.
PodSandboxConfig sandbox_config = 3;
}
message PullImageResponse {
// Reference to the image in use. For most runtimes, this should be an
// image ID or digest.
string image_ref = 1;
}
message RemoveImageRequest {
// Spec of the image to remove.
ImageSpec image = 1;
}
message RemoveImageResponse {}
message NetworkConfig {
// CIDR to use for pod IP addresses. If the CIDR is empty, runtimes
// should omit it.
string pod_cidr = 1;
}
message RuntimeConfig {
NetworkConfig network_config = 1;
}
message UpdateRuntimeConfigRequest {
RuntimeConfig runtime_config = 1;
}
message UpdateRuntimeConfigResponse {}
// RuntimeCondition contains condition information for the runtime.
// There are 2 kinds of runtime conditions:
// 1. Required conditions: Conditions are required for kubelet to work
// properly. If any required condition is unmet, the node will be not ready.
// The required conditions include:
// * RuntimeReady: RuntimeReady means the runtime is up and ready to accept
// basic containers e.g. container only needs host network.
// * NetworkReady: NetworkReady means the runtime network is up and ready to
// accept containers which require container network.
// 2. Optional conditions: Conditions are informative to the user, but kubelet
// will not rely on. Since condition type is an arbitrary string, all conditions
// not required are optional. These conditions will be exposed to users to help
// them understand the status of the system.
message RuntimeCondition {
// Type of runtime condition.
string type = 1;
// Status of the condition, one of true/false. Default: false.
bool status = 2;
// Brief CamelCase string containing reason for the condition's last transition.
string reason = 3;
// Human-readable message indicating details about last transition.
string message = 4;
}
// RuntimeStatus is information about the current status of the runtime.
message RuntimeStatus {
// List of current observed runtime conditions.
repeated RuntimeCondition conditions = 1;
}
message StatusRequest {
// Verbose indicates whether to return extra information about the runtime.
bool verbose = 1;
}
// RuntimeHandlerFeatures is a set of features implemented by the runtime handler.
message RuntimeHandlerFeatures {
// recursive_read_only_mounts is set to true if the runtime handler supports
// recursive read-only mounts.
// For runc-compatible runtimes, availability of this feature can be detected by checking whether
// the Linux kernel version is >= 5.12, and, `runc features | jq .mountOptions` contains "rro".
bool recursive_read_only_mounts = 1;
// user_namespaces is set to true if the runtime handler supports user namespaces as implemented
// in Kubernetes. This means support for both, user namespaces and idmap mounts.
bool user_namespaces = 2;
}
message RuntimeHandler {
// Name must be unique in StatusResponse.
// An empty string denotes the default handler.
string name = 1;
// Supported features.
RuntimeHandlerFeatures features = 2;
}
// RuntimeFeatures describes the set of features implemented by the CRI implementation.
// The features contained in the RuntimeFeatures should depend only on the cri implementation
// independent of runtime handlers.
message RuntimeFeatures {
// supplemental_groups_policy is set to true if the runtime supports SupplementalGroupsPolicy and ContainerUser.
bool supplemental_groups_policy = 1;
}
message StatusResponse {
// Status of the Runtime.
RuntimeStatus status = 1;
// Info is extra information of the Runtime. The key could be arbitrary string, and
// value should be in json format. The information could include anything useful for
// debug, e.g. plugins used by the container runtime.
// It should only be returned non-empty when Verbose is true.
map<string, string> info = 2;
// Runtime handlers.
repeated RuntimeHandler runtime_handlers = 3;
// features describes the set of features implemented by the CRI implementation.
// This field is supposed to propagate to NodeFeatures in Kubernetes API.
RuntimeFeatures features = 4;
}
message ImageFsInfoRequest {}
// UInt64Value is the wrapper of uint64.
message UInt64Value {
// The value.
uint64 value = 1;
}
// FilesystemIdentifier uniquely identify the filesystem.
message FilesystemIdentifier{
// Mountpoint of a filesystem.
string mountpoint = 1;
}
// FilesystemUsage provides the filesystem usage information.
message FilesystemUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// The unique identifier of the filesystem.
FilesystemIdentifier fs_id = 2;
// UsedBytes represents the bytes used for images on the filesystem.
// This may differ from the total bytes used on the filesystem and may not
// equal CapacityBytes - AvailableBytes.
UInt64Value used_bytes = 3;
// InodesUsed represents the inodes used by the images.
// This may not equal InodesCapacity - InodesAvailable because the underlying
// filesystem may also be used for purposes other than storing images.
UInt64Value inodes_used = 4;
}
// WindowsFilesystemUsage provides the filesystem usage information specific to Windows.
message WindowsFilesystemUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// The unique identifier of the filesystem.
FilesystemIdentifier fs_id = 2;
// UsedBytes represents the bytes used for images on the filesystem.
// This may differ from the total bytes used on the filesystem and may not
// equal CapacityBytes - AvailableBytes.
UInt64Value used_bytes = 3;
}
message ImageFsInfoResponse {
// Information of image filesystem(s).
repeated FilesystemUsage image_filesystems = 1;
// Information of container filesystem(s).
// This is an optional field, may be used for example if container and image
// storage are separated.
// Default will be to return this as empty.
repeated FilesystemUsage container_filesystems = 2;
}
message ContainerStatsRequest{
// ID of the container for which to retrieve stats.
string container_id = 1;
}
message ContainerStatsResponse {
// Stats of the container.
ContainerStats stats = 1;
}
message ListContainerStatsRequest{
// Filter for the list request.
ContainerStatsFilter filter = 1;
}
// ContainerStatsFilter is used to filter containers.
// All those fields are combined with 'AND'
message ContainerStatsFilter {
// ID of the container.
string id = 1;
// ID of the PodSandbox.
string pod_sandbox_id = 2;
// LabelSelector to select matches.
// Only api.MatchLabels is supported for now and the requirements
// are ANDed. MatchExpressions is not supported yet.
map<string, string> label_selector = 3;
}
message ListContainerStatsResponse {
// Stats of the container.
repeated ContainerStats stats = 1;
}
// ContainerAttributes provides basic information of the container.
message ContainerAttributes {
// ID of the container.
string id = 1;
// Metadata of the container.
ContainerMetadata metadata = 2;
// Key-value pairs that may be used to scope and select individual resources.
map<string,string> labels = 3;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding ContainerConfig used to
// instantiate the Container this status represents.
map<string,string> annotations = 4;
}
// ContainerStats provides the resource usage statistics for a container.
message ContainerStats {
// Information of the container.
ContainerAttributes attributes = 1;
// CPU usage gathered from the container.
CpuUsage cpu = 2;
// Memory usage gathered from the container.
MemoryUsage memory = 3;
// Usage of the writable layer.
FilesystemUsage writable_layer = 4;
// Swap usage gathered from the container.
SwapUsage swap = 5;
}
// WindowsContainerStats provides the resource usage statistics for a container specific for Windows
message WindowsContainerStats {
// Information of the container.
ContainerAttributes attributes = 1;
// CPU usage gathered from the container.
WindowsCpuUsage cpu = 2;
// Memory usage gathered from the container.
WindowsMemoryUsage memory = 3;
// Usage of the writable layer.
WindowsFilesystemUsage writable_layer = 4;
}
// CpuUsage provides the CPU usage information.
message CpuUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Cumulative CPU usage (sum across all cores) since object creation.
UInt64Value usage_core_nano_seconds = 2;
// Total CPU usage (sum of all cores) averaged over the sample window.
// The "core" unit can be interpreted as CPU core-nanoseconds per second.
UInt64Value usage_nano_cores = 3;
}
// WindowsCpuUsage provides the CPU usage information specific to Windows
message WindowsCpuUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Cumulative CPU usage (sum across all cores) since object creation.
UInt64Value usage_core_nano_seconds = 2;
// Total CPU usage (sum of all cores) averaged over the sample window.
// The "core" unit can be interpreted as CPU core-nanoseconds per second.
UInt64Value usage_nano_cores = 3;
}
// MemoryUsage provides the memory usage information.
message MemoryUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// The amount of working set memory in bytes.
UInt64Value working_set_bytes = 2;
// Available memory for use. This is defined as the memory limit - workingSetBytes.
UInt64Value available_bytes = 3;
// Total memory in use. This includes all memory regardless of when it was accessed.
UInt64Value usage_bytes = 4;
// The amount of anonymous and swap cache memory (includes transparent hugepages).
UInt64Value rss_bytes = 5;
// Cumulative number of minor page faults.
UInt64Value page_faults = 6;
// Cumulative number of major page faults.
UInt64Value major_page_faults = 7;
}
message SwapUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Available swap for use. This is defined as the swap limit - swapUsageBytes.
UInt64Value swap_available_bytes = 2;
// Total memory in use. This includes all memory regardless of when it was accessed.
UInt64Value swap_usage_bytes = 3;
}
// WindowsMemoryUsage provides the memory usage information specific to Windows
message WindowsMemoryUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// The amount of working set memory in bytes.
UInt64Value working_set_bytes = 2;
// Available memory for use. This is defined as the memory limit - commit_memory_bytes.
UInt64Value available_bytes = 3;
// Cumulative number of page faults.
UInt64Value page_faults = 4;
// Total commit memory in use. Commit memory is total of physical and virtual memory in use.
UInt64Value commit_memory_bytes = 5;
}
message ReopenContainerLogRequest {
// ID of the container for which to reopen the log.
string container_id = 1;
}
message ReopenContainerLogResponse{
}
message CheckpointContainerRequest {
// ID of the container to be checkpointed.
string container_id = 1;
// Location of the checkpoint archive used for export
string location = 2;
// Timeout in seconds for the checkpoint to complete.
// Timeout of zero means to use the CRI default.
// Timeout > 0 means to use the user specified timeout.
int64 timeout = 3;
}
message CheckpointContainerResponse {}
message GetEventsRequest {}
message ContainerEventResponse {
// ID of the container
string container_id = 1;
// Type of the container event
ContainerEventType container_event_type = 2;
// Creation timestamp in nanoseconds of this event
int64 created_at = 3;
// Sandbox status
PodSandboxStatus pod_sandbox_status = 4;
// Container statuses
repeated ContainerStatus containers_statuses = 5;
}
enum ContainerEventType {
// Container created
CONTAINER_CREATED_EVENT = 0;
// Container started
CONTAINER_STARTED_EVENT = 1;
// Container stopped
CONTAINER_STOPPED_EVENT = 2;
// Container deleted
CONTAINER_DELETED_EVENT = 3;
}
message ListMetricDescriptorsRequest {}
message ListMetricDescriptorsResponse {
repeated MetricDescriptor descriptors = 1;
}
message MetricDescriptor {
// The name field will be used as a unique identifier of this MetricDescriptor,
// and be used in conjunction with the Metric structure to populate the full Metric.
string name = 1;
string help = 2;
// When a metric uses this metric descriptor, it should only define
// labels that have previously been declared in label_keys.
// It is the responsibility of the runtime to correctly keep sorted the keys and values.
// If the two slices have different length, the behavior is undefined.
repeated string label_keys = 3;
}
message ListPodSandboxMetricsRequest {}
message ListPodSandboxMetricsResponse {
repeated PodSandboxMetrics pod_metrics = 1;
}
message PodSandboxMetrics {
string pod_sandbox_id = 1;
repeated Metric metrics = 2;
repeated ContainerMetrics container_metrics = 3;
}
message ContainerMetrics {
string container_id = 1;
repeated Metric metrics = 2;
}
message Metric {
// Name must match a name previously returned in a MetricDescriptors call,
// otherwise, it will be ignored.
string name = 1;
// Timestamp should be 0 if the metric was gathered live.
// If it was cached, the Timestamp should reflect the time in nanoseconds it was collected.
int64 timestamp = 2;
MetricType metric_type = 3;
// The corresponding LabelValues to the LabelKeys defined in the MetricDescriptor.
// It is the responsibility of the runtime to correctly keep sorted the keys and values.
// If the two slices have different length, the behavior is undefined.
repeated string label_values = 4;
UInt64Value value = 5;
}
enum MetricType {
COUNTER = 0;
GAUGE = 1;
}
message RuntimeConfigRequest {}
message RuntimeConfigResponse {
// Configuration information for Linux-based runtimes. This field contains
// global runtime configuration options that are not specific to runtime
// handlers.
LinuxRuntimeConfiguration linux = 1;
}
message LinuxRuntimeConfiguration {
// Cgroup driver to use
// Note: this field should not change for the lifecycle of the Kubelet,
// or while there are running containers.
// The Kubelet will not re-request this after startup, and will construct the cgroup
// hierarchy assuming it is static.
// If the runtime wishes to change this value, it must be accompanied by removal of
// all pods, and a restart of the Kubelet. The easiest way to do this is with a full node reboot.
CgroupDriver cgroup_driver = 1;
}
enum CgroupDriver {
SYSTEMD = 0;
CGROUPFS = 1;
}
Codebase Browser
kubernetes