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

©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.