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-replicas-for-all-shards {
 123         output {
 124             uses shard-result-output;
 125         }
 126
 127         description "Adds replicas on this node for all currently defined shards. This is equivalent to issuing
 128                      an add-shard-replica RPC for all shards.";
 129     }
 130
 131     rpc remove-all-shard-replicas {
 132         input {
 133             leaf member-name {
 134                 mandatory true;
 135                 type string;
 136                 description "The cluster member from which the shard replicas should be removed";
 137             }
 138         }
 139
 140         output {
 141             uses shard-result-output;
 142         }
 143
 144         description "Removes replicas for all shards on this node. This is equivalent to issuing
 145                      a remove-shard-replica for all shards and essentially removes this node from a cluster.";
 146     }
 147
 148     rpc change-member-voting-states-for-shard {
 149         input {
 150             uses datastore-shard-id;
 151             uses member-voting-states-input;
 152         }
 153
 154         description "Changes the voting states, either voting or non-voting, of cluster members for a shard.
 155                      Non-voting members will no longer participate in leader elections and consensus but will be
 156                      replicated. This is useful for having a set of members serve as a backup cluster in case the
 157                      primary voting cluster suffers catastrophic failure. This RPC can be issued to any cluster member
 158                      and will be forwarded to the leader.";
 159     }
 160
 161     rpc change-member-voting-states-for-all-shards {
 162         input {
 163             uses member-voting-states-input;
 164         }
 165
 166         output {
 167             uses shard-result-output;
 168         }
 169
 170         description "Changes the voting states, either voting or non-voting, of cluster members for all shards.
 171                      Non-voting members will no longer participate in leader elections and consensus but will be
 172                      replicated. This is useful for having a set of members serve as a backup cluster in case the
 173                      primary voting cluster suffers catastrophic failure. This RPC can be issued to any cluster member
 174                      and will be forwarded to the leader.";
 175     }
 176
 177     rpc flip-member-voting-states-for-all-shards {
 178         output {
 179             uses shard-result-output;
 180         }
 181
 182         description "Flips the voting states of all cluster members for all shards, such that if a member
 183                      was voting it becomes non-voting and vice versa.";
 184     }
 185
 186     rpc backup-datastore {
 187         input {
 188             leaf file-path {
 189               type string;
 190               description "The path and name of the file in which to store the backup.";
 191             }
 192
 193             leaf timeout {
 194               type uint32 {
 195                 range 1..max;
 196               }
 197               units "seconds";
 198               description "Optional timeout in seconds for the backup operation which will override all the different
 199                            timeouts that are being hit on the backend.";
 200             }
 201         }
 202
 203         description "Creates a backup file of the datastore state";
 204     }
 205
 206     rpc get-shard-role {
 207         input {
 208             uses datastore-shard-id;
 209         }
 210
 211         output {
 212             leaf role {
 213                 type string;
 214                 description "Current role for the given shard, if not present the shard currently does not have a role";
 215             }
 216         }
 217
 218         description "Returns the current role for the requested module shard.";
 219     }
 220
 221     rpc locate-shard {
 222         description "Return the transport-level information about where a shard has a home.";
 223         input {
 224             uses datastore-shard-id;
 225         }
 226
 227         output {
 228             choice member-node {
 229                 description "Location of the hypothetical cluster member node. Relationship to the input parameters
 230                              and the transport protocol.";
 231
 232                 leaf local {
 233                     description "Local node is the best node to talk to when it comes from efficiency perspective
 234                                  of underlying implementation. The requester of this RPC is advised to contact
 235                                  any services to the specified shard via the channel on which this RPC was invoked.";
 236                     type empty;
 237                 }
 238
 239                 leaf leader-actor-ref {
 240                     description "Actor reference to the actor which is currently acting as the leader.";
 241                     type string;
 242                 }
 243             }
 244         }
 245     }
 246
 247     rpc get-known-clients-for-all-shards {
 248         description "Request all shards to report their known frontend clients. This is useful for determining what
 249                      generation should a resurrected member node should use.";
 250
 251         output {
 252             uses shard-result-output {
 253                 augment shard-result {
 254                     list known-clients {
 255                         when "../succeeded = true";
 256
 257                         uses cds:client-identifier;
 258                         key "member type";
 259                     }
 260                 }
 261             }
 262         }
 263     }
 264
 265     rpc activate-eos-datacenter {
 266         description "Activates the datacenter that the node this rpc is called on belongs to. The caller must maintain
 267                      only a single active datacenter at a time as the singleton components will interfere with each
 268                      other otherwise. This only needs to be used if configuring multiple datacenters or if not using
 269                      default datacenter.";
 270     }
 271
 272     rpc deactivate-eos-datacenter {
 273         description "Deactivates the datacenter that the node this rpc is called on belongs to. The caller must maintain
 274                      only a single active datacenter at a time as the singleton components will interfere with each
 275                      other otherwise. This only needs to be used if configuring multiple datacenters or if not using
 276                      default datacenter.";
 277     }
 278 }