-
Notifications
You must be signed in to change notification settings - Fork 611
/
types.proto
1691 lines (1421 loc) · 61.2 KB
/
types.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
syntax = "proto3";
package docker.swarmkit.v1;
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";
import "gogoproto/gogo.proto";
// This file contains types that are common to objects and spec or that are not
// considered first-class within the cluster object-model.
// Version tracks the last time an object in the store was updated.
message Version {
uint64 index = 1;
}
message IndexEntry {
string key = 1;
string val = 2;
}
// Annotations provide useful information to identify API objects. They are
// common to all API specs.
message Annotations {
string name = 1;
map<string, string> labels = 2;
// Indices provides keys and values for indexing this object.
// A single key may have multiple values.
repeated IndexEntry indices = 4 [(gogoproto.nullable) = false];
}
// NamedGenericResource represents a "user defined" resource which is defined
// as a string.
// "Kind" is used to describe the Kind of a resource (e.g: "GPU", "FPGA", "SSD", ...)
// Value is used to identify the resource (GPU="UUID-1", FPGA="/dev/sdb5", ...)
message NamedGenericResource {
string kind = 1;
string value = 2;
}
// DiscreteGenericResource represents a "user defined" resource which is defined
// as an integer
// "Kind" is used to describe the Kind of a resource (e.g: "GPU", "FPGA", "SSD", ...)
// Value is used to count the resource (SSD=5, HDD=3, ...)
message DiscreteGenericResource {
string kind = 1;
int64 value = 2;
}
// GenericResource represents a "user defined" resource which can
// be either an integer (e.g: SSD=3) or a string (e.g: SSD=sda1)
message GenericResource {
oneof resource {
NamedGenericResource named_resource_spec = 1;
DiscreteGenericResource discrete_resource_spec = 2;
}
}
enum ResourceType {
TASK = 0;
SECRET = 1;
CONFIG = 2;
VOLUME = 3;
}
message Resources {
// Amount of CPUs (e.g. 2000000000 = 2 CPU cores)
int64 nano_cpus = 1 [(gogoproto.customname) = "NanoCPUs"];
// Amount of memory in bytes.
int64 memory_bytes = 2;
// User specified resource (e.g: bananas=2;apple={red,yellow,green})
repeated GenericResource generic = 3;
}
message ResourceRequirements {
Resources limits = 1;
Resources reservations = 2;
// Amount of swap in bytes - can only be used together with a memory limit
// -1 means unlimited
// a null pointer indicates that the default behaviour of granting twice
// the memory is maintained
google.protobuf.Int64Value swap_bytes = 3;
// Tune container memory swappiness (0 to 100) - if not specified, defaults
// to the container OS's default - generally 60, or the value predefined in
// the image; set to -1 to unset a previously set value
google.protobuf.Int64Value memory_swappiness = 4;
}
message Platform {
// Architecture (e.g. x86_64)
string architecture = 1;
// Operating System (e.g. linux)
string os = 2 [(gogoproto.customname) = "OS"];
}
// PluginDescription describes an engine plugin.
message PluginDescription {
// Type of plugin. Canonical values for existing types are
// Volume, Network, and Authorization. More types could be
// supported in the future.
string type = 1;
// Name of the plugin
string name = 2;
}
message EngineDescription {
// Docker daemon version running on the node.
string engine_version = 1;
// Labels attached to the engine.
map<string, string> labels = 2;
// Volume, Network, and Auth plugins
repeated PluginDescription plugins = 3 [(gogoproto.nullable) = false];
}
message NodeDescription {
// Hostname of the node as reported by the agent.
// This is different from spec.meta.name which is user-defined.
string hostname = 1;
// Platform of the node.
Platform platform = 2;
// Total resources on the node.
Resources resources = 3;
// Information about the Docker Engine on the node.
EngineDescription engine = 4;
// Information on the node's TLS setup
NodeTLSInfo tls_info = 5 [(gogoproto.customname) = "TLSInfo"];
// FIPS indicates whether the node has FIPS-enabled
bool fips = 6 [(gogoproto.customname) = "FIPS"];
repeated NodeCSIInfo csi_info = 7 [(gogoproto.customname) = "CSIInfo"];
}
message NodeTLSInfo {
// Information about which root certs the node trusts
bytes trust_root = 1;
// Information about the node's current TLS certificate
bytes cert_issuer_subject = 2;
bytes cert_issuer_public_key = 3;
}
// NodeCSIInfo represents information about a Node returned by calling the
// NodeGetInfo RPC on the CSI plugin present on the node. There is a separate
// NodeCSIInfo object for each CSI plugin present.
message NodeCSIInfo {
// PluginName is the name of the CSI plugin.
string plugin_name = 1;
// NodeID is the ID of the node as reported by the CSI plugin. This will be
// different from the swarmkit node ID.
string node_id = 2;
// MaxVolumesPerNode is the maximum number of volumes that may be published
// to this node.
int64 max_volumes_per_node = 3;
// AccessibleTopology indicates the location of this node in the CSI plugin's
// topology
Topology accessible_topology = 4;
}
message RaftMemberStatus {
bool leader = 1;
enum Reachability {
// Unknown indicates that the manager state cannot be resolved
UNKNOWN = 0;
// Unreachable indicates that the node cannot be contacted by other
// raft cluster members.
UNREACHABLE = 1;
// Reachable indicates that the node is healthy and reachable
// by other members.
REACHABLE = 2;
}
Reachability reachability = 2;
string message = 3;
}
message NodeStatus {
// TODO(aluzzardi) These should be using `gogoproto.enumvalue_customname`.
enum State {
// Unknown indicates the node state cannot be resolved.
UNKNOWN = 0;
// Down indicates the node is down.
DOWN = 1;
// Ready indicates the node is ready to accept tasks.
READY = 2;
// Disconnected indicates the node is currently trying to find new manager.
DISCONNECTED = 3;
}
State state = 1;
string message = 2;
// Addr is the node's IP address as observed by the manager
string addr = 3;
}
message Image {
// reference is a docker image reference. This can include a rpository, tag
// or be fully qualified witha digest. The format is specified in the
// distribution/reference package.
string reference = 1;
}
// Mount describes volume mounts for a container.
//
// The Mount type follows the structure of the mount syscall, including a type,
// source, target. Top-level flags, such as writable, are common to all kinds
// of mounts, where we also provide options that are specific to a type of
// mount. This corresponds to flags and data, respectively, in the syscall.
message Mount {
enum Type {
option (gogoproto.goproto_enum_prefix) = false;
option (gogoproto.enum_customname) = "MountType";
BIND = 0 [(gogoproto.enumvalue_customname) = "MountTypeBind"]; // Bind mount host dir
VOLUME = 1 [(gogoproto.enumvalue_customname) = "MountTypeVolume"]; // Remote storage volumes
TMPFS = 2 [(gogoproto.enumvalue_customname) = "MountTypeTmpfs"]; // Mount a tmpfs
NPIPE = 3 [(gogoproto.enumvalue_customname) = "MountTypeNamedPipe"]; // Windows named pipes
CLUSTER = 4 [(gogoproto.enumvalue_customname) = "MountTypeCluster"]; // CSI volume
}
// Type defines the nature of the mount.
Type type = 1;
// Source specifies the name of the mount. Depending on mount type, this
// may be a volume name or a host path, or even ignored.
//
// For CSI type mounts, the source is either the name of the volume or the
// name of the volume group. To specify a volume group, the source should be
// prefixed with "group:", as in "group:groupname"
string source = 2;
// Target path in container
string target = 3;
// ReadOnly should be set to true if the mount should not be writable.
bool readonly = 4 [(gogoproto.customname) = "ReadOnly"];
// Consistency indicates the tolerable level of file system consistency
enum Consistency {
option (gogoproto.goproto_enum_prefix) = false;
option (gogoproto.enum_customname) = "MountConsistency";
DEFAULT = 0 [(gogoproto.enumvalue_customname) = "MountConsistencyDefault"];
CONSISTENT = 1 [(gogoproto.enumvalue_customname) = "MountConsistencyFull"];
CACHED = 2 [(gogoproto.enumvalue_customname) = "MountConsistencyCached"];
DELEGATED = 3 [(gogoproto.enumvalue_customname) = "MountConsistencyDelegated"];
}
Consistency consistency = 8;
// BindOptions specifies options that are specific to a bind mount.
message BindOptions {
enum Propagation {
option (gogoproto.goproto_enum_prefix) = false;
option (gogoproto.enum_customname) = "MountPropagation";
RPRIVATE = 0 [(gogoproto.enumvalue_customname) = "MountPropagationRPrivate"];
PRIVATE = 1 [(gogoproto.enumvalue_customname) = "MountPropagationPrivate"];
RSHARED = 2 [(gogoproto.enumvalue_customname) = "MountPropagationRShared"];
SHARED = 3 [(gogoproto.enumvalue_customname) = "MountPropagationShared"];
RSLAVE = 4 [(gogoproto.enumvalue_customname) = "MountPropagationRSlave"];
SLAVE = 5 [(gogoproto.enumvalue_customname) = "MountPropagationSlave"];
}
// Propagation mode of mount.
Propagation propagation = 1;
// allows non-recursive bind-mount, i.e. mount(2) with "bind" rather than "rbind".
bool nonrecursive = 2 [(gogoproto.customname) = "NonRecursive"];
// Create the mount point
bool createmountpoint = 3 [(gogoproto.customname) = "CreateMountpoint"];
// ReadOnlyNonRecursive makes the mount non-recursively read-only, but still leaves the mount recursive
// (unless NonRecursive is set to true in conjunction).
bool readonlynonrecursive = 4 [(gogoproto.customname) = "ReadOnlyNonRecursive"];
// ReadOnlyForceRecursive raises an error if the mount cannot be made recursively read-only.
bool readonlyforcerecursive = 5 [(gogoproto.customname) = "ReadOnlyForceRecursive"];
}
// VolumeOptions contains parameters for mounting the volume.
message VolumeOptions {
// nocopy prevents automatic copying of data to the volume with data from target
bool nocopy = 1 [(gogoproto.customname) = "NoCopy"];
// labels to apply to the volume if creating
map<string, string> labels = 2;
// DriverConfig specifies the options that may be passed to the driver
// if the volume is created.
//
// If this is empty, no volume will be created if the volume is missing.
Driver driver_config = 3;
// subpath inside the volume to mount.
string subpath = 4 [(gogoproto.customname) = "Subpath"];
}
message TmpfsOptions {
// Size sets the size of the tmpfs, in bytes.
//
// This will be converted to an operating system specific value
// depending on the host. For example, on linux, it will be convered to
// use a 'k', 'm' or 'g' syntax. BSD, though not widely supported with
// docker, uses a straight byte value.
//
// Percentages are not supported.
int64 size_bytes = 1;
// Mode of the tmpfs upon creation
uint32 mode = 2 [(gogoproto.customtype) = "os.FileMode", (gogoproto.nullable) = false];
// Options passed to tmpfs mount
string options = 3;
// TODO(stevvooe): There are several more tmpfs flags, specified in the
// daemon, that are accepted. Only the most basic are added for now.
//
// From docker/docker/pkg/mount/flags.go:
//
// var validFlags = map[string]bool{
// "": true,
// "size": true, X
// "mode": true, X
// "uid": true,
// "gid": true,
// "nr_inodes": true,
// "nr_blocks": true,
// "mpol": true,
// }
//
// Some of these may be straightforward to add, but others, such as
// uid/gid have implications in a clustered system.
}
// Depending on type, one of bind_options or volumes_options will be set.
// BindOptions configures properties of a bind mount type.
//
// For mounts of type bind, the source must be an absolute host path.
BindOptions bind_options = 5;
// VolumeOptions configures the properties specific to a volume mount type.
//
// For mounts of type volume, the source will be used as the volume name.
VolumeOptions volume_options = 6;
// TmpfsOptions allows one to set options for mounting a temporary
// filesystem.
//
// The source field will be ignored when using mounts of type tmpfs.
TmpfsOptions tmpfs_options = 7;
// TODO(stevvooe): It be better to use a oneof field above, although the
// type is enough to make the decision, while being primary to the
// datastructure.
}
message RestartPolicy {
enum RestartCondition {
option (gogoproto.goproto_enum_prefix) = false;
option (gogoproto.enum_customname) = "RestartCondition";
NONE = 0 [(gogoproto.enumvalue_customname) = "RestartOnNone"];
ON_FAILURE = 1 [(gogoproto.enumvalue_customname) = "RestartOnFailure"];
ANY = 2 [(gogoproto.enumvalue_customname) = "RestartOnAny"];
}
RestartCondition condition = 1;
// Delay between restart attempts
// Note: can't use stdduration because this field needs to be nullable.
google.protobuf.Duration delay = 2;
// MaxAttempts is the maximum number of restarts to attempt on an
// instance before giving up. Ignored if 0.
uint64 max_attempts = 3;
// Window is the time window used to evaluate the restart policy.
// The time window is unbounded if this is 0.
// Note: can't use stdduration because this field needs to be nullable.
google.protobuf.Duration window = 4;
}
// UpdateConfig specifies the rate and policy of updates.
// TODO(aluzzardi): Consider making this a oneof with RollingStrategy and LockstepStrategy.
message UpdateConfig {
// Maximum number of tasks to be updated in one iteration.
// 0 means unlimited parallelism.
uint64 parallelism = 1;
// Amount of time between updates.
google.protobuf.Duration delay = 2 [(gogoproto.stdduration) = true, (gogoproto.nullable) = false];
enum FailureAction {
PAUSE = 0;
CONTINUE = 1;
ROLLBACK = 2;
}
// FailureAction is the action to take when an update failures.
FailureAction failure_action = 3;
// Monitor indicates how long to monitor a task for failure after it is
// created. If the task fails by ending up in one of the states
// REJECTED, COMPLETED, or FAILED, within Monitor from its creation,
// this counts as a failure. If it fails after Monitor, it does not
// count as a failure. If Monitor is unspecified, a default value will
// be used.
// Note: can't use stdduration because this field needs to be nullable.
google.protobuf.Duration monitor = 4;
// MaxFailureRatio is the fraction of tasks that may fail during
// an update before the failure action is invoked. Any task created by
// the current update which ends up in one of the states REJECTED,
// COMPLETED or FAILED within Monitor from its creation counts as a
// failure. The number of failures is divided by the number of tasks
// being updated, and if this fraction is greater than
// MaxFailureRatio, the failure action is invoked.
//
// If the failure action is CONTINUE, there is no effect.
// If the failure action is PAUSE, no more tasks will be updated until
// another update is started.
// If the failure action is ROLLBACK, the orchestrator will attempt to
// roll back to the previous service spec. If the MaxFailureRatio
// threshold is hit during the rollback, the rollback will pause.
float max_failure_ratio = 5;
// UpdateOrder controls the order of operations when rolling out an
// updated task. Either the old task is shut down before the new task
// is started, or the new task is started before the old task is shut
// down.
enum UpdateOrder {
STOP_FIRST = 0;
START_FIRST = 1;
}
UpdateOrder order = 6;
}
// UpdateStatus is the status of an update in progress.
message UpdateStatus {
enum UpdateState {
UNKNOWN = 0;
UPDATING = 1;
PAUSED = 2;
COMPLETED = 3;
ROLLBACK_STARTED = 4;
ROLLBACK_PAUSED = 5; // if a rollback fails
ROLLBACK_COMPLETED = 6;
}
// State is the state of this update. It indicates whether the
// update is in progress, completed, paused, rolling back, or
// finished rolling back.
UpdateState state = 1;
// StartedAt is the time at which the update was started.
// Note: can't use stdtime because this field is nullable.
google.protobuf.Timestamp started_at = 2;
// CompletedAt is the time at which the update completed successfully,
// paused, or finished rolling back.
// Note: can't use stdtime because this field is nullable.
google.protobuf.Timestamp completed_at = 3;
// TODO(aaronl): Consider adding a timestamp showing when the most
// recent task update took place. Currently, this is nontrivial
// because each service update kicks off a replacement update, so
// updating the service object with a timestamp at every step along
// the rolling update would cause the rolling update to be constantly
// restarted.
// Message explains how the update got into its current state. For
// example, if the update is paused, it will explain what is preventing
// the update from proceeding (typically the failure of a task to start up
// when OnFailure is PAUSE).
string message = 4;
}
// TaskState enumerates the states that a task progresses through within an
// agent. States are designed to be monotonically increasing, such that if two
// states are seen by a task, the greater of the new represents the true state.
// Only the manager create a NEW task, and move the task to PENDING and ASSIGNED.
// Afterward, the manager must rely on the agent to update the task status
// (pre-run: preparing, ready, starting;
// running;
// end-state: complete, shutdown, failed, rejected)
enum TaskState {
// TODO(aluzzardi): Move it back into `TaskStatus` because of the naming
// collisions of enums.
option (gogoproto.goproto_enum_prefix) = false;
option (gogoproto.enum_customname) = "TaskState";
NEW = 0 [(gogoproto.enumvalue_customname)="TaskStateNew"];
PENDING = 64 [(gogoproto.enumvalue_customname)="TaskStatePending"]; // waiting for scheduling decision
ASSIGNED = 192 [(gogoproto.enumvalue_customname)="TaskStateAssigned"];
ACCEPTED = 256 [(gogoproto.enumvalue_customname)="TaskStateAccepted"]; // task has been accepted by an agent.
PREPARING = 320 [(gogoproto.enumvalue_customname)="TaskStatePreparing"];
READY = 384 [(gogoproto.enumvalue_customname)="TaskStateReady"];
STARTING = 448 [(gogoproto.enumvalue_customname)="TaskStateStarting"];
RUNNING = 512 [(gogoproto.enumvalue_customname)="TaskStateRunning"];
COMPLETE = 576 [(gogoproto.enumvalue_customname)="TaskStateCompleted"]; // successful completion of task (not error code, just ran)
SHUTDOWN = 640 [(gogoproto.enumvalue_customname)="TaskStateShutdown"]; // orchestrator requested shutdown
FAILED = 704 [(gogoproto.enumvalue_customname)="TaskStateFailed"]; // task execution failed with error
// TaskStateRejected means a task never ran, for instance if something about
// the environment failed (e.g. setting up a port on that node failed).
REJECTED = 768 [(gogoproto.enumvalue_customname)="TaskStateRejected"]; // task could not be executed here.
// TaskStateRemove is used to correctly handle service deletions and scale
// downs. This allows us to keep track of tasks that have been marked for
// deletion, but can't yet be removed because the agent is in the process of
// shutting them down. Once the agent has shut down tasks with desired state
// REMOVE, the task reaper is responsible for removing them.
REMOVE = 800 [(gogoproto.enumvalue_customname)="TaskStateRemove"];
// TaskStateOrphaned is used to free up resources associated with service
// tasks on unresponsive nodes without having to delete those tasks. This
// state is directly assigned to the task by the orchestrator.
ORPHANED = 832 [(gogoproto.enumvalue_customname)="TaskStateOrphaned"];
// NOTE(stevvooe): The state of a task is actually a lamport clock, in that
// given two observations, the greater of the two can be considered
// correct. To enforce this, we only allow tasks to proceed to a greater
// state.
//
// A byproduct of this design decision is that we must also maintain this
// invariant in the protobuf enum values, such that when comparing two
// values, the one with the greater value is also the greater state.
//
// Because we may want to add intervening states a later date, we've left
// 64 spaces between each one. This should allow us to make 5 or 6
// insertions between each state if we find that we made a mistake and need
// another state.
//
// Remove this message when the states are deemed perfect.
}
// Container specific status.
message ContainerStatus {
string container_id = 1;
int32 pid = 2 [(gogoproto.customname) = "PID"];
int32 exit_code = 3;
}
// PortStatus specifies the actual allocated runtime state of a list
// of port configs.
message PortStatus {
repeated PortConfig ports = 1;
}
message TaskStatus {
// Note: can't use stdtime because this field is nullable.
google.protobuf.Timestamp timestamp = 1;
// State expresses the current state of the task.
TaskState state = 2;
// Message reports a message for the task status. This should provide a
// human readable message that can point to how the task actually arrived
// at a current state.
//
// As a convention, we place the a small message here that led to the
// current state. For example, if the task is in ready, because it was
// prepared, we'd place "prepared" in this field. If we skipped preparation
// because the task is prepared, we would put "already prepared" in this
// field.
string message = 3;
// Err is set if the task is in an error state, or is unable to
// progress from an earlier state because a precondition is
// unsatisfied.
//
// The following states should report a companion error:
//
// FAILED, REJECTED
//
// In general, messages that should be surfaced to users belong in the
// Err field, and notes on routine state transitions belong in Message.
//
// TODO(stevvooe) Integrate this field with the error interface.
string err = 4;
// Container status contains container specific status information.
oneof runtime_status {
ContainerStatus container = 5;
}
// HostPorts provides a list of ports allocated at the host
// level.
PortStatus port_status = 6;
// AppliedBy gives the node ID of the manager that applied this task
// status update to the Task object.
string applied_by = 7;
// AppliedAt gives a timestamp of when this status update was applied to
// the Task object.
// Note: can't use stdtime because this field is nullable.
google.protobuf.Timestamp applied_at = 8;
}
// NetworkAttachmentConfig specifies how a service should be attached to a particular network.
//
// For now, this is a simple struct, but this can include future information
// instructing Swarm on how this service should work on the particular
// network.
message NetworkAttachmentConfig {
// Target specifies the target network for attachment. This value must be a
// network ID.
string target = 1;
// Aliases specifies a list of discoverable alternate names for the service on this Target.
repeated string aliases = 2;
// Addresses specifies a list of ipv4 and ipv6 addresses
// preferred. If these addresses are not available then the
// attachment might fail.
repeated string addresses = 3;
// DriverAttachmentOpts is a map of driver attachment options for the network target
map<string, string> driver_attachment_opts = 4;
}
// IPAMConfig specifies parameters for IP Address Management.
message IPAMConfig {
// TODO(stevvooe): It may make more sense to manage IPAM and network
// definitions separately. This will allow multiple networks to share IPAM
// instances. For now, we will follow the conventions of libnetwork and
// specify this as part of the network specification.
// AddressFamily specifies the network address family that
// this IPAMConfig belongs to.
enum AddressFamily {
UNKNOWN = 0; // satisfy proto3
IPV4 = 4;
IPV6 = 6;
}
AddressFamily family = 1;
// Subnet defines a network as a CIDR address (ie network and mask
// 192.168.0.1/24).
string subnet = 2;
// Range defines the portion of the subnet to allocate to tasks. This is
// defined as a subnet within the primary subnet.
string range = 3;
// Gateway address within the subnet.
string gateway = 4;
// Reserved is a list of address from the master pool that should *not* be
// allocated. These addresses may have already been allocated or may be
// reserved for another allocation manager.
map<string, string> reserved = 5;
}
// PortConfig specifies an exposed port which can be
// addressed using the given name. This can be later queried
// using a service discovery api or a DNS SRV query. The node
// port specifies a port that can be used to address this
// service external to the cluster by sending a connection
// request to this port to any node on the cluster.
message PortConfig {
enum Protocol {
option (gogoproto.goproto_enum_prefix) = false;
TCP = 0 [(gogoproto.enumvalue_customname) = "ProtocolTCP"];
UDP = 1 [(gogoproto.enumvalue_customname) = "ProtocolUDP"];
SCTP = 2 [(gogoproto.enumvalue_customname) = "ProtocolSCTP"];
}
// PublishMode controls how ports are published on the swarm.
enum PublishMode {
option (gogoproto.enum_customname) = "PublishMode";
option (gogoproto.goproto_enum_prefix) = false;
// PublishModeIngress exposes the port across the cluster on all nodes.
INGRESS = 0 [(gogoproto.enumvalue_customname) = "PublishModeIngress"];
// PublishModeHost exposes the port on just the target host. If the
// published port is undefined, an ephemeral port will be allocated. If
// the published port is defined, the node will attempt to allocate it,
// erroring the task if it fails.
HOST = 1 [(gogoproto.enumvalue_customname) = "PublishModeHost"];
}
// Name for the port. If provided the port information can
// be queried using the name as in a DNS SRV query.
string name = 1;
// Protocol for the port which is exposed.
Protocol protocol = 2;
// The port which the application is exposing and is bound to.
uint32 target_port = 3;
// PublishedPort specifies the port on which the service is exposed. If
// specified, the port must be within the available range. If not specified
// (value is zero), an available port is automatically assigned.
uint32 published_port = 4;
// PublishMode controls how the port is published.
PublishMode publish_mode = 5;
}
// Driver is a generic driver type to be used throughout the API. For now, a
// driver is simply a name and set of options. The field contents depend on the
// target use case and driver application. For example, a network driver may
// have different rules than a volume driver.
message Driver {
string name = 1;
map <string, string> options = 2;
}
message IPAMOptions {
Driver driver = 1;
repeated IPAMConfig configs = 3;
}
// Peer should be used anywhere where we are describing a remote peer.
message Peer {
string node_id = 1;
string addr = 2;
}
// WeightedPeer should be used anywhere where we are describing a remote peer
// with a weight.
message WeightedPeer {
Peer peer = 1;
int64 weight = 2;
}
message IssuanceStatus {
enum State {
option (gogoproto.goproto_enum_prefix) = false;
UNKNOWN = 0 [(gogoproto.enumvalue_customname) = "IssuanceStateUnknown"];
// A new certificate should be issued
RENEW = 1 [(gogoproto.enumvalue_customname)="IssuanceStateRenew"];
// Certificate is pending acceptance
PENDING = 2 [(gogoproto.enumvalue_customname)="IssuanceStatePending"];
// successful completion certificate issuance
ISSUED = 3 [(gogoproto.enumvalue_customname)="IssuanceStateIssued"];
// Certificate issuance failed
FAILED = 4 [(gogoproto.enumvalue_customname)="IssuanceStateFailed"];
// Signals workers to renew their certificate. From the CA's perspective
// this is equivalent to IssuanceStateIssued: a noop.
ROTATE = 5 [(gogoproto.enumvalue_customname)="IssuanceStateRotate"];
}
State state = 1;
// Err is set if the Certificate Issuance is in an error state.
// The following states should report a companion error:
// FAILED
string err = 2;
}
message AcceptancePolicy {
message RoleAdmissionPolicy {
message Secret {
// The actual content (possibly hashed)
bytes data = 1;
// The type of hash we are using, or "plaintext"
string alg = 2;
}
NodeRole role = 1;
// Autoaccept controls which roles' certificates are automatically
// issued without administrator intervention.
bool autoaccept = 2;
// Secret represents a user-provided string that is necessary for new
// nodes to join the cluster
Secret secret = 3;
}
repeated RoleAdmissionPolicy policies = 1;
}
message ExternalCA {
enum CAProtocol {
CFSSL = 0 [(gogoproto.enumvalue_customname) = "CAProtocolCFSSL"];
}
// Protocol is the protocol used by this external CA.
CAProtocol protocol = 1;
// URL is the URL where the external CA can be reached.
string url = 2 [(gogoproto.customname) = "URL"];
// Options is a set of additional key/value pairs whose interpretation
// depends on the specified CA type.
map<string, string> options = 3;
// CACert specifies which root CA is used by this external CA
bytes ca_cert = 4 [(gogoproto.customname) = "CACert"];
}
message CAConfig {
// NodeCertExpiry is the duration certificates should be issued for
// Note: can't use stdduration because this field needs to be nullable.
google.protobuf.Duration node_cert_expiry = 1;
// ExternalCAs is a list of CAs to which a manager node will make
// certificate signing requests for node certificates.
repeated ExternalCA external_cas = 2 [(gogoproto.customname) = "ExternalCAs"];
// SigningCACert is the desired CA certificate to be used as the root and
// signing CA for the swarm. If not provided, indicates that we are either happy
// with the current configuration, or (together with a bump in the ForceRotate value)
// that we want a certificate and key generated for us.
bytes signing_ca_cert = 3 [(gogoproto.customname) = "SigningCACert"];
// SigningCAKey is the desired private key, matching the signing CA cert, to be used
// to sign certificates for the swarm
bytes signing_ca_key = 4 [(gogoproto.customname) = "SigningCAKey"];
// ForceRotate is a counter that triggers a root CA rotation even if no relevant
// parameters have been in the spec. This will force the manager to generate a new
// certificate and key, if none have been provided.
uint64 force_rotate = 5;
}
// OrchestrationConfig defines cluster-level orchestration settings.
message OrchestrationConfig {
// TaskHistoryRetentionLimit is the number of historic tasks to keep per instance or
// node. If negative, never remove completed or failed tasks.
int64 task_history_retention_limit = 1;
}
// TaskDefaults specifies default values for task creation.
message TaskDefaults {
// LogDriver specifies the log driver to use for the cluster if not
// specified for each task.
//
// If this is changed, only new tasks will pick up the new log driver.
// Existing tasks will continue to use the previous default until rescheduled.
Driver log_driver = 1;
}
// DispatcherConfig defines cluster-level dispatcher settings.
message DispatcherConfig {
// HeartbeatPeriod defines how often agent should send heartbeats to
// dispatcher.
// Note: can't use stdduration because this field needs to be nullable.
google.protobuf.Duration heartbeat_period = 1;
}
// RaftConfig defines raft settings for the cluster.
message RaftConfig {
// SnapshotInterval is the number of log entries between snapshots.
uint64 snapshot_interval = 1;
// KeepOldSnapshots is the number of snapshots to keep beyond the
// current snapshot.
uint64 keep_old_snapshots = 2;
// LogEntriesForSlowFollowers is the number of log entries to keep
// around to sync up slow followers after a snapshot is created.
uint64 log_entries_for_slow_followers = 3;
// HeartbeatTick defines the amount of ticks (in seconds) between
// each heartbeat message sent to other members for health-check.
uint32 heartbeat_tick = 4;
// ElectionTick defines the amount of ticks (in seconds) needed
// without a leader to trigger a new election.
uint32 election_tick = 5;
}
message EncryptionConfig {
// AutoLockManagers specifies whether or not managers TLS keys and raft data
// should be encrypted at rest in such a way that they must be unlocked
// before the manager node starts up again.
bool auto_lock_managers = 1;
}
message SpreadOver {
string spread_descriptor = 1; // label descriptor, such as engine.labels.az
// TODO: support node information beyond engine and node labels
// TODO: in the future, add a map that provides weights for weighted
// spreading.
}
message PlacementPreference {
oneof Preference {
SpreadOver spread = 1;
}
}
// Placement specifies task distribution constraints.
message Placement {
// Constraints specifies a set of requirements a node should meet for a task.
repeated string constraints = 1;
// Preferences provide a way to make the scheduler aware of factors
// such as topology. They are provided in order from highest to lowest
// precedence.
repeated PlacementPreference preferences = 2;
// Platforms stores all the platforms that the image can run on.
// This field is used in the platform filter for scheduling. If empty,
// then the platform filter is off, meaning there are no scheduling restrictions.
repeated Platform platforms = 3;
// MaxReplicas specifies the limit for maximum number of replicas running on one node.
uint64 max_replicas = 4;
}
// JoinToken contains the join tokens for workers and managers.
message JoinTokens {
// Worker is the join token workers may use to join the swarm.
string worker = 1;
// Manager is the join token workers may use to join the swarm.
string manager = 2;
}
message RootCA {
// CAKey is the root CA private key.
bytes ca_key = 1 [(gogoproto.customname) = "CAKey"];
// CACert is the root CA certificate.
bytes ca_cert = 2 [(gogoproto.customname) = "CACert"];
// CACertHash is the digest of the CA Certificate.
string ca_cert_hash = 3 [(gogoproto.customname) = "CACertHash"];
// JoinTokens contains the join tokens for workers and managers.
JoinTokens join_tokens = 4 [(gogoproto.nullable) = false];
// RootRotation contains the new root cert and key we want to rotate to - if this is nil, we are not in the
// middle of a root rotation
RootRotation root_rotation = 5;
// LastForcedRotation matches the Cluster Spec's CAConfig's ForceRotation counter.
// It indicates when the current CA cert and key were generated (or updated).
uint64 last_forced_rotation = 6;
}
enum NodeRole {
option (gogoproto.enum_customname) = "NodeRole";
option (gogoproto.goproto_enum_prefix) = false;
WORKER = 0 [(gogoproto.enumvalue_customname) = "NodeRoleWorker"];
MANAGER = 1 [(gogoproto.enumvalue_customname) = "NodeRoleManager"];
}
message Certificate {
NodeRole role = 1;
bytes csr = 2 [(gogoproto.customname) = "CSR"];
IssuanceStatus status = 3 [(gogoproto.nullable) = false];
bytes certificate = 4;
// CN represents the node ID.
string cn = 5 [(gogoproto.customname) = "CN"];
}
// Symmetric keys to encrypt inter-agent communication.
message EncryptionKey {
// Agent subsystem the key is intended for. Example:
// networking:gossip
string subsystem = 1;
// Encryption algorithm that can implemented using this key
enum Algorithm {
option (gogoproto.goproto_enum_prefix) = false;
AES_128_GCM = 0;
}
Algorithm algorithm = 2;
bytes key = 3;
// Time stamp from the lamport clock of the key allocator to
// identify the relative age of the key.
uint64 lamport_time = 4;