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