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 get-prefix-shard-role {
 254         input {
 255             leaf shard-prefix {
 256                 mandatory true;
 257                 type instance-identifier;
 258             }
 259
 260             leaf data-store-type {
 261                 mandatory true;
 262                 type data-store-type;
 263                 description "The type of the data store to which the replica belongs";
 264             }
 265         }
 266
 267         output {
 268             leaf role {
 269                 type string;
 270                 description "Current role for the given shard, if not present the shard currently does not have a role";
 271             }
 272         }
 273
 274         description "Returns the current role for the requested module shard.";
 275     }
 276 }