cri.proto

// 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";

// 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. If the hostPath doesn't exist, then runtimes
    // should report 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 OCI 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 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;
}

// 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;
}

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;
}

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;
}

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 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 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;
}