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 }