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 }