Add the ability to report known connected clients
[controller.git] / opendaylight / md-sal / sal-cluster-admin-api / src / main / yang / cluster-admin.yang
1 module cluster-admin {
2     yang-version 1;
3     namespace "urn:opendaylight:params:xml:ns:yang:controller:md:sal:cluster:admin";
4     prefix "cluster-admin";
5
6     description
7         "This module contains YANG RPC definitions for administering a cluster.";
8
9     revision "2015-10-13" {
10         description "Initial revision.";
11     }
12
13     import odl-controller-cds-types { prefix cds; }
14
15     typedef data-store-type {
16         type enumeration {
17             enum config {
18                 value 1;
19             }
20             enum operational {
21                 value 2;
22             }
23         }
24     }
25
26     grouping datastore-shard-id {
27         description "Grouping holding combined identifiers of a shard -- its name and datastore type";
28
29         leaf shard-name {
30             description "The name of the shard.";
31             mandatory true;
32             type string {
33                 length "1..max" {
34                     error-app-tag "odl-named-shards";
35                     error-message "Shard name must not be empty";
36                 }
37             }
38         }
39
40         leaf data-store-type {
41             mandatory true;
42             type data-store-type;
43             description "The type of the data store to which the shard belongs";
44         }
45     }
46
47     grouping shard-operation-result {
48         uses datastore-shard-id;
49
50         leaf succeeded {
51             type boolean;
52         }
53
54         leaf error-message {
55             type string;
56         }
57     }
58
59     grouping shard-result-output {
60         list shard-result {
61             key "shard-name data-store-type";
62             uses shard-operation-result;
63
64             description "The list of results, one per shard";
65         }
66     }
67
68     grouping member-voting-states-input {
69         list member-voting-state {
70             leaf member-name {
71                 type string;
72             }
73
74             leaf voting {
75                 type boolean;
76             }
77
78             description "The list of member voting states";
79         }
80     }
81
82     rpc add-shard-replica {
83         input {
84             uses datastore-shard-id;
85         }
86
87         description "Adds a replica of a shard to this node and joins it to an existing cluster. The shard must
88                      already have a module configuration defined for it and there must already be a shard existing on
89                      another node with a leader. This RPC first contacts peer member seed nodes searching for a shard.
90                      When found, an AddServer message is sent to the shard leader and applied as described in the Raft
91                      paper.";
92     }
93
94     rpc remove-shard-replica {
95         input {
96             uses datastore-shard-id;
97
98             leaf member-name {
99                 mandatory true;
100                 type string;
101                 description "The cluster member from which the shard replica should be removed";
102             }
103         }
104
105         description "Removes an existing replica of a shard from this node via the RemoveServer mechanism as
106                      described in the Raft paper.";
107     }
108
109     rpc make-leader-local {
110         input {
111             uses datastore-shard-id;
112         }
113
114         description "Attempts to move the shard leader of the given module based shard to the local node.
115                      The rpc returns a response after handling of the underlying MakeLeaderLocal message completes.
116                      This operation fails if there is no current shard leader due to lack of network connectivity or
117                      a cluster majority. In addition, if the local node is not up to date with the current leader,
118                      an attempt is made to first sync the local node with the leader. If this cannot be achieved
119                      within two election timeout periods the operation fails.";
120     }
121
122     rpc add-prefix-shard-replica {
123         input {
124             leaf shard-prefix {
125                 mandatory true;
126                 type instance-identifier;
127             }
128
129             leaf data-store-type {
130                 mandatory true;
131                 type data-store-type;
132                 description "The type of the data store to which the replica belongs";
133             }
134         }
135
136         description "Adds a replica of a shard to this node and joins it to an existing cluster. There must already be
137                      a shard existing on another node with a leader. This RPC first contacts peer member seed nodes
138                      searching for a shard. When found, an AddServer message is sent to the shard leader and applied as
139                      described in the Raft paper.";
140     }
141
142     rpc remove-prefix-shard-replica {
143         input {
144             leaf shard-prefix {
145                 mandatory true;
146                 type instance-identifier;
147             }
148             leaf member-name {
149                 mandatory true;
150                 type string;
151                 description "The cluster member from which the shard replica should be removed";
152             }
153
154             leaf data-store-type {
155                 mandatory true;
156                 type data-store-type;
157                 description "The type of the data store to which the replica belongs";
158             }
159         }
160
161         description "Removes an existing replica of a prefix shard from this node via the RemoveServer mechanism as
162                      described in the Raft paper.";
163     }
164
165     rpc add-replicas-for-all-shards {
166         output {
167             uses shard-result-output;
168         }
169
170         description "Adds replicas on this node for all currently defined shards. This is equivalent to issuing
171                      an add-shard-replica RPC for all shards.";
172     }
173
174     rpc remove-all-shard-replicas {
175         input {
176             leaf member-name {
177                 mandatory true;
178                 type string;
179                 description "The cluster member from which the shard replicas should be removed";
180             }
181         }
182
183         output {
184             uses shard-result-output;
185         }
186
187         description "Removes replicas for all shards on this node. This is equivalent to issuing
188                      a remove-shard-replica for all shards and essentially removes this node from a cluster.";
189     }
190
191     rpc change-member-voting-states-for-shard {
192         input {
193             uses datastore-shard-id;
194             uses member-voting-states-input;
195         }
196
197         description "Changes the voting states, either voting or non-voting, of cluster members for a shard.
198                      Non-voting members will no longer participate in leader elections and consensus but will be
199                      replicated. This is useful for having a set of members serve as a backup cluster in case the
200                      primary voting cluster suffers catastrophic failure. This RPC can be issued to any cluster member
201                      and will be forwarded to the leader.";
202     }
203
204     rpc change-member-voting-states-for-all-shards {
205         input {
206             uses member-voting-states-input;
207         }
208
209         output {
210             uses shard-result-output;
211         }
212
213         description "Changes the voting states, either voting or non-voting, of cluster members for all shards.
214                      Non-voting members will no longer participate in leader elections and consensus but will be
215                      replicated. This is useful for having a set of members serve as a backup cluster in case the
216                      primary voting cluster suffers catastrophic failure. This RPC can be issued to any cluster member
217                      and will be forwarded to the leader.";
218     }
219
220     rpc flip-member-voting-states-for-all-shards {
221         output {
222             uses shard-result-output;
223         }
224
225         description "Flips the voting states of all cluster members for all shards, such that if a member
226                      was voting it becomes non-voting and vice versa.";
227     }
228
229     rpc backup-datastore {
230         input {
231             leaf file-path {
232               type string;
233               description "The path and name of the file in which to store the backup.";
234             }
235         }
236
237         description "Creates a backup file of the datastore state";
238     }
239
240     rpc get-shard-role {
241         input {
242             uses datastore-shard-id;
243         }
244
245         output {
246             leaf role {
247                 type string;
248                 description "Current role for the given shard, if not present the shard currently does not have a role";
249             }
250         }
251
252         description "Returns the current role for the requested module shard.";
253     }
254
255     rpc locate-shard {
256         description "Return the transport-level information about where a shard has a home.";
257         input {
258             uses datastore-shard-id;
259         }
260
261         output {
262             choice member-node {
263                 description "Location of the hypothetical cluster member node. Relationship to the input parameters
264                              and the transport protocol.";
265
266                 leaf local {
267                     description "Local node is the best node to talk to when it comes from efficiency perspective
268                                  of underlying implementation. The requester of this RPC is advised to contact
269                                  any services to the specified shard via the channel on which this RPC was invoked.";
270                     type empty;
271                 }
272
273                 leaf leader-actor-ref {
274                     description "Actor reference to the actor which is currently acting as the leader.";
275                     type string;
276                 }
277             }
278         }
279     }
280
281     rpc get-prefix-shard-role {
282         input {
283             leaf shard-prefix {
284                 mandatory true;
285                 type instance-identifier;
286             }
287
288             leaf data-store-type {
289                 mandatory true;
290                 type data-store-type;
291                 description "The type of the data store to which the replica belongs";
292             }
293         }
294
295         output {
296             leaf role {
297                 type string;
298                 description "Current role for the given shard, if not present the shard currently does not have a role";
299             }
300         }
301
302         description "Returns the current role for the requested module shard.";
303     }
304
305     rpc get-known-clients-for-all-shards {
306         description "Request all shards to report their known frontend clients. This is useful for determining what
307                      generation should a resurrected member node should use.";
308
309         output {
310             uses shard-result-output {
311                 augment shard-result {
312                     list known-clients {
313                         when "../succeeded = true";
314
315                         uses cds:client-identifier;
316                         key "member type";
317                     }
318                 }
319             }
320         }
321     }
322 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.