From ae052f080486539dfea7a53474f9cbc944dbb7e7 Mon Sep 17 00:00:00 2001 From: Serge Bazanski Date: Mon, 24 May 2021 13:54:11 +0200 Subject: [PATCH] cluster/identd/cri: import This imports the CRI protobuf/gRPC specs. These are pulled from: https://raw.githubusercontent.com/kubernetes/cri-api/master/pkg/apis/runtime/v1alpha2/api.proto Our host containerd does not implement v1, so we go with v1alpha2. Change-Id: I3e2bedca76edc85eea9b61a8634c92175f0d2a30 --- cluster/identd/cri/BUILD.bazel | 24 + cluster/identd/cri/api.proto | 1363 ++++++++++++++++++++++++++++++++ 2 files changed, 1387 insertions(+) create mode 100644 cluster/identd/cri/BUILD.bazel create mode 100644 cluster/identd/cri/api.proto diff --git a/cluster/identd/cri/BUILD.bazel b/cluster/identd/cri/BUILD.bazel new file mode 100644 index 00000000..68a15aaf --- /dev/null +++ b/cluster/identd/cri/BUILD.bazel @@ -0,0 +1,24 @@ +load("@rules_proto//proto:defs.bzl", "proto_library") +load("@io_bazel_rules_go//go:def.bzl", "go_library") +load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library") + +proto_library( + name = "cri_proto", + srcs = ["api.proto"], + visibility = ["//visibility:public"], +) + +go_proto_library( + name = "cri_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "code.hackerspace.pl/hscloud/cluster/identd/cri", + proto = ":cri_proto", + visibility = ["//visibility:public"], +) + +go_library( + name = "go_default_library", + embed = [":cri_go_proto"], + importpath = "code.hackerspace.pl/hscloud/cluster/identd/cri", + visibility = ["//visibility:public"], +) diff --git a/cluster/identd/cri/api.proto b/cluster/identd/cri/api.proto new file mode 100644 index 00000000..561f4697 --- /dev/null +++ b/cluster/identd/cri/api.proto @@ -0,0 +1,1363 @@ +/* +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 = "code.hackerspace.pl/hscloud/cluster/identd/cri"; + +// 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/: the profile installed on the node. + // 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 `/` + 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 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//` + // 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 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 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. +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 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 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 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 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 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 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 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..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 B (2MB, 1GB), + // and must match the of the corresponding control file found in `hugetlb..limit_in_bytes`. + // The values of 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 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/: the profile installed on the node. + // 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; +} + +// 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 be asked to run as a HostProcess container. + bool host_process = 3; +} + +// 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; +} + +// 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 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 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//` + // 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 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 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 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 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 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 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 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 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 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 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 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 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{ +} +