-
Notifications
You must be signed in to change notification settings - Fork 39.4k
/
api.proto
972 lines (875 loc) · 35.8 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
// To regenerate api.pb.go run hack/update-generated-runtime.sh
syntax = 'proto3';
package runtime;
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.
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.
rpc ContainerStatus(ContainerStatusRequest) returns (ContainerStatusResponse) {}
// ExecSync runs a command in a container synchronously.
rpc ExecSync(ExecSyncRequest) returns (ExecSyncResponse) {}
// Exec prepares a streaming endpoint to execute a command in the container.
rpc Exec(ExecRequest) returns (ExecResponse) {}
// Attach prepares a streaming endpoint to attach to a running container.
rpc Attach(AttachRequest) returns (AttachResponse) {}
// PortForward prepares a streaming endpoint to forward ports from a PodSandbox.
rpc PortForward(PortForwardRequest) returns (PortForwardResponse) {}
// UpdateRuntimeConfig updates the runtime configuration based on 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) {}
}
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;
}
// 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;
}
// 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.
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;
}
// NamespaceOption provides options for Linux namespaces.
message NamespaceOption {
// If set, use the host's network namespace.
bool host_network = 1;
// If set, use the host's PID namespace.
bool host_pid = 2;
// If set, use the host's IPC namespace.
bool host_ipc = 3;
}
// 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;
// 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;
}
// 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;
}
// 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 PodSpec.
string name = 1;
// Pod UID of the sandbox. Same as the pod UID in the PodSpec.
string uid = 2;
// Pod namespace of the sandbox. Same as the pod namespace in the PodSpec.
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.
string hostname = 2;
// Path to the directory on the host in which container log files are
// stored.
// By default the log of a container going into the LogDirectory will be
// hooked up to STDOUT and STDERR. However, the LogDirectory may contain
// binary log files with structured logging data from the individual
// containers. For example, the files might be newline separated JSON
// structured logs, systemd-journald journal files, gRPC trace files, etc.
// E.g.,
// PodSandboxConfig.LogDirectory = `/var/log/pods/<podUID>/`
// ContainerConfig.LogPath = `containerName_Instance#.log`
//
// WARNING: Log management and how kubelet should interface with the
// container logs are under active discussion in
// https://issues.k8s.io/24677. There *may* be future change of direction
// for logging as the discussion carries on.
string log_directory = 3;
// DNS config for the sandbox.
DNSConfig dns_config = 4;
// Port mappings for the sandbox.
repeated PortMapping port_mappings = 5;
// Key-value pairs that may be used to scope and select individual resources.
map<string, string> labels = 6;
// Unstructured key-value map that may be set by the kubelet to store and
// retrieve arbitrary metadata. This will include any annotations set on a
// pod through the Kubernetes API.
//
// Annotations MUST NOT be altered by the runtime; the annotations stored
// here MUST be returned in the PodSandboxStatus associated with the pod
// this PodSandboxConfig creates.
//
// In general, in order to preserve a well-defined interface between the
// kubelet and the container runtime, annotations SHOULD NOT influence
// runtime behaviour. For legacy reasons, there are some annotations which
// currently explicitly break this rule, listed below; in future versions
// of the interface these will be promoted to typed features.
//
// 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.
//
// 1. AppArmor
//
// key: container.apparmor.security.beta.kubernetes.io/<container_name>
// description: apparmor profile for a container in this pod.
// value:
// * runtime/default: equivalent to not specifying a profile.
// * localhost/<profile_name>: profile loaded on the node
// (localhost) by name. The possible profile names are detailed at
// http://wiki.apparmor.net/index.php/AppArmor_Core_Policy_Reference
//
// 2. Seccomp
//
// key: security.alpha.kubernetes.io/seccomp/pod
// description: the seccomp profile for the containers of an entire pod.
// value: see below.
//
// key: security.alpha.kubernetes.io/seccomp/container/<container name>
// description: the seccomp profile for the container (overrides pod).
// value: see below
//
// The value of seccomp is runtime agnostic:
// * runtime/default: the default profile for the container runtime
// * unconfined: unconfined profile, ie, no seccomp sandboxing
// * localhost/<profile-name>: the profile installed to the node's
// local seccomp profile root. Note that profile root is set in
// kubelet, and it is not passed in CRI yet, see https://issues.k8s.io/36997.
//
// 3. Sysctls
//
// key: security.alpha.kubernetes.io/sysctls
// description: list of safe sysctls which are set for the sandbox.
// value: comma separated list of sysctl_name=value key-value pairs.
//
// key: security.alpha.kubernetes.io/unsafe-sysctls
// description: list of unsafe sysctls which are set for the sandbox.
// value: comma separated list of sysctl_name=value key-value pairs.
//
map<string, string> annotations = 7;
// Optional configurations specific to Linux hosts.
LinuxPodSandboxConfig linux = 8;
}
message RunPodSandboxRequest {
// Configuration for creating a PodSandbox.
PodSandboxConfig config = 1;
}
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;
}
// PodSandboxNetworkStatus is the status of the network for a PodSandbox.
message PodSandboxNetworkStatus {
// IP address of the PodSandbox.
string ip = 1;
}
// Namespace contains paths to the namespaces.
message Namespace {
// Path to the network namespace.
string network = 1;
// 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;
}
message PodSandboxStatusResponse {
// Status of the PodSandbox.
PodSandboxStatus status = 1;
}
// 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;
}
message ListPodSandboxResponse {
// List of PodSandboxes.
repeated PodSandbox items = 1;
}
// ImageSpec is an internal representation of an image. Currently, it wraps the
// value of a Container's Image field (e.g. imageID or imageDigest), but in the
// future it will include more detailed information about the different image types.
message ImageSpec {
string image = 1;
}
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;
}
// 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;
// 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;
}
// 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;
}
// ContainerMetadata holds all necessary information for building the container
// name. The container runtime is encouraged to expose the metadata in its user
// interface for better user experience. E.g., runtime can construct a unique
// container name based on the metadata. Note that (name, attempt) is unique
// within a sandbox for the entire lifetime of the sandbox.
message ContainerMetadata {
// Name of the container. Same as the container name in the PodSpec.
string name = 1;
// Attempt number of creating the container. Default: 0.
uint32 attempt = 2;
}
// Device specifies a host device to mount into a container.
message Device {
// Path of the device within the container.
string container_path = 1;
// Path of the device on the host.
string host_path = 2;
// Cgroups permissions of the device, candidates are one or more of
// * r - allows container to read from the specified device.
// * w - allows container to write to the specified device.
// * m - allows container to create device files that do not yet exist.
string permissions = 3;
}
// ContainerConfig holds all the required and optional fields for creating a
// container.
message ContainerConfig {
// Metadata of the container. This information will uniquely identify the
// container, and the runtime should leverage this to ensure correct
// operation. The runtime may also use this information to improve UX, such
// as by constructing a readable name.
ContainerMetadata metadata = 1 ;
// Image to use.
ImageSpec image = 2;
// Command to execute (i.e., entrypoint for docker)
repeated string command = 3;
// Args for the Command (i.e., command for docker)
repeated string args = 4;
// Current working directory of the command.
string working_dir = 5;
// List of environment variable to set in the container.
repeated KeyValue envs = 6;
// Mounts for the container.
repeated Mount mounts = 7;
// Devices for the container.
repeated Device devices = 8;
// Key-value pairs that may be used to scope and select individual resources.
// Label keys are of the form:
// label-key ::= prefixed-name | name
// prefixed-name ::= prefix '/' name
// prefix ::= DNS_SUBDOMAIN
// name ::= DNS_LABEL
map<string, string> labels = 9;
// Unstructured key-value map that may be used by the kubelet to store and
// retrieve arbitrary metadata.
//
// Annotations MUST NOT be altered by the runtime; the annotations stored
// here MUST be returned in the ContainerStatus associated with the container
// this ContainerConfig creates.
//
// In general, in order to preserve a well-defined interface between the
// kubelet and the container runtime, annotations SHOULD NOT influence
// runtime behaviour.
map<string, string> annotations = 10;
// Path relative to PodSandboxConfig.LogDirectory for container to store
// the log (STDOUT and STDERR) on the host.
// E.g.,
// PodSandboxConfig.LogDirectory = `/var/log/pods/<podUID>/`
// ContainerConfig.LogPath = `containerName_Instance#.log`
//
// WARNING: Log management and how kubelet should interface with the
// container logs are under active discussion in
// https://issues.k8s.io/24677. There *may* be future change of direction
// for logging as the discussion carries on.
string log_path = 11;
// Variables for interactive containers, these have very specialized
// use-cases (e.g. debugging).
// TODO: Determine if we need to continue supporting these fields that are
// part of Kubernetes's Container Spec.
bool stdin = 12;
bool stdin_once = 13;
bool tty = 14;
// Configuration specific to Linux containers.
LinuxContainerConfig linux = 15;
}
message CreateContainerRequest {
// ID of the PodSandbox in which the container should be created.
string pod_sandbox_id = 1;
// Config of the container.
ContainerConfig config = 2;
// Config of the PodSandbox. This is the same config that was passed
// to RunPodSandboxRequest to create the PodSandbox. It is passed again
// here just for easy reference. The PodSandboxConfig is immutable and
// remains the same throughout the lifetime of the pod.
PodSandboxConfig sandbox_config = 3;
}
message CreateContainerResponse {
// ID of the created container.
string container_id = 1;
}
message StartContainerRequest {
// ID of the container to start.
string container_id = 1;
}
message StartContainerResponse {}
message StopContainerRequest {
// ID of the container to stop.
string container_id = 1;
// Timeout in seconds to wait for the container to stop before forcibly
// terminating it. Default: 0 (forcibly terminate the container immediately)
int64 timeout = 2;
}
message StopContainerResponse {}
message RemoveContainerRequest {
// ID of the container to remove.
string container_id = 1;
}
message RemoveContainerResponse {}
enum ContainerState {
CONTAINER_CREATED = 0;
CONTAINER_RUNNING = 1;
CONTAINER_EXITED = 2;
CONTAINER_UNKNOWN = 3;
}
// ContainerStateValue is the wrapper of ContainerState.
message ContainerStateValue {
// State of the container.
ContainerState state = 1;
}
// ContainerFilter is used to filter containers.
// All those fields are combined with 'AND'
message ContainerFilter {
// ID of the container.
string id = 1;
// State of the container.
ContainerStateValue state = 2;
// ID of the PodSandbox.
string pod_sandbox_id = 3;
// LabelSelector to select matches.
// Only api.MatchLabels is supported for now and the requirements
// are ANDed. MatchExpressions is not supported yet.
map<string, string> label_selector = 4;
}
message ListContainersRequest {
ContainerFilter filter = 1;
}
// Container provides the runtime information for a container, such as ID, hash,
// state of the container.
message Container {
// ID of the container, used by the container runtime to identify
// a container.
string id = 1;
// ID of the sandbox to which this container belongs.
string pod_sandbox_id = 2;
// Metadata of the container.
ContainerMetadata metadata = 3;
// Spec of the image.
ImageSpec image = 4;
// Reference to the image in use. For most runtimes, this should be an
// image ID.
string image_ref = 5;
// State of the container.
ContainerState state = 6;
// Creation time of the container in nanoseconds.
int64 created_at = 7;
// Key-value pairs that may be used to scope and select individual resources.
map<string, string> labels = 8;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding ContainerConfig used to
// instantiate this Container.
map<string, string> annotations = 9;
}
message ListContainersResponse {
// List of containers.
repeated Container containers = 1;
}
message ContainerStatusRequest {
// ID of the container for which to retrieve status.
string container_id = 1;
}
// ContainerStatus represents the status of a container.
message ContainerStatus {
// ID of the container.
string id = 1;
// Metadata of the container.
ContainerMetadata metadata = 2;
// Status of the container.
ContainerState state = 3;
// Creation time of the container in nanoseconds.
int64 created_at = 4;
// Start time of the container in nanoseconds. Default: 0 (not specified).
int64 started_at = 5;
// Finish time of the container in nanoseconds. Default: 0 (not specified).
int64 finished_at = 6;
// Exit code of the container. Only required when finished_at != 0. Default: 0.
int32 exit_code = 7;
// Spec of the image.
ImageSpec image = 8;
// Reference to the image in use. For most runtimes, this should be an
// image ID
string image_ref = 9;
// Brief CamelCase string explaining why container is in its current state.
string reason = 10;
// Human-readable message indicating details about why container is in its
// current state.
string message = 11;
// Key-value pairs that may be used to scope and select individual resources.
map<string,string> labels = 12;
// Unstructured key-value map holding arbitrary metadata.
// Annotations MUST NOT be altered by the runtime; the value of this field
// MUST be identical to that of the corresponding ContainerConfig used to
// instantiate the Container this status represents.
map<string,string> annotations = 13;
// Mounts for the container.
repeated Mount mounts = 14;
}
message ContainerStatusResponse {
// Status of the container.
ContainerStatus status = 1;
}
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.
bool stdin = 4;
}
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.
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;
}
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;
}
message ListImagesResponse {
// List of images.
repeated Image images = 1;
}
message ImageStatusRequest {
// Spec of the image.
ImageSpec image = 1;
}
message ImageStatusResponse {
// Status of the image.
Image image = 1;
}
// 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.
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 {}
message StatusResponse {
// Status of the Runtime.
RuntimeStatus status = 1;
}