-
Notifications
You must be signed in to change notification settings - Fork 445
/
api.proto
1969 lines (1766 loc) · 79 KB
/
api.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
Copyright 2020 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-codegen.sh protobindings`
syntax = "proto3";
package runtime.v1;
option go_package = "k8s.io/cri-api/pkg/apis/runtime/v1";
import "github.com/gogo/protobuf/gogoproto/gogo.proto";
option (gogoproto.goproto_stringer_all) = false;
option (gogoproto.stringer_all) = true;
option (gogoproto.goproto_getters_all) = true;
option (gogoproto.marshaler_all) = true;
option (gogoproto.sizer_all) = true;
option (gogoproto.unmarshaler_all) = true;
option (gogoproto.goproto_unrecognized_all) = false;
// Runtime service defines the public APIs for remote container runtimes
service RuntimeService {
// Version returns the runtime name, runtime version, and runtime API version.
rpc Version(VersionRequest) returns (VersionResponse) {}
// RunPodSandbox creates and starts a pod-level sandbox. Runtimes must ensure
// the sandbox is in the ready state on success.
rpc RunPodSandbox(RunPodSandboxRequest) returns (RunPodSandboxResponse) {}
// StopPodSandbox stops any running process that is part of the sandbox and
// reclaims network resources (e.g., IP addresses) allocated to the sandbox.
// If there are any running containers in the sandbox, they must be forcibly
// terminated.
// This call is idempotent, and must not return an error if all relevant
// resources have already been reclaimed. kubelet will call StopPodSandbox
// at least once before calling RemovePodSandbox. It will also attempt to
// reclaim resources eagerly, as soon as a sandbox is not needed. Hence,
// multiple StopPodSandbox calls are expected.
rpc StopPodSandbox(StopPodSandboxRequest) returns (StopPodSandboxResponse) {}
// RemovePodSandbox removes the sandbox. If there are any running containers
// in the sandbox, they must be forcibly terminated and removed.
// This call is idempotent, and must not return an error if the sandbox has
// already been removed.
rpc RemovePodSandbox(RemovePodSandboxRequest) returns (RemovePodSandboxResponse) {}
// PodSandboxStatus returns the status of the PodSandbox. If the PodSandbox is not
// present, returns an error.
rpc PodSandboxStatus(PodSandboxStatusRequest) returns (PodSandboxStatusResponse) {}
// ListPodSandbox returns a list of PodSandboxes.
rpc ListPodSandbox(ListPodSandboxRequest) returns (ListPodSandboxResponse) {}
// CreateContainer creates a new container in specified PodSandbox
rpc CreateContainer(CreateContainerRequest) returns (CreateContainerResponse) {}
// StartContainer starts the container.
rpc StartContainer(StartContainerRequest) returns (StartContainerResponse) {}
// StopContainer stops a running container with a grace period (i.e., timeout).
// This call is idempotent, and must not return an error if the container has
// already been stopped.
// The runtime must forcibly kill the container after the grace period is
// reached.
rpc StopContainer(StopContainerRequest) returns (StopContainerResponse) {}
// RemoveContainer removes the container. If the container is running, the
// container must be forcibly removed.
// This call is idempotent, and must not return an error if the container has
// already been removed.
rpc RemoveContainer(RemoveContainerRequest) returns (RemoveContainerResponse) {}
// ListContainers lists all containers by filters.
rpc ListContainers(ListContainersRequest) returns (ListContainersResponse) {}
// ContainerStatus returns status of the container. If the container is not
// present, returns an error.
rpc ContainerStatus(ContainerStatusRequest) returns (ContainerStatusResponse) {}
// UpdateContainerResources updates ContainerConfig of the container synchronously.
// If runtime fails to transactionally update the requested resources, an error is returned.
rpc UpdateContainerResources(UpdateContainerResourcesRequest) returns (UpdateContainerResourcesResponse) {}
// ReopenContainerLog asks runtime to reopen the stdout/stderr log file
// for the container. This is often called after the log file has been
// rotated. If the container is not running, container runtime can choose
// to either create a new log file and return nil, or return an error.
// Once it returns error, new container log file MUST NOT be created.
rpc ReopenContainerLog(ReopenContainerLogRequest) returns (ReopenContainerLogResponse) {}
// ExecSync runs a command in a container synchronously.
rpc ExecSync(ExecSyncRequest) returns (ExecSyncResponse) {}
// Exec prepares a streaming endpoint to execute a command in the container.
rpc Exec(ExecRequest) returns (ExecResponse) {}
// Attach prepares a streaming endpoint to attach to a running container.
rpc Attach(AttachRequest) returns (AttachResponse) {}
// PortForward prepares a streaming endpoint to forward ports from a PodSandbox.
rpc PortForward(PortForwardRequest) returns (PortForwardResponse) {}
// ContainerStats returns stats of the container. If the container does not
// exist, the call returns an error.
rpc ContainerStats(ContainerStatsRequest) returns (ContainerStatsResponse) {}
// ListContainerStats returns stats of all running containers.
rpc ListContainerStats(ListContainerStatsRequest) returns (ListContainerStatsResponse) {}
// PodSandboxStats returns stats of the pod sandbox. If the pod sandbox does not
// exist, the call returns an error.
rpc PodSandboxStats(PodSandboxStatsRequest) returns (PodSandboxStatsResponse) {}
// ListPodSandboxStats returns stats of the pod sandboxes matching a filter.
rpc ListPodSandboxStats(ListPodSandboxStatsRequest) returns (ListPodSandboxStatsResponse) {}
// UpdateRuntimeConfig updates the runtime configuration based on the given request.
rpc UpdateRuntimeConfig(UpdateRuntimeConfigRequest) returns (UpdateRuntimeConfigResponse) {}
// Status returns the status of the runtime.
rpc Status(StatusRequest) returns (StatusResponse) {}
// CheckpointContainer checkpoints a container
rpc CheckpointContainer(CheckpointContainerRequest) returns (CheckpointContainerResponse) {}
// GetContainerEvents gets container events from the CRI runtime
rpc GetContainerEvents(GetEventsRequest) returns (stream ContainerEventResponse) {}
// ListMetricDescriptors gets the descriptors for the metrics that will be returned in ListPodSandboxMetrics.
// This list should be static at startup: either the client and server restart together when
// adding or removing metrics descriptors, or they should not change.
// Put differently, if ListPodSandboxMetrics references a name that is not described in the initial
// ListMetricDescriptors call, then the metric will not be broadcasted.
rpc ListMetricDescriptors(ListMetricDescriptorsRequest) returns (ListMetricDescriptorsResponse) {}
// ListPodSandboxMetrics gets pod sandbox metrics from CRI Runtime
rpc ListPodSandboxMetrics(ListPodSandboxMetricsRequest) returns (ListPodSandboxMetricsResponse) {}
// RuntimeConfig returns configuration information of the runtime.
// A couple of notes:
// - The RuntimeConfigRequest object is not to be confused with the contents of UpdateRuntimeConfigRequest.
// The former is for having runtime tell Kubelet what to do, the latter vice versa.
// - It is the expectation of the Kubelet that these fields are static for the lifecycle of the Kubelet.
// The Kubelet will not re-request the RuntimeConfiguration after startup, and CRI implementations should
// avoid updating them without a full node reboot.
rpc RuntimeConfig(RuntimeConfigRequest) returns (RuntimeConfigResponse) {}
}
// ImageService defines the public APIs for managing images.
service ImageService {
// ListImages lists existing images.
rpc ListImages(ListImagesRequest) returns (ListImagesResponse) {}
// ImageStatus returns the status of the image. If the image is not
// present, returns a response with ImageStatusResponse.Image set to
// nil.
rpc ImageStatus(ImageStatusRequest) returns (ImageStatusResponse) {}
// PullImage pulls an image with authentication config.
rpc PullImage(PullImageRequest) returns (PullImageResponse) {}
// RemoveImage removes the image.
// This call is idempotent, and must not return an error if the image has
// already been removed.
rpc RemoveImage(RemoveImageRequest) returns (RemoveImageResponse) {}
// ImageFSInfo returns information of the filesystem that is used to store images.
rpc ImageFsInfo(ImageFsInfoRequest) returns (ImageFsInfoResponse) {}
}
message VersionRequest {
// Version of the kubelet runtime API.
string version = 1;
}
message VersionResponse {
// Version of the kubelet runtime API.
string version = 1;
// Name of the container runtime.
string runtime_name = 2;
// Version of the container runtime. The string must be
// semver-compatible.
string runtime_version = 3;
// API version of the container runtime. The string must be
// semver-compatible.
string runtime_api_version = 4;
}
// DNSConfig specifies the DNS servers and search domains of a sandbox.
message DNSConfig {
// List of DNS servers of the cluster.
repeated string servers = 1;
// List of DNS search domains of the cluster.
repeated string searches = 2;
// List of DNS options. See https://linux.die.net/man/5/resolv.conf
// for all available options.
repeated string options = 3;
}
enum Protocol {
TCP = 0;
UDP = 1;
SCTP = 2;
}
// PortMapping specifies the port mapping configurations of a sandbox.
message PortMapping {
// Protocol of the port mapping.
Protocol protocol = 1;
// Port number within the container. Default: 0 (not specified).
int32 container_port = 2;
// Port number on the host. Default: 0 (not specified).
int32 host_port = 3;
// Host IP.
string host_ip = 4;
}
enum MountPropagation {
// No mount propagation ("rprivate" in Linux terminology).
PROPAGATION_PRIVATE = 0;
// Mounts get propagated from the host to the container ("rslave" in Linux).
PROPAGATION_HOST_TO_CONTAINER = 1;
// Mounts get propagated from the host to the container and from the
// container to the host ("rshared" in Linux).
PROPAGATION_BIDIRECTIONAL = 2;
}
// Mount specifies a host volume to mount into a container.
message Mount {
// Path of the mount within the container.
string container_path = 1;
// Path of the mount on the host. If the hostPath doesn't exist, then runtimes
// should report error. If the hostpath is a symbolic link, runtimes should
// follow the symlink and mount the real destination to container.
string host_path = 2;
// If set, the mount is read-only.
bool readonly = 3;
// If set, the mount needs SELinux relabeling.
bool selinux_relabel = 4;
// Requested propagation mode.
MountPropagation propagation = 5;
// UidMappings specifies the runtime UID mappings for the mount.
repeated IDMapping uidMappings = 6;
// GidMappings specifies the runtime GID mappings for the mount.
repeated IDMapping gidMappings = 7;
// If set to true, the mount is made recursive read-only.
// In this CRI API, recursive_read_only is a plain true/false boolean, although its equivalent
// in the Kubernetes core API is a quaternary that can be nil, "Enabled", "IfPossible", or "Disabled".
// kubelet translates that quaternary value in the core API into a boolean in this CRI API.
// Remarks:
// - nil is just treated as false
// - when set to true, readonly must be explicitly set to true, and propagation must be PRIVATE (0).
// - (readonly == false && recursive_read_only == false) does not make the mount read-only.
bool recursive_read_only = 8;
// Mount an image reference (image ID, with or without digest), which is a
// special use case for image volume mounts. If this field is set, then
// host_path should be unset. All OCI mounts are per feature definition
// readonly. The kubelet does an PullImage RPC and evaluates the returned
// PullImageResponse.image_ref value, which is then set to the
// ImageSpec.image field. Runtimes are expected to mount the image as
// required.
// Introduced in the OCI Volume Source KEP: https://kep.k8s.io/4639
ImageSpec image = 9;
}
// IDMapping describes host to container ID mappings for a pod sandbox.
message IDMapping {
// HostId is the id on the host.
uint32 host_id = 1;
// ContainerId is the id in the container.
uint32 container_id = 2;
// Length is the size of the range to map.
uint32 length = 3;
}
// A NamespaceMode describes the intended namespace configuration for each
// of the namespaces (Network, PID, IPC) in NamespaceOption. Runtimes should
// map these modes as appropriate for the technology underlying the runtime.
enum NamespaceMode {
// A POD namespace is common to all containers in a pod.
// For example, a container with a PID namespace of POD expects to view
// all of the processes in all of the containers in the pod.
POD = 0;
// A CONTAINER namespace is restricted to a single container.
// For example, a container with a PID namespace of CONTAINER expects to
// view only the processes in that container.
CONTAINER = 1;
// A NODE namespace is the namespace of the Kubernetes node.
// For example, a container with a PID namespace of NODE expects to view
// all of the processes on the host running the kubelet.
NODE = 2;
// TARGET targets the namespace of another container. When this is specified,
// a target_id must be specified in NamespaceOption and refer to a container
// previously created with NamespaceMode CONTAINER. This containers namespace
// will be made to match that of container target_id.
// For example, a container with a PID namespace of TARGET expects to view
// all of the processes that container target_id can view.
TARGET = 3;
}
// UserNamespace describes the intended user namespace configuration for a pod sandbox.
message UserNamespace {
// Mode is the NamespaceMode for this UserNamespace.
// Note: NamespaceMode for UserNamespace currently supports only POD and NODE, not CONTAINER OR TARGET.
NamespaceMode mode = 1;
// Uids specifies the UID mappings for the user namespace.
repeated IDMapping uids = 2;
// Gids specifies the GID mappings for the user namespace.
repeated IDMapping gids = 3;
}
// NamespaceOption provides options for Linux namespaces.
message NamespaceOption {
// Network namespace for this container/sandbox.
// Note: There is currently no way to set CONTAINER scoped network in the Kubernetes API.
// Namespaces currently set by the kubelet: POD, NODE
NamespaceMode network = 1;
// PID namespace for this container/sandbox.
// Note: The CRI default is POD, but the v1.PodSpec default is CONTAINER.
// The kubelet's runtime manager will set this to CONTAINER explicitly for v1 pods.
// Namespaces currently set by the kubelet: POD, CONTAINER, NODE, TARGET
NamespaceMode pid = 2;
// IPC namespace for this container/sandbox.
// Note: There is currently no way to set CONTAINER scoped IPC in the Kubernetes API.
// Namespaces currently set by the kubelet: POD, NODE
NamespaceMode ipc = 3;
// Target Container ID for NamespaceMode of TARGET. This container must have been
// previously created in the same pod. It is not possible to specify different targets
// for each namespace.
string target_id = 4;
// UsernsOptions for this pod sandbox.
// The Kubelet picks the user namespace configuration to use for the pod sandbox. The mappings
// are specified as part of the UserNamespace struct. If the struct is nil, then the POD mode
// must be assumed. This is done for backward compatibility with older Kubelet versions that
// do not set a user namespace.
UserNamespace userns_options = 5;
}
// SupplementalGroupsPolicy defines how supplemental groups
// of the first container processes are calculated.
enum SupplementalGroupsPolicy {
// Merge means that the container's provided SupplementalGroups
// and FsGroup (specified in SecurityContext) will be merged with
// the primary user's groups as defined in the container image
// (in /etc/group).
Merge = 0;
// Strict means that the container's provided SupplementalGroups
// and FsGroup (specified in SecurityContext) will be used instead of
// any groups defined in the container image.
Strict = 1;
}
// Int64Value is the wrapper of int64.
message Int64Value {
// The value.
int64 value = 1;
}
// LinuxSandboxSecurityContext holds linux security configuration that will be
// applied to a sandbox. Note that:
// 1) It does not apply to containers in the pods.
// 2) It may not be applicable to a PodSandbox which does not contain any running
// process.
message LinuxSandboxSecurityContext {
// Configurations for the sandbox's namespaces.
// This will be used only if the PodSandbox uses namespace for isolation.
NamespaceOption namespace_options = 1;
// Optional SELinux context to be applied.
SELinuxOption selinux_options = 2;
// UID to run sandbox processes as, when applicable.
Int64Value run_as_user = 3;
// GID to run sandbox processes as, when applicable. run_as_group should only
// be specified when run_as_user is specified; otherwise, the runtime MUST error.
Int64Value run_as_group = 8;
// If set, the root filesystem of the sandbox is read-only.
bool readonly_rootfs = 4;
// List of groups applied to the first process run in each container.
// supplemental_groups_policy can control how groups will be calculated.
repeated int64 supplemental_groups = 5;
// supplemental_groups_policy defines how supplemental groups of the first
// container processes are calculated.
// Valid values are "Merge" and "Strict".
// If not specified, "Merge" is used.
SupplementalGroupsPolicy supplemental_groups_policy = 11;
// Indicates whether the sandbox will be asked to run a privileged
// container. If a privileged container is to be executed within it, this
// MUST be true.
// This allows a sandbox to take additional security precautions if no
// privileged containers are expected to be run.
bool privileged = 6;
// Seccomp profile for the sandbox.
SecurityProfile seccomp = 9;
// AppArmor profile for the sandbox.
SecurityProfile apparmor = 10;
// Seccomp profile for the sandbox, candidate values are:
// * runtime/default: the default profile for the container runtime
// * unconfined: unconfined profile, ie, no seccomp sandboxing
// * localhost/<full-path-to-profile>: the profile installed on the node.
// <full-path-to-profile> is the full path of the profile.
// Default: "", which is identical with unconfined.
string seccomp_profile_path = 7 [deprecated=true];
}
// A security profile which can be used for sandboxes and containers.
message SecurityProfile {
// Available profile types.
enum ProfileType {
// The container runtime default profile should be used.
RuntimeDefault = 0;
// Disable the feature for the sandbox or the container.
Unconfined = 1;
// A pre-defined profile on the node should be used.
Localhost = 2;
}
// Indicator which `ProfileType` should be applied.
ProfileType profile_type = 1;
// Indicates that a pre-defined profile on the node should be used.
// Must only be set if `ProfileType` is `Localhost`.
// For seccomp, it must be an absolute path to the seccomp profile.
// For AppArmor, this field is the AppArmor `<profile name>/`
string localhost_ref = 2;
}
// LinuxPodSandboxConfig holds platform-specific configurations for Linux
// host platforms and Linux-based containers.
message LinuxPodSandboxConfig {
// Parent cgroup of the PodSandbox.
// The cgroupfs style syntax will be used, but the container runtime can
// convert it to systemd semantics if needed.
string cgroup_parent = 1;
// LinuxSandboxSecurityContext holds sandbox security attributes.
LinuxSandboxSecurityContext security_context = 2;
// Sysctls holds linux sysctls config for the sandbox.
map<string, string> sysctls = 3;
// Optional overhead represents the overheads associated with this sandbox
LinuxContainerResources overhead = 4;
// Optional resources represents the sum of container resources for this sandbox
LinuxContainerResources resources = 5;
}
// PodSandboxMetadata holds all necessary information for building the sandbox name.
// The container runtime is encouraged to expose the metadata associated with the
// PodSandbox in its user interface for better user experience. For example,
// the runtime can construct a unique PodSandboxName based on the metadata.
message PodSandboxMetadata {
// Pod name of the sandbox. Same as the pod name in the Pod ObjectMeta.
string name = 1;
// Pod UID of the sandbox. Same as the pod UID in the Pod ObjectMeta.
string uid = 2;
// Pod namespace of the sandbox. Same as the pod namespace in the Pod ObjectMeta.
string namespace = 3;
// Attempt number of creating the sandbox. Default: 0.
uint32 attempt = 4;
}
// PodSandboxConfig holds all the required and optional fields for creating a
// sandbox.
message PodSandboxConfig {
// Metadata of the sandbox. This information will uniquely identify the
// sandbox, and the runtime should leverage this to ensure correct
// operation. The runtime may also use this information to improve UX, such
// as by constructing a readable name.
PodSandboxMetadata metadata = 1;
// Hostname of the sandbox. Hostname could only be empty when the pod
// network namespace is NODE.
string hostname = 2;
// Path to the directory on the host in which container log files are
// stored.
// By default the log of a container going into the LogDirectory will be
// hooked up to STDOUT and STDERR. However, the LogDirectory may contain
// binary log files with structured logging data from the individual
// containers. For example, the files might be newline separated JSON
// structured logs, systemd-journald journal files, gRPC trace files, etc.
// E.g.,
// PodSandboxConfig.LogDirectory = `/var/log/pods/<NAMESPACE>_<NAME>_<UID>/`
// ContainerConfig.LogPath = `containerName/Instance#.log`
string log_directory = 3;
// DNS config for the sandbox.
DNSConfig dns_config = 4;
// Port mappings for the sandbox.
repeated PortMapping port_mappings = 5;
// Key-value pairs that may be used to scope and select individual resources.
map<string, string> labels = 6;
// Unstructured key-value map that may be set by the kubelet to store and
// retrieve arbitrary metadata. This will include any annotations set on a
// pod through the Kubernetes API.
//
// Annotations MUST NOT be altered by the runtime; the annotations stored
// here MUST be returned in the PodSandboxStatus associated with the pod
// this PodSandboxConfig creates.
//
// In general, in order to preserve a well-defined interface between the
// kubelet and the container runtime, annotations SHOULD NOT influence
// runtime behaviour.
//
// Annotations can also be useful for runtime authors to experiment with
// new features that are opaque to the Kubernetes APIs (both user-facing
// and the CRI). Whenever possible, however, runtime authors SHOULD
// consider proposing new typed fields for any new features instead.
map<string, string> annotations = 7;
// Optional configurations specific to Linux hosts.
LinuxPodSandboxConfig linux = 8;
// Optional configurations specific to Windows hosts.
WindowsPodSandboxConfig windows = 9;
}
message RunPodSandboxRequest {
// Configuration for creating a PodSandbox.
PodSandboxConfig config = 1;
// Named runtime configuration to use for this PodSandbox.
// If the runtime handler is unknown, this request should be rejected. An
// empty string should select the default handler, equivalent to the
// behavior before this feature was added.
// See https://git.k8s.io/enhancements/keps/sig-node/585-runtime-class
string runtime_handler = 2;
}
message RunPodSandboxResponse {
// ID of the PodSandbox to run.
string pod_sandbox_id = 1;
}
message StopPodSandboxRequest {
// ID of the PodSandbox to stop.
string pod_sandbox_id = 1;
}
message StopPodSandboxResponse {}
message RemovePodSandboxRequest {
// ID of the PodSandbox to remove.
string pod_sandbox_id = 1;
}
message RemovePodSandboxResponse {}
message PodSandboxStatusRequest {
// ID of the PodSandbox for which to retrieve status.
string pod_sandbox_id = 1;
// Verbose indicates whether to return extra information about the pod sandbox.
bool verbose = 2;
}
// PodIP represents an ip of a Pod
message PodIP{
// an ip is a string representation of an IPv4 or an IPv6
string ip = 1;
}
// PodSandboxNetworkStatus is the status of the network for a PodSandbox.
// Currently ignored for pods sharing the host networking namespace.
message PodSandboxNetworkStatus {
// IP address of the PodSandbox.
string ip = 1;
// list of additional ips (not inclusive of PodSandboxNetworkStatus.Ip) of the PodSandBoxNetworkStatus
repeated PodIP additional_ips = 2;
}
// Namespace contains paths to the namespaces.
message Namespace {
// Namespace options for Linux namespaces.
NamespaceOption options = 2;
}
// LinuxSandboxStatus contains status specific to Linux sandboxes.
message LinuxPodSandboxStatus {
// Paths to the sandbox's namespaces.
Namespace namespaces = 1;
}
enum PodSandboxState {
SANDBOX_READY = 0;
SANDBOX_NOTREADY = 1;
}
// PodSandboxStatus contains the status of the PodSandbox.
message PodSandboxStatus {
// ID of the sandbox.
string id = 1;
// Metadata of the sandbox.
PodSandboxMetadata metadata = 2;
// State of the sandbox.
PodSandboxState state = 3;
// Creation timestamp of the sandbox in nanoseconds. Must be > 0.
int64 created_at = 4;
// Network contains network status if network is handled by the runtime.
PodSandboxNetworkStatus network = 5;
// Linux-specific status to a pod sandbox.
LinuxPodSandboxStatus linux = 6;
// Labels are key-value pairs that may be used to scope and select individual resources.
map<string, string> labels = 7;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding PodSandboxConfig used to
// instantiate the pod sandbox this status represents.
map<string, string> annotations = 8;
// runtime configuration used for this PodSandbox.
string runtime_handler = 9;
}
message PodSandboxStatusResponse {
// Status of the PodSandbox.
PodSandboxStatus status = 1;
// Info is extra information of the PodSandbox. The key could be arbitrary string, and
// value should be in json format. The information could include anything useful for
// debug, e.g. network namespace for linux container based container runtime.
// It should only be returned non-empty when Verbose is true.
map<string, string> info = 2;
// Container statuses
repeated ContainerStatus containers_statuses = 3;
// Timestamp at which container and pod statuses were recorded
int64 timestamp = 4;
}
// PodSandboxStateValue is the wrapper of PodSandboxState.
message PodSandboxStateValue {
// State of the sandbox.
PodSandboxState state = 1;
}
// PodSandboxFilter is used to filter a list of PodSandboxes.
// All those fields are combined with 'AND'
message PodSandboxFilter {
// ID of the sandbox.
string id = 1;
// State of the sandbox.
PodSandboxStateValue state = 2;
// LabelSelector to select matches.
// Only api.MatchLabels is supported for now and the requirements
// are ANDed. MatchExpressions is not supported yet.
map<string, string> label_selector = 3;
}
message ListPodSandboxRequest {
// PodSandboxFilter to filter a list of PodSandboxes.
PodSandboxFilter filter = 1;
}
// PodSandbox contains minimal information about a sandbox.
message PodSandbox {
// ID of the PodSandbox.
string id = 1;
// Metadata of the PodSandbox.
PodSandboxMetadata metadata = 2;
// State of the PodSandbox.
PodSandboxState state = 3;
// Creation timestamps of the PodSandbox in nanoseconds. Must be > 0.
int64 created_at = 4;
// Labels of the PodSandbox.
map<string, string> labels = 5;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding PodSandboxConfig used to
// instantiate this PodSandbox.
map<string, string> annotations = 6;
// runtime configuration used for this PodSandbox.
string runtime_handler = 7;
}
message ListPodSandboxResponse {
// List of PodSandboxes.
repeated PodSandbox items = 1;
}
message PodSandboxStatsRequest {
// ID of the pod sandbox for which to retrieve stats.
string pod_sandbox_id = 1;
}
message PodSandboxStatsResponse {
PodSandboxStats stats = 1;
}
// PodSandboxStatsFilter is used to filter the list of pod sandboxes to retrieve stats for.
// All those fields are combined with 'AND'.
message PodSandboxStatsFilter {
// ID of the pod sandbox.
string id = 1;
// LabelSelector to select matches.
// Only api.MatchLabels is supported for now and the requirements
// are ANDed. MatchExpressions is not supported yet.
map<string, string> label_selector = 2;
}
message ListPodSandboxStatsRequest {
// Filter for the list request.
PodSandboxStatsFilter filter = 1;
}
message ListPodSandboxStatsResponse {
// Stats of the pod sandbox.
repeated PodSandboxStats stats = 1;
}
// PodSandboxAttributes provides basic information of the pod sandbox.
message PodSandboxAttributes {
// ID of the pod sandbox.
string id = 1;
// Metadata of the pod sandbox.
PodSandboxMetadata metadata = 2;
// Key-value pairs that may be used to scope and select individual resources.
map<string,string> labels = 3;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding PodSandboxStatus used to
// instantiate the PodSandbox this status represents.
map<string,string> annotations = 4;
}
// PodSandboxStats provides the resource usage statistics for a pod.
// The linux or windows field will be populated depending on the platform.
message PodSandboxStats {
// Information of the pod.
PodSandboxAttributes attributes = 1;
// Stats from linux.
LinuxPodSandboxStats linux = 2;
// Stats from windows.
WindowsPodSandboxStats windows = 3;
}
// LinuxPodSandboxStats provides the resource usage statistics for a pod sandbox on linux.
message LinuxPodSandboxStats {
// CPU usage gathered for the pod sandbox.
CpuUsage cpu = 1;
// Memory usage gathered for the pod sandbox.
MemoryUsage memory = 2;
// Network usage gathered for the pod sandbox
NetworkUsage network = 3;
// Stats pertaining to processes in the pod sandbox.
ProcessUsage process = 4;
// Stats of containers in the measured pod sandbox.
repeated ContainerStats containers = 5;
}
// WindowsPodSandboxStats provides the resource usage statistics for a pod sandbox on windows
message WindowsPodSandboxStats {
// CPU usage gathered for the pod sandbox.
WindowsCpuUsage cpu = 1;
// Memory usage gathered for the pod sandbox.
WindowsMemoryUsage memory = 2;
// Network usage gathered for the pod sandbox
WindowsNetworkUsage network = 3;
// Stats pertaining to processes in the pod sandbox.
WindowsProcessUsage process = 4;
// Stats of containers in the measured pod sandbox.
repeated WindowsContainerStats containers = 5;
}
// NetworkUsage contains data about network resources.
message NetworkUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Stats for the default network interface.
NetworkInterfaceUsage default_interface = 2;
// Stats for all found network interfaces, excluding the default.
repeated NetworkInterfaceUsage interfaces = 3;
}
// WindowsNetworkUsage contains data about network resources specific to Windows.
message WindowsNetworkUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Stats for the default network interface.
WindowsNetworkInterfaceUsage default_interface = 2;
// Stats for all found network interfaces, excluding the default.
repeated WindowsNetworkInterfaceUsage interfaces = 3;
}
// NetworkInterfaceUsage contains resource value data about a network interface.
message NetworkInterfaceUsage {
// The name of the network interface.
string name = 1;
// Cumulative count of bytes received.
UInt64Value rx_bytes = 2;
// Cumulative count of receive errors encountered.
UInt64Value rx_errors = 3;
// Cumulative count of bytes transmitted.
UInt64Value tx_bytes = 4;
// Cumulative count of transmit errors encountered.
UInt64Value tx_errors = 5;
}
// WindowsNetworkInterfaceUsage contains resource value data about a network interface specific for Windows.
message WindowsNetworkInterfaceUsage {
// The name of the network interface.
string name = 1;
// Cumulative count of bytes received.
UInt64Value rx_bytes = 2;
// Cumulative count of receive errors encountered.
UInt64Value rx_packets_dropped = 3;
// Cumulative count of bytes transmitted.
UInt64Value tx_bytes = 4;
// Cumulative count of transmit errors encountered.
UInt64Value tx_packets_dropped = 5;
}
// ProcessUsage are stats pertaining to processes.
message ProcessUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Number of processes.
UInt64Value process_count = 2;
}
// WindowsProcessUsage are stats pertaining to processes specific to Windows.
message WindowsProcessUsage {
// Timestamp in nanoseconds at which the information were collected. Must be > 0.
int64 timestamp = 1;
// Number of processes.
UInt64Value process_count = 2;
}
// ImageSpec is an internal representation of an image.
message ImageSpec {
// Container's Image field (e.g. imageID or imageDigest).
string image = 1;
// Unstructured key-value map holding arbitrary metadata.
// ImageSpec Annotations can be used to help the runtime target specific
// images in multi-arch images.
map<string, string> annotations = 2;
// The container image reference specified by the user (e.g. image[:tag] or digest).
// Only set if available within the RPC context.
string user_specified_image = 18;
// Runtime handler to use for pulling the image.
// If the runtime handler is unknown, the request should be rejected.
// An empty string would select the default runtime handler.
string runtime_handler = 19;
}
message KeyValue {
string key = 1;
string value = 2;
}
// LinuxContainerResources specifies Linux specific configuration for
// resources.
message LinuxContainerResources {
// CPU CFS (Completely Fair Scheduler) period. Default: 0 (not specified).
int64 cpu_period = 1;
// CPU CFS (Completely Fair Scheduler) quota. Default: 0 (not specified).
int64 cpu_quota = 2;
// CPU shares (relative weight vs. other containers). Default: 0 (not specified).
int64 cpu_shares = 3;
// Memory limit in bytes. Default: 0 (not specified).
int64 memory_limit_in_bytes = 4;
// OOMScoreAdj adjusts the oom-killer score. Default: 0 (not specified).
int64 oom_score_adj = 5;
// CpusetCpus constrains the allowed set of logical CPUs. Default: "" (not specified).
string cpuset_cpus = 6;
// CpusetMems constrains the allowed set of memory nodes. Default: "" (not specified).
string cpuset_mems = 7;
// List of HugepageLimits to limit the HugeTLB usage of container per page size. Default: nil (not specified).
repeated HugepageLimit hugepage_limits = 8;
// Unified resources for cgroup v2. Default: nil (not specified).
// Each key/value in the map refers to the cgroup v2.
// e.g. "memory.max": "6937202688" or "io.weight": "default 100".
map<string, string> unified = 9;
// Memory swap limit in bytes. Default 0 (not specified).
int64 memory_swap_limit_in_bytes = 10;
}
// HugepageLimit corresponds to the file`hugetlb.<hugepagesize>.limit_in_byte` in container level cgroup.
// For example, `PageSize=1GB`, `Limit=1073741824` means setting `1073741824` bytes to hugetlb.1GB.limit_in_bytes.
message HugepageLimit {
// The value of PageSize has the format <size><unit-prefix>B (2MB, 1GB),
// and must match the <hugepagesize> of the corresponding control file found in `hugetlb.<hugepagesize>.limit_in_bytes`.
// The values of <unit-prefix> are intended to be parsed using base 1024("1KB" = 1024, "1MB" = 1048576, etc).
string page_size = 1;
// limit in bytes of hugepagesize HugeTLB usage.
uint64 limit = 2;
}
// SELinuxOption are the labels to be applied to the container.
message SELinuxOption {
string user = 1;
string role = 2;
string type = 3;
string level = 4;
}
// Capability contains the container capabilities to add or drop
// Dropping a capability will drop it from all sets.
// If a capability is added to only the add_capabilities list then it gets added to permitted,
// inheritable, effective and bounding sets, i.e. all sets except the ambient set.
// If a capability is added to only the add_ambient_capabilities list then it gets added to all sets, i.e permitted
// inheritable, effective, bounding and ambient sets.
// If a capability is added to add_capabilities and add_ambient_capabilities lists then it gets added to all sets, i.e.
// permitted, inheritable, effective, bounding and ambient sets.
message Capability {
// List of capabilities to add.
repeated string add_capabilities = 1;
// List of capabilities to drop.
repeated string drop_capabilities = 2;
// List of ambient capabilities to add.
repeated string add_ambient_capabilities = 3;
}
// LinuxContainerSecurityContext holds linux security configuration that will be applied to a container.
message LinuxContainerSecurityContext {
// Capabilities to add or drop.
Capability capabilities = 1;
// If set, run container in privileged mode.
// Privileged mode is incompatible with the following options. If
// privileged is set, the following features MAY have no effect:
// 1. capabilities
// 2. selinux_options
// 4. seccomp
// 5. apparmor
//
// Privileged mode implies the following specific options are applied:
// 1. All capabilities are added.
// 2. Sensitive paths, such as kernel module paths within sysfs, are not masked.
// 3. Any sysfs and procfs mounts are mounted RW.
// 4. AppArmor confinement is not applied.
// 5. Seccomp restrictions are not applied.
// 6. The device cgroup does not restrict access to any devices.
// 7. All devices from the host's /dev are available within the container.
// 8. SELinux restrictions are not applied (e.g. label=disabled).
bool privileged = 2;
// Configurations for the container's namespaces.
// Only used if the container uses namespace for isolation.
NamespaceOption namespace_options = 3;
// SELinux context to be optionally applied.
SELinuxOption selinux_options = 4;
// UID to run the container process as. Only one of run_as_user and
// run_as_username can be specified at a time.
Int64Value run_as_user = 5;
// GID to run the container process as. run_as_group should only be specified
// when run_as_user or run_as_username is specified; otherwise, the runtime
// MUST error.
Int64Value run_as_group = 12;
// User name to run the container process as. If specified, the user MUST
// exist in the container image (i.e. in the /etc/passwd inside the image),
// and be resolved there by the runtime; otherwise, the runtime MUST error.
string run_as_username = 6;
// If set, the root filesystem of the container is read-only.
bool readonly_rootfs = 7;
// List of groups applied to the first process run in each container.
// supplemental_groups_policy can control how groups will be calculated.
repeated int64 supplemental_groups = 8;
// supplemental_groups_policy defines how supplemental groups of the first
// container processes are calculated.
// Valid values are "Merge" and "Strict".
// If not specified, "Merge" is used.
SupplementalGroupsPolicy supplemental_groups_policy = 17;
// no_new_privs defines if the flag for no_new_privs should be set on the
// container.
bool no_new_privs = 11;
// masked_paths is a slice of paths that should be masked by the container
// runtime, this can be passed directly to the OCI spec.
repeated string masked_paths = 13;
// readonly_paths is a slice of paths that should be set as readonly by the
// container runtime, this can be passed directly to the OCI spec.
repeated string readonly_paths = 14;
// Seccomp profile for the container.
SecurityProfile seccomp = 15;
// AppArmor profile for the container.
SecurityProfile apparmor = 16;
// AppArmor profile for the container, candidate values are:
// * runtime/default: equivalent to not specifying a profile.
// * unconfined: no profiles are loaded
// * localhost/<profile_name>: profile loaded on the node
// (localhost) by name. The possible profile names are detailed at
// https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference
string apparmor_profile = 9 [deprecated=true];
// Seccomp profile for the container, candidate values are:
// * runtime/default: the default profile for the container runtime
// * unconfined: unconfined profile, ie, no seccomp sandboxing
// * localhost/<full-path-to-profile>: the profile installed on the node.
// <full-path-to-profile> is the full path of the profile.
// Default: "", which is identical with unconfined.
string seccomp_profile_path = 10 [deprecated=true];
}
// LinuxContainerConfig contains platform-specific configuration for
// Linux-based containers.
message LinuxContainerConfig {
// Resources specification for the container.
LinuxContainerResources resources = 1;
// LinuxContainerSecurityContext configuration for the container.
LinuxContainerSecurityContext security_context = 2;
}
message LinuxContainerUser {
// uid is the primary uid initially attached to the first process in the container
int64 uid = 1;
// gid is the primary gid initially attached to the first process in the container
int64 gid = 2;
// supplemental_groups are the supplemental groups initially attached to the first process in the container
repeated int64 supplemental_groups = 3;
}
// WindowsNamespaceOption provides options for Windows namespaces.
message WindowsNamespaceOption {
// Network namespace for this container/sandbox.
// Namespaces currently set by the kubelet: POD, NODE
NamespaceMode network = 1;
}
// WindowsSandboxSecurityContext holds platform-specific configurations that will be
// applied to a sandbox.
// These settings will only apply to the sandbox container.
message WindowsSandboxSecurityContext {
// User name to run the container process as. If specified, the user MUST
// exist in the container image and be resolved there by the runtime;
// otherwise, the runtime MUST return error.