// To regenerate api.pb.go run hack/update-generated-runtime.sh syntax = 'proto2'; package runtime; // 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 should ensure // the sandbox is in ready state. rpc RunPodSandbox(RunPodSandboxRequest) returns (RunPodSandboxResponse) {} // StopPodSandbox stops the running sandbox. If there are any running // containers in the sandbox, they should be forcibly terminated. rpc StopPodSandbox(StopPodSandboxRequest) returns (StopPodSandboxResponse) {} // RemovePodSandbox removes the sandbox. If there are any running containers in the // sandbox, they should be forcibly removed. // It should return success if the sandbox has already been removed. rpc RemovePodSandbox(RemovePodSandboxRequest) returns (RemovePodSandboxResponse) {} // PodSandboxStatus returns the status of the PodSandbox. rpc PodSandboxStatus(PodSandboxStatusRequest) returns (PodSandboxStatusResponse) {} // ListPodSandbox returns a list of Sandbox. 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). rpc StopContainer(StopContainerRequest) returns (StopContainerResponse) {} // RemoveContainer removes the container. If the container is running, the // container should be forcibly removed. // It should return success 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. rpc ContainerStatus(ContainerStatusRequest) returns (ContainerStatusResponse) {} // 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) {} // UpdateRuntimeConfig updates the runtime configuration based on request rpc UpdateRuntimeConfig(UpdateRuntimeConfigRequest) returns (UpdateRuntimeConfigResponse) {} } // Image service 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 nil. rpc ImageStatus(ImageStatusRequest) returns (ImageStatusResponse) {} // PullImage pulls an image with authentication config. rpc PullImage(PullImageRequest) returns (PullImageResponse) {} // RemoveImage removes the image. // It should return success if the image has already been removed. rpc RemoveImage(RemoveImageRequest) returns (RemoveImageResponse) {} } message VersionRequest { // The version of kubelet runtime API. optional string version = 1; } message VersionResponse { // The version of the kubelet runtime API. optional string version = 1; // The name of the container runtime. optional string runtime_name = 2; // The version of the container runtime. The string should be // semver-compatible. optional string runtime_version = 3; // The API version of the container runtime. The string should be // semver-compatible. optional 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; } // PortMapping specifies the port mapping configurations of a sandbox. message PortMapping { // The protocol of the port mapping. optional Protocol protocol = 1; // The port number within the container. optional int32 container_port = 2; // The port number on the host. optional int32 host_port = 3; // The host IP. optional string host_ip = 4; } // Mount specifies a host volume to mount into a container. message Mount { // The path of the mount within the container. optional string container_path = 1; // The path of the mount on the host. optional string host_path = 2; // If set, the mount is read-only. optional bool readonly = 3; // If set, the mount needs SELinux relabeling optional bool selinux_relabel = 4; } // NamespaceOption provides options for Linux namespaces. message NamespaceOption { // If set, use the host's network namespace. optional bool host_network = 1; // If set, use the host's PID namespace. optional bool host_pid = 2; // If set, use the host's IPC namespace. optional bool host_ipc = 3; } // LinuxPodSandboxConfig holds platform-specific configurations for Linux // host platforms and Linux-based containers. message LinuxPodSandboxConfig { // The parent cgroup of the pod sandbox. // The cgroupfs style syntax will be used, but the container runtime can // convert it to systemd semantics if needed. optional string cgroup_parent = 1; // The configurations for the sandbox's namespaces. // This will be used only if the PodSandbox uses namespace for isolation. optional NamespaceOption namespace_options = 2; } // 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 { // The pod name of the sandbox. Same as the pod name in the PodSpec. optional string name = 1; // The pod UID of the sandbox. Same as the pod UID in the PodSpec. optional string uid = 2; // The pod namespace of the sandbox. Same as the pod namespace in the PodSpec. optional string namespace = 3; // The attempt number of creating the sandbox. optional uint32 attempt = 4; } // PodSandboxConfig holds all the required and optional fields for creating a // sandbox. message PodSandboxConfig { // The 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. optional PodSandboxMetadata metadata = 1; // The hostname of the sandbox. optional 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//` // 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. optional string log_directory = 3; // The DNS config for the sandbox. optional DNSConfig dns_config = 4; // The port mappings for the sandbox. repeated PortMapping port_mappings = 5; // Labels are key value pairs that may be used to scope and select individual resources. map labels = 6; // Annotations is an unstructured key value map that may be set by external // tools to store and retrieve arbitrary metadata. There are a few features are // driven by annotations, Runtimes could support them optionally: // // 1. AppArmor // // key: container.apparmor.security.beta.kubernetes.io/ // description: apparmor profile for the container. // value: // * runtime/default: equivalent to not specifying a profile. // * localhost/: profile loaded on the node // (localhost) by name. The possible profile names are detailed at // http://wiki.apparmor.net/index.php/AppArmor_Core_Policy_Reference // // 2. Seccomp // // key: security.alpha.kubernetes.io/seccomp/pod // description: the seccomp profile for the containers of an entire pod. // value: see below. // // key: security.alpha.kubernetes.io/seccomp/container/ // description: the seccomp profile for the container (overides pod). // values: see below // // The value of seccomp is runtime agnostic: // * runtime/default: the default profile for the container runtime // * unconfined: unconfined profile, ie, no seccomp sandboxing // * localhost/: the profile installed to the node's // local seccomp profile root // map annotations = 7; // Optional configurations specific to Linux hosts. optional LinuxPodSandboxConfig linux = 8; } message RunPodSandboxRequest { // The configuration for creating a PodSandbox. optional PodSandboxConfig config = 1; } message RunPodSandboxResponse { // The id of the PodSandbox optional string pod_sandbox_id = 1; } message StopPodSandboxRequest { // The id of the PodSandbox optional string pod_sandbox_id = 1; } message StopPodSandboxResponse {} message RemovePodSandboxRequest { // The id of the PodSandbox optional string pod_sandbox_id = 1; } message RemovePodSandboxResponse {} message PodSandboxStatusRequest { // The id of the PodSandbox optional string pod_sandbox_id = 1; } // PodSandboxNetworkStatus is the status of the network for a PodSandbox. message PodSandboxNetworkStatus { // The IP address of the PodSandbox optional string ip = 1; } // Namespace contains paths to the namespaces. message Namespace { // Network is the path to the network namespace. optional string network = 1; // Options is the namespace options for linux namespaces optional NamespaceOption options = 2; } // LinuxSandboxStatus contains status specific to Linux sandboxes. message LinuxPodSandboxStatus { // Namespaces contains paths to the sandbox's namespaces. optional Namespace namespaces = 1; } enum PodSandboxState { SANDBOX_READY = 0; SANDBOX_NOTREADY = 1; } // PodSandboxStatus contains the status of the PodSandbox. message PodSandboxStatus { // ID of the sandbox. optional string id = 1; // Metadata of the sandbox. optional PodSandboxMetadata metadata = 2; // State of the sandbox. optional PodSandboxState state = 3; // Creation timestamp of the sandbox in nanoseconds. optional int64 created_at = 4; // Network contains network status if network is handled by the runtime. optional PodSandboxNetworkStatus network = 5; // Linux specific status to a pod sandbox. optional LinuxPodSandboxStatus linux = 6; // Labels are key value pairs that may be used to scope and select individual resources. map labels = 7; // Annotations is an unstructured key value map that may be set by external // tools to store and retrieve arbitrary metadata. map annotations = 8; } message PodSandboxStatusResponse { // The status of the PodSandbox optional PodSandboxStatus status = 1; } // PodSandboxFilter is used to filter a list of PodSandboxes. // All those fields are combined with 'AND' message PodSandboxFilter { // ID of the sandbox. optional string id = 1; // State of the sandbox. optional PodSandboxState state = 2; // LabelSelector to select matches. // Only api.MatchLabels is supported for now and the requirements // are ANDed. MatchExpressions is not supported yet. map label_selector = 3; } message ListPodSandboxRequest { // PodSandboxFilter to filter a list of PodSandboxes. optional PodSandboxFilter filter = 1; } // PodSandbox contains minimal information about a sandbox. message PodSandbox { // The id of the PodSandbox optional string id = 1; // Metadata of the sandbox optional PodSandboxMetadata metadata = 2; // The state of the PodSandbox optional PodSandboxState state = 3; // Creation timestamps of the sandbox in nanoseconds optional int64 created_at = 4; // The labels of the PodSandbox map labels = 5; // Annotations is an unstructured key value map that may be set by external // tools to store and retrieve arbitrary metadata. map annotations = 6; } message ListPodSandboxResponse { // List of PodSandbox repeated PodSandbox items = 1; } // ImageSpec is an internal representation of an image. Currently, it wraps the // value of a Container's Image field (e.g. imageName, imageName:tag, or // imageName:digest), but in the future it will include more detailed // information about the different image types. message ImageSpec { optional string image = 1; } message KeyValue { optional string key = 1; optional 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 optional int64 cpu_period = 1; // CPU CFS (Completely Fair Scheduler) quota optional int64 cpu_quota = 2; // CPU shares (relative weight vs. other containers) optional int64 cpu_shares = 3; // Memory limit in bytes optional int64 memory_limit_in_bytes = 4; // OOMScoreAdj adjusts the oom-killer score. optional int64 oom_score_adj = 5; } // SELinuxOption are the labels to be applied to the container. message SELinuxOption { optional string user = 1; optional string role = 2; optional string type = 3; optional 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; } // LinuxContainerConfig contains platform-specific configuration for // Linux-based containers. message LinuxContainerConfig { // Resources specification for the container. optional LinuxContainerResources resources = 1; // Capabilities to add or drop. optional Capability capabilities = 2; // Optional SELinux context to be applied. optional SELinuxOption selinux_options = 3; // User contains the user for the container process. optional LinuxUser user = 4; } message LinuxUser { // uid specifies the user ID the container process has. optional int64 uid = 1; // gid specifies the group ID the container process has. optional int64 gid = 2; // additional_gids specifies additional GIDs the container process has. repeated int64 additional_gids = 3; } // 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 { // The name of the container. Same as the container name in the PodSpec. optional string name = 1; // The attempt number of creating the container. optional uint32 attempt = 2; } // ContainerConfig holds all the required and optional fields for creating a // container. message ContainerConfig { // The 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. optional ContainerMetadata metadata = 1 ; // Image to use. optional 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. optional string working_dir = 5; // List of environment variable to set in the container repeated KeyValue envs = 6; // Mounts specifies mounts for the container repeated Mount mounts = 7; // Labels are 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 labels = 8; // Annotations is an unstructured key value map that may be set by external // tools to store and retrieve arbitrary metadata. map annotations = 9; // If set, run container in privileged mode. // Processes in privileged containers are essentially equivalent to root on the host. optional bool privileged = 10; // If set, the root filesystem of the container is read-only. optional bool readonly_rootfs = 11; // Path relative to PodSandboxConfig.LogDirectory for container to store // the log (STDOUT and STDERR) on the host. // E.g., // PodSandboxConfig.LogDirectory = `/var/log/pods//` // 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. optional string log_path = 12; // The hash of container config // 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. optional bool stdin = 13; optional bool stdin_once = 14; optional bool tty = 15; // Linux contains configuration specific to Linux containers. optional LinuxContainerConfig linux = 16; } message CreateContainerRequest { // The id of the PodSandbox optional string pod_sandbox_id = 1; // The config of the container optional ContainerConfig config = 2; // The 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. optional PodSandboxConfig sandbox_config = 3; } message CreateContainerResponse { // The id of the created container optional string container_id = 1; } message StartContainerRequest { // The id of the container optional string container_id = 1; } message StartContainerResponse {} message StopContainerRequest { // The id of the container optional string container_id = 1; // Timeout in seconds to stop the container optional int64 timeout = 2; } message StopContainerResponse {} message RemoveContainerRequest { // The id of the container optional string container_id = 1; } message RemoveContainerResponse {} enum ContainerState { CONTAINER_CREATED = 0; CONTAINER_RUNNING = 1; CONTAINER_EXITED = 2; CONTAINER_UNKNOWN = 3; } // ContainerFilter is used to filter containers. // All those fields are combined with 'AND' message ContainerFilter { // ID of the container. optional string id = 1; // State of the container. optional ContainerState state = 2; // The id of the pod sandbox optional 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 label_selector = 4; } message ListContainersRequest { optional ContainerFilter filter = 1; } // Container provides the runtime information for a container, such as ID, hash, // state of the container. message Container { // The ID of the container, used by the container runtime to identify // a container. optional string id = 1; // The id of the sandbox which this container belongs to. optional string pod_sandbox_id = 2; // The metadata of the container. optional ContainerMetadata metadata = 3; // The spec of the image optional ImageSpec image = 4; // Reference to the image in use. For most runtimes, this should be an // image ID. optional string image_ref = 5; // State is the state of the container. optional ContainerState state = 6; // Creation time of the container in nanoseconds. optional int64 created_at = 7; // Labels are key value pairs that may be used to scope and select individual resources. map labels = 8; // Annotations is an unstructured key value map that may be set by external // tools to store and retrieve arbitrary metadata. map annotations = 9; } message ListContainersResponse { // List of containers repeated Container containers = 1; } message ContainerStatusRequest { // The id of the container optional string container_id = 1; } // ContainerStatus represents the status of a container. message ContainerStatus { // ID of the container. optional string id = 1; // Metadata of the container. optional ContainerMetadata metadata = 2; // Status of the container. optional ContainerState state = 3; // Creation time of the container in nanoseconds. optional int64 created_at = 4; // Start time of the container in nanoseconds. optional int64 started_at = 5; // Finish time of the container in nanoseconds. optional int64 finished_at = 6; // Exit code of the container. optional int32 exit_code = 7; // The spec of the image optional ImageSpec image = 8; // Reference to the image in use. For most runtimes, this should be an // image ID optional string image_ref = 9; // A brief CamelCase string explains why container is in such a status. optional string reason = 10; // A human-readable message indication details about why container is in // this state. optional string message = 11; // Labels are key value pairs that may be used to scope and select individual resources. map labels = 12; // Annotations is an unstructured key value map. map annotations = 13; // Mounts specifies mounts for the container repeated Mount mounts = 14; } message ContainerStatusResponse { // The status of the container optional ContainerStatus status = 1; } message ExecSyncRequest { // The id of the container optional string container_id = 1; // The cmd to execute repeated string cmd = 2; // Timeout in seconds to stop the command. Default: run forever. optional int64 timeout = 3; } message ExecSyncResponse { // The captured command stdout output. optional bytes stdout = 1; // The captured command stderr output. optional bytes stderr = 2; // The exit code the command finished with. optional int32 exit_code = 3; } message ExecRequest { // The id of the container optional string container_id = 1; // The cmd to execute repeated string cmd = 2; // Whether use tty optional bool tty = 3; // Whether to stream stdin optional bool stdin = 4; } message ExecResponse { // The fully qualified URL of the exec streaming server optional string url = 1; } message AttachRequest { // The id of the container optional string container_id = 1; // Whether to stream stdin optional bool stdin = 2; } message AttachResponse { // The fully qualified URL of the attach streaming server optional string url = 1; } message PortForwardRequest { // The id of the container optional string pod_sandbox_id = 1; // The port to forward repeated int32 port = 2; } message PortForwardResponse { // The fully qualified URL of the port-forward streaming server optional string url = 1; } message ImageFilter { // The spec of the image optional ImageSpec image = 1; } message ListImagesRequest { // The filter to list images optional ImageFilter filter = 1; } // Basic information about a container image. message Image { // ID of the image. optional 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; // The size of the image in bytes. optional uint64 size = 4; } message ListImagesResponse { // List of images repeated Image images = 1; } message ImageStatusRequest { // The spec of the image optional ImageSpec image = 1; } message ImageStatusResponse { // The status of the image optional Image image = 1; } // AuthConfig contains authorization information for connecting to a registry. message AuthConfig { optional string username = 1; optional string password = 2; optional string auth = 3; optional string server_address = 4; // IdentityToken is used to authenticate the user and get // an access token for the registry. optional string identity_token = 5; // RegistryToken is a bearer token to be sent to a registry optional string registry_token = 6; } message PullImageRequest { // The spec of the image optional ImageSpec image = 1; // The auth config for pulling image optional AuthConfig auth = 2; // The config of the PodSandbox, which is used to pull image in PodSandbox context optional PodSandboxConfig sandbox_config = 3; } message PullImageResponse {} message RemoveImageRequest { // The spec of the image optional ImageSpec image = 1; } message RemoveImageResponse {} message NetworkConfig { // The CIDR to use for pod IP addresses optional string pod_cidr = 1; } message RuntimeConfig { optional NetworkConfig network_config = 1; } message UpdateRuntimeConfigRequest { optional RuntimeConfig runtime_config = 1; } message UpdateRuntimeConfigResponse {}