dispatcher.proto 8.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218
  1. syntax = "proto3";
  2. package docker.swarmkit.v1;
  3. import "types.proto";
  4. import "objects.proto";
  5. import "gogoproto/gogo.proto";
  6. import "plugin/plugin.proto";
  7. import "google/protobuf/duration.proto";
  8. // Dispatcher is the API provided by a manager group for agents to connect to. Agents
  9. // connect to this service to receive task assignments and report status.
  10. //
  11. // API methods on this service are used only by agent nodes.
  12. service Dispatcher { // maybe dispatch, al likes this
  13. // Session starts an agent session with the dispatcher. The session is
  14. // started after the first SessionMessage is received.
  15. //
  16. // Once started, the agent is controlled with a stream of SessionMessage.
  17. // Agents should list on the stream at all times for instructions.
  18. rpc Session(SessionRequest) returns (stream SessionMessage) {
  19. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-worker" roles: "swarm-manager" };
  20. };
  21. // Heartbeat is heartbeat method for nodes. It returns new TTL in response.
  22. // Node should send new heartbeat earlier than now + TTL, otherwise it will
  23. // be deregistered from dispatcher and its status will be updated to NodeStatus_DOWN
  24. rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse) {
  25. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-worker" roles: "swarm-manager" };
  26. };
  27. // UpdateTaskStatus updates status of task. Node should send such updates
  28. // on every status change of its tasks.
  29. //
  30. // Whether receiving batch updates or single status updates, this method
  31. // should be accepting. Errors should only be returned if the entire update
  32. // should be retried, due to data loss or other problems.
  33. //
  34. // If a task is unknown the dispatcher, the status update should be
  35. // accepted regardless.
  36. rpc UpdateTaskStatus(UpdateTaskStatusRequest) returns (UpdateTaskStatusResponse) {
  37. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-worker" roles: "swarm-manager" };
  38. };
  39. // Tasks is a stream of tasks state for node. Each message contains full list
  40. // of tasks which should be run on node, if task is not present in that list,
  41. // it should be terminated.
  42. rpc Tasks(TasksRequest) returns (stream TasksMessage) {
  43. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-worker" roles: "swarm-manager" };
  44. option deprecated = true;
  45. };
  46. // Assignments is a stream of assignments such as tasks and secrets for node.
  47. // The first message in the stream contains all of the tasks and secrets
  48. // that are relevant to the node. Future messages in the stream are updates to
  49. // the set of assignments.
  50. rpc Assignments(AssignmentsRequest) returns (stream AssignmentsMessage) {
  51. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-worker" roles: "swarm-manager" };
  52. };
  53. }
  54. // SessionRequest starts a session.
  55. message SessionRequest {
  56. NodeDescription description = 1;
  57. // SessionID can be provided to attempt resuming an existing session. If the
  58. // SessionID is empty or invalid, a new SessionID will be assigned.
  59. //
  60. // See SessionMessage.SessionID for details.
  61. string session_id = 2;
  62. }
  63. // SessionMessage instructs an agent on various actions as part of the current
  64. // session. An agent should act immediately on the contents.
  65. message SessionMessage {
  66. // SessionID is allocated after a successful registration. It should be
  67. // used on all RPC calls after registration. A dispatcher may choose to
  68. // change the SessionID, at which time an agent must re-register and obtain
  69. // a new one.
  70. //
  71. // All Dispatcher calls after register should include the SessionID. If the
  72. // Dispatcher so chooses, it may reject the call with an InvalidArgument
  73. // error code, at which time the agent should call Register to start a new
  74. // session.
  75. //
  76. // As a rule, once an agent has a SessionID, it should never save it to
  77. // disk or try to otherwise reuse. If the agent loses its SessionID, it
  78. // must start a new session through a call to Register. A Dispatcher may
  79. // choose to reuse the SessionID, if it sees fit, but it is not advised.
  80. //
  81. // The actual implementation of the SessionID is Dispatcher specific and
  82. // should be treated as opaque by agents.
  83. //
  84. // From a Dispatcher perspective, there are many ways to use the SessionID
  85. // to ensure uniqueness of a set of client RPC calls. One method is to keep
  86. // the SessionID unique to every call to Register in a single Dispatcher
  87. // instance. This ensures that the SessionID represents the unique
  88. // session from a single Agent to Manager. If the Agent restarts, we
  89. // allocate a new session, since the restarted Agent is not aware of the
  90. // new SessionID.
  91. //
  92. // The most compelling use case is to support duplicate node detection. If
  93. // one clones a virtual machine, including certificate material, two nodes
  94. // may end up with the same identity. This can also happen if two identical
  95. // agent processes are coming from the same node. If the SessionID is
  96. // replicated through the cluster, we can immediately detect the condition
  97. // and address it.
  98. //
  99. // Extending from the case above, we can actually detect a compromised
  100. // identity. Coupled with provisions to rebuild node identity, we can ban
  101. // the compromised node identity and have the nodes re-authenticate and
  102. // build a new identity. At this time, an administrator can then
  103. // re-authorize the compromised nodes, if it was a mistake or ensure that a
  104. // misbehaved node can no longer connect to the cluster.
  105. //
  106. // We considered placing this field in a GRPC header. Because this is a
  107. // critical feature of the protocol, we thought it should be represented
  108. // directly in the RPC message set.
  109. string session_id = 1;
  110. // Node identifies the registering node.
  111. Node node = 2;
  112. // Managers provides a weight list of alternative dispatchers
  113. repeated WeightedPeer managers = 3;
  114. // Symmetric encryption key distributed by the lead manager. Used by agents
  115. // for securing network bootstrapping and communication.
  116. repeated EncryptionKey network_bootstrap_keys = 4;
  117. // Which root certificates to trust
  118. bytes RootCA = 5;
  119. }
  120. // HeartbeatRequest provides identifying properties for a single heartbeat.
  121. message HeartbeatRequest {
  122. string session_id = 1;
  123. }
  124. message HeartbeatResponse {
  125. // Period is the duration to wait before sending the next heartbeat.
  126. // Well-behaved agents should update this on every heartbeat round trip.
  127. google.protobuf.Duration period = 1 [(gogoproto.stdduration) = true, (gogoproto.nullable) = false];
  128. }
  129. message UpdateTaskStatusRequest {
  130. // Tasks should contain all statuses for running tasks. Only the status
  131. // field must be set. The spec is not required.
  132. string session_id = 1;
  133. message TaskStatusUpdate {
  134. string task_id = 1;
  135. TaskStatus status = 2;
  136. }
  137. repeated TaskStatusUpdate updates = 3;
  138. }
  139. message UpdateTaskStatusResponse{
  140. // void
  141. }
  142. message TasksRequest {
  143. string session_id = 1;
  144. }
  145. message TasksMessage {
  146. // Tasks is the set of tasks that should be running on the node.
  147. // Tasks outside of this set running on the node should be terminated.
  148. repeated Task tasks = 1;
  149. }
  150. message AssignmentsRequest {
  151. string session_id = 1;
  152. }
  153. message Assignment {
  154. oneof item {
  155. Task task = 1;
  156. Secret secret = 2;
  157. Config config = 3;
  158. }
  159. }
  160. message AssignmentChange {
  161. enum AssignmentAction {
  162. UPDATE = 0 [(gogoproto.enumvalue_customname) = "AssignmentActionUpdate"];
  163. REMOVE = 1 [(gogoproto.enumvalue_customname) = "AssignmentActionRemove"];
  164. }
  165. Assignment assignment = 1;
  166. AssignmentAction action = 2;
  167. }
  168. message AssignmentsMessage {
  169. // AssignmentType specifies whether this assignment message carries
  170. // the full state, or is an update to an existing state.
  171. enum Type {
  172. COMPLETE = 0;
  173. INCREMENTAL = 1;
  174. }
  175. Type type = 1;
  176. // AppliesTo references the previous ResultsIn value, to chain
  177. // incremental updates together. For the first update in a stream,
  178. // AppliesTo is empty. If AppliesTo does not match the previously
  179. // received ResultsIn, the consumer of the stream should start a new
  180. // Assignments stream to re-sync.
  181. string applies_to = 2;
  182. // ResultsIn identifies the result of this assignments message, to
  183. // match against the next message's AppliesTo value and protect
  184. // against missed messages.
  185. string results_in = 3;
  186. // AssignmentChange is a set of changes to apply on this node.
  187. repeated AssignmentChange changes = 4;
  188. }