From 4879b6d7dbee078b8fbdb62b1343bd5d270e179a Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 22 Dec 2021 23:02:48 +0000 Subject: [PATCH] synced up v1 and v1alpha2 CRI API comments and updated the readme --- staging/src/k8s.io/cri-api/README.md | 11 ++++++-- .../cri-api/pkg/apis/runtime/v1/api.pb.go | 14 +++++----- .../cri-api/pkg/apis/runtime/v1/api.proto | 12 ++++---- .../pkg/apis/runtime/v1alpha2/api.pb.go | 21 +++++--------- .../pkg/apis/runtime/v1alpha2/api.proto | 28 +++++++------------ 5 files changed, 38 insertions(+), 48 deletions(-) diff --git a/staging/src/k8s.io/cri-api/README.md b/staging/src/k8s.io/cri-api/README.md index d597eb778d8..a490b753890 100644 --- a/staging/src/k8s.io/cri-api/README.md +++ b/staging/src/k8s.io/cri-api/README.md @@ -3,6 +3,11 @@ This repository contains the definitions for the Container Runtime Interface (CRI). CRI is a plugin interface which enables kubelet to use a wide variety of container runtimes, without the need to recompile. CRI consists of a protocol buffers and gRPC API. +Read more about CRI API at [kubernetes docs](https://kubernetes.io/docs/concepts/architecture/cri/). + +The repository [kubernetes/cri-api](https://github.com/kubernetes/cri-api) is a mirror of https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/cri-api. +Please do NOT file issues or submit PRs against the [kubernetes/cri-api](https://github.com/kubernetes/cri-api) +repository as it is readonly, all development is done in [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). ## Community, discussion, contribution, and support @@ -12,7 +17,7 @@ page](http://kubernetes.io/community/). You can reach the maintainers of this repository at: - Slack: #sig-node (on https://kubernetes.slack.com -- get an - invite at slack.kubernetes.io) + invite at [slack.kubernetes.io](https://slack.kubernetes.io)) - Mailing List: https://groups.google.com/forum/#!forum/kubernetes-sig-node @@ -23,5 +28,5 @@ Code of Conduct](code-of-conduct.md). ### Contibution Guidelines -See [CONTRIBUTING.md](CONTRIBUTING.md) for more information. - +See [CONTRIBUTING.md](CONTRIBUTING.md) for more information. Please note that [kubernetes/cri-api](https://github.com/kubernetes/cri-api) +is a readonly mirror repository, all development is done at [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). diff --git a/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.pb.go b/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.pb.go index f8762ae63a0..c4dfd60f0d9 100644 --- a/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.pb.go +++ b/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.pb.go @@ -1241,7 +1241,7 @@ type RunPodSandboxRequest struct { // 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/README.md + // See https://git.k8s.io/enhancements/keps/sig-node/585-runtime-class RuntimeHandler string `protobuf:"bytes,2,opt,name=runtime_handler,json=runtimeHandler,proto3" json:"runtime_handler,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_sizecache int32 `json:"-"` @@ -2492,9 +2492,9 @@ func (m *ListPodSandboxStatsResponse) GetStats() []*PodSandboxStats { // PodSandboxAttributes provides basic information of the pod sandbox. type PodSandboxAttributes struct { - // ID of the pod. + // ID of the pod sandbox. Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"` - // Metadata of the pod. + // Metadata of the pod sandbox. Metadata *PodSandboxMetadata `protobuf:"bytes,2,opt,name=metadata,proto3" json:"metadata,omitempty"` // Key-value pairs that may be used to scope and select individual resources. Labels map[string]string `protobuf:"bytes,3,rep,name=labels,proto3" json:"labels,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` @@ -8495,10 +8495,10 @@ type RuntimeServiceClient interface { ContainerStats(ctx context.Context, in *ContainerStatsRequest, opts ...grpc.CallOption) (*ContainerStatsResponse, error) // ListContainerStats returns stats of all running containers. ListContainerStats(ctx context.Context, in *ListContainerStatsRequest, opts ...grpc.CallOption) (*ListContainerStatsResponse, error) - // PodSandboxStats returns stats of the pod. If the pod sandbox does not + // PodSandboxStats returns stats of the pod sandbox. If the pod sandbox does not // exist, the call returns an error. PodSandboxStats(ctx context.Context, in *PodSandboxStatsRequest, opts ...grpc.CallOption) (*PodSandboxStatsResponse, error) - // ListPodSandboxStats returns stats of the pods matching a filter. + // ListPodSandboxStats returns stats of the pod sandboxes matching a filter. ListPodSandboxStats(ctx context.Context, in *ListPodSandboxStatsRequest, opts ...grpc.CallOption) (*ListPodSandboxStatsResponse, error) // UpdateRuntimeConfig updates the runtime configuration based on the given request. UpdateRuntimeConfig(ctx context.Context, in *UpdateRuntimeConfigRequest, opts ...grpc.CallOption) (*UpdateRuntimeConfigResponse, error) @@ -8798,10 +8798,10 @@ type RuntimeServiceServer interface { ContainerStats(context.Context, *ContainerStatsRequest) (*ContainerStatsResponse, error) // ListContainerStats returns stats of all running containers. ListContainerStats(context.Context, *ListContainerStatsRequest) (*ListContainerStatsResponse, error) - // PodSandboxStats returns stats of the pod. If the pod sandbox does not + // PodSandboxStats returns stats of the pod sandbox. If the pod sandbox does not // exist, the call returns an error. PodSandboxStats(context.Context, *PodSandboxStatsRequest) (*PodSandboxStatsResponse, error) - // ListPodSandboxStats returns stats of the pods matching a filter. + // ListPodSandboxStats returns stats of the pod sandboxes matching a filter. ListPodSandboxStats(context.Context, *ListPodSandboxStatsRequest) (*ListPodSandboxStatsResponse, error) // UpdateRuntimeConfig updates the runtime configuration based on the given request. UpdateRuntimeConfig(context.Context, *UpdateRuntimeConfigRequest) (*UpdateRuntimeConfigResponse, error) diff --git a/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto b/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto index 8f96c97ebc6..71a18bbbe54 100644 --- a/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto +++ b/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto @@ -103,10 +103,10 @@ service RuntimeService { // ListContainerStats returns stats of all running containers. rpc ListContainerStats(ListContainerStatsRequest) returns (ListContainerStatsResponse) {} - // PodSandboxStats returns stats of the pod. If the pod sandbox does not + // PodSandboxStats returns stats of the pod sandbox. If the pod sandbox does not // exist, the call returns an error. rpc PodSandboxStats(PodSandboxStatsRequest) returns (PodSandboxStatsResponse) {} - // ListPodSandboxStats returns stats of the pods matching a filter. + // ListPodSandboxStats returns stats of the pod sandboxes matching a filter. rpc ListPodSandboxStats(ListPodSandboxStatsRequest) returns (ListPodSandboxStatsResponse) {} // UpdateRuntimeConfig updates the runtime configuration based on the given request. @@ -409,7 +409,7 @@ message RunPodSandboxRequest { // 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/README.md + // See https://git.k8s.io/enhancements/keps/sig-node/585-runtime-class string runtime_handler = 2; } @@ -587,9 +587,9 @@ message ListPodSandboxStatsResponse { // PodSandboxAttributes provides basic information of the pod sandbox. message PodSandboxAttributes { - // ID of the pod. + // ID of the pod sandbox. string id = 1; - // Metadata of the pod. + // Metadata of the pod sandbox. PodSandboxMetadata metadata = 2; // Key-value pairs that may be used to scope and select individual resources. map labels = 3; @@ -812,7 +812,7 @@ message LinuxContainerConfig { LinuxContainerSecurityContext security_context = 2; } -// WindowsSandboxSecurityContext holds platform-specific configurations that will be +// WindowsSandboxSecurityContext holds platform-specific configurations that will be // applied to a sandbox. // These settings will only apply to the sandbox container. message WindowsSandboxSecurityContext { diff --git a/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.pb.go b/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.pb.go index dd1d1d84e93..fc9e9db7daf 100644 --- a/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.pb.go +++ b/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.pb.go @@ -1107,11 +1107,6 @@ type PodSandboxConfig struct { // 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. LogDirectory string `protobuf:"bytes,3,opt,name=log_directory,json=logDirectory,proto3" json:"log_directory,omitempty"` // DNS config for the sandbox. DnsConfig *DNSConfig `protobuf:"bytes,4,opt,name=dns_config,json=dnsConfig,proto3" json:"dns_config,omitempty"` @@ -2344,7 +2339,7 @@ func (m *PodSandboxStatsResponse) GetStats() *PodSandboxStats { return nil } -// PodSandboxStatsFilter is used to filter pod sandboxes. +// PodSandboxStatsFilter is used to filter the list of pod sandboxes to retrieve stats for. // All those fields are combined with 'AND'. type PodSandboxStatsFilter struct { // ID of the pod sandbox. @@ -3076,8 +3071,6 @@ func (m *KeyValue) GetValue() string { // LinuxContainerResources specifies Linux specific configuration for // resources. -// TODO: Consider using Resources from opencontainers/runtime-spec/specs-go -// directly. type LinuxContainerResources struct { // CPU CFS (Completely Fair Scheduler) period. Default: 0 (not specified). CpuPeriod int64 `protobuf:"varint,1,opt,name=cpu_period,json=cpuPeriod,proto3" json:"cpu_period,omitempty"` @@ -3679,7 +3672,7 @@ type WindowsSandboxSecurityContext struct { RunAsUsername string `protobuf:"bytes,1,opt,name=run_as_username,json=runAsUsername,proto3" json:"run_as_username,omitempty"` // The contents of the GMSA credential spec to use to run this container. CredentialSpec string `protobuf:"bytes,2,opt,name=credential_spec,json=credentialSpec,proto3" json:"credential_spec,omitempty"` - // Indicates whether the container be asked to run as a HostProcess container. + // Indicates whether the container requested to run as a HostProcess container. HostProcess bool `protobuf:"varint,3,opt,name=host_process,json=hostProcess,proto3" json:"host_process,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_sizecache int32 `json:"-"` @@ -4166,8 +4159,6 @@ type ContainerConfig struct { LogPath string `protobuf:"bytes,11,opt,name=log_path,json=logPath,proto3" json:"log_path,omitempty"` // 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. Stdin bool `protobuf:"varint,12,opt,name=stdin,proto3" json:"stdin,omitempty"` StdinOnce bool `protobuf:"varint,13,opt,name=stdin_once,json=stdinOnce,proto3" json:"stdin_once,omitempty"` Tty bool `protobuf:"varint,14,opt,name=tty,proto3" json:"tty,omitempty"` @@ -7735,7 +7726,7 @@ type MemoryUsage struct { Timestamp int64 `protobuf:"varint,1,opt,name=timestamp,proto3" json:"timestamp,omitempty"` // The amount of working set memory in bytes. WorkingSetBytes *UInt64Value `protobuf:"bytes,2,opt,name=working_set_bytes,json=workingSetBytes,proto3" json:"working_set_bytes,omitempty"` - // Available memory for use. This is defined as the memory limit = workingSetBytes. + // Available memory for use. This is defined as the memory limit - workingSetBytes. AvailableBytes *UInt64Value `protobuf:"bytes,3,opt,name=available_bytes,json=availableBytes,proto3" json:"available_bytes,omitempty"` // Total memory in use. This includes all memory regardless of when it was accessed. UsageBytes *UInt64Value `protobuf:"bytes,4,opt,name=usage_bytes,json=usageBytes,proto3" json:"usage_bytes,omitempty"` @@ -8472,7 +8463,8 @@ type RuntimeServiceClient interface { // 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? + // The runtime must forcibly kill the container after the grace period is + // reached. StopContainer(ctx context.Context, in *StopContainerRequest, opts ...grpc.CallOption) (*StopContainerResponse, error) // RemoveContainer removes the container. If the container is running, the // container must be forcibly removed. @@ -8774,7 +8766,8 @@ type RuntimeServiceServer interface { // 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? + // The runtime must forcibly kill the container after the grace period is + // reached. StopContainer(context.Context, *StopContainerRequest) (*StopContainerResponse, error) // RemoveContainer removes the container. If the container is running, the // container must be forcibly removed. diff --git a/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.proto b/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.proto index ba3230d183b..77744a82d4d 100644 --- a/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.proto +++ b/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.proto @@ -66,7 +66,8 @@ service RuntimeService { // 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? + // The runtime must forcibly kill the container after the grace period is + // reached. rpc StopContainer(StopContainerRequest) returns (StopContainerResponse) {} // RemoveContainer removes the container. If the container is running, the // container must be forcibly removed. @@ -371,11 +372,6 @@ message PodSandboxConfig { // 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; @@ -568,7 +564,7 @@ message PodSandboxStatsResponse { PodSandboxStats stats = 1; } -// PodSandboxStatsFilter is used to filter pod sandboxes. +// PodSandboxStatsFilter is used to filter the list of pod sandboxes to retrieve stats for. // All those fields are combined with 'AND'. message PodSandboxStatsFilter { // ID of the pod sandbox. @@ -662,7 +658,7 @@ message NetworkInterfaceUsage { message ProcessUsage { // The time at which these stats were updated. int64 timestamp = 1; - // Number of processes. + // Number of processes. UInt64Value process_count = 2; } @@ -683,8 +679,6 @@ message KeyValue { // 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; @@ -818,7 +812,7 @@ message LinuxContainerConfig { LinuxContainerSecurityContext security_context = 2; } -// WindowsSandboxSecurityContext holds platform-specific configurations that will be +// WindowsSandboxSecurityContext holds platform-specific configurations that will be // applied to a sandbox. // These settings will only apply to the sandbox container. message WindowsSandboxSecurityContext { @@ -830,7 +824,7 @@ message WindowsSandboxSecurityContext { // 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. + // Indicates whether the container requested to run as a HostProcess container. bool host_process = 3; } @@ -956,8 +950,6 @@ message ContainerConfig { // 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; @@ -1135,10 +1127,10 @@ message UpdateContainerResourcesRequest { string container_id = 1; // Resource configuration specific to Linux containers. LinuxContainerResources linux = 2; - // Resource configuration specific to Windows containers. + // 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 + // 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; } @@ -1491,7 +1483,7 @@ message MemoryUsage { int64 timestamp = 1; // The amount of working set memory in bytes. UInt64Value working_set_bytes = 2; - // Available memory for use. This is defined as the memory limit = workingSetBytes. + // Available memory for use. This is defined as the memory limit - workingSetBytes. UInt64Value available_bytes = 3; // Total memory in use. This includes all memory regardless of when it was accessed. UInt64Value usage_bytes = 4;