runtime/v1alpha2/api.proto

/*
Copyright 2018 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-generated-runtime.sh
syntax = "proto3";

package runtime.v1alpha2;
option go_package = "v1alpha2";

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.
    // TODO: what must the runtime do 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.
    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) {}

    // 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) {}
}

// 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 ("private" 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;
}

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

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

// 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 the sandbox, in
    // addition to the sandbox's primary GID.
    repeated int64 supplemental_groups = 5;
    // 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;
}

// 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/<podUID>/`
    //     ContainerConfig.LogPath = `containerName/Instance#.log`
    //
    // WARNING: Log management and how kubelet should interface with the
    // container logs are under active discussion in
    // https://issues.k8s.io/24677. There *may* be future change of direction
    // for logging as the discussion carries on.
    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;
}

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/runtime-class.md
    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.
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;
}

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

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

message KeyValue {
    string key = 1;
    string value = 2;
}

// LinuxContainerResources specifies Linux specific configuration for
// resources.
// TODO: Consider using Resources from opencontainers/runtime-spec/specs-go
// directly.
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;
}

// 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
message Capability {
    // List of capabilities to add.
    repeated string add_capabilities = 1;
    // List of capabilities to drop.
    repeated string drop_capabilities = 2;
}

// 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 the container, in
    // addition to the container's primary GID.
    repeated int64 supplemental_groups = 8;
    // 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;
}

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

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

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

// 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/<podUID>/`
    //     ContainerConfig.LogPath = `containerName/Instance#.log`
    //
    // WARNING: Log management and how kubelet should interface with the
    // container logs are under active discussion in
    // https://issues.k8s.io/24677. There *may* be future change of direction
    // for logging as the discussion carries on.
    string log_path = 11;

    // Variables for interactive containers, these have very specialized
    // use-cases (e.g. debugging).
    // TODO: Determine if we need to continue supporting these fields that are
    // part of Kubernetes's Container Spec.
    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;
}

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;
    // Reference to the image in use. For most runtimes, this should be an
    // image ID.
    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;
}

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;
    // Reference to the image in use. For most runtimes, this should be an
    // image ID
    string image_ref = 9;
    // Brief CamelCase string explaining why container is in its current state.
    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;
}

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

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.
    bytes stdout = 1;
    // Captured command stderr output.
    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;
}

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

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

message ImageFsInfoResponse {
    // Information of image filesystem(s).
    repeated FilesystemUsage image_filesystems = 1;
}

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

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

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

message ReopenContainerLogRequest {
    // ID of the container for which to reopen the log.
    string container_id = 1;
}

message ReopenContainerLogResponse{
}