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 shard-operation-result {
  25         leaf shard-name {
  26             type string;
  27         }
  28
  29         leaf data-store-type {
  30             type data-store-type;
  31         }
  32
  33         leaf succeeded {
  34             type boolean;
  35         }
  36
  37         leaf error-message {
  38             type string;
  39         }
  40     }
  41
  42     grouping shard-result-output {
  43         list shard-result {
  44             key "shard-name data-store-type";
  45             uses shard-operation-result;
  46
  47             description "The list of results, one per shard";
  48         }
  49     }
  50
  51     grouping member-voting-states-input {
  52         list member-voting-state {
  53             leaf member-name {
  54                 type string;
  55             }
  56
  57             leaf voting {
  58                 type boolean;
  59             }
  60
  61             description "The list of member voting states";
  62         }
  63     }
  64
  65     rpc add-shard-replica {
  66         input {
  67             leaf shard-name {
  68                 mandatory true;
  69                 type string;
  70                 description "The name of the shard for which to create a replica.";
  71             }
  72
  73             leaf data-store-type {
  74                 mandatory true;
  75                 type data-store-type;
  76                 description "The type of the data store to which the replica belongs";
  77             }
  78         }
  79
  80         description "Adds a replica of a shard to this node and joins it to an existing cluster. The shard must
  81             already have a module configuration defined for it and there must already be a shard existing on
  82             another node with a leader. This RPC first contacts peer member seed nodes searching for a shard.
  83             When found, an AddServer message is sent to the shard leader and applied as described in the Raft
  84             paper.";
  85     }
  86
  87     rpc remove-shard-replica {
  88         input {
  89             leaf shard-name {
  90                 mandatory true;
  91                 type string;
  92                 description "The name of the shard for which to remove the replica.";
  93             }
  94
  95             leaf member-name {
  96                 mandatory true;
  97                 type string;
  98                 description "The cluster member from which the shard replica should be removed";
  99             }
 100
 101             leaf data-store-type {
 102                 mandatory true;
 103                 type data-store-type;
 104                 description "The type of the data store to which the replica belongs";
 105             }
 106         }
 107
 108         description "Removes an existing replica of a shard from this node via the RemoveServer mechanism as
 109             described in the Raft paper.";
 110     }
 111
 112     rpc make-leader-local {
 113         input {
 114             leaf shard-name {
 115                 mandatory true;
 116                 type string;
 117                 description "The name of the shard for which to move the leader to the local node";
 118             }
 119
 120             leaf data-store-type {
 121                 mandatory true;
 122                 type data-store-type;
 123                 description "The type of the data store to which the shard belongs";
 124             }
 125         }
 126
 127         description "Attempts to move the shard leader of the given module based shard to the local node.
 128                 The rpc returns a response after handling of the underlying MakeLeaderLocal message completes.
 129                 This operation fails if there is no current shard leader due to lack of network connectivity or
 130                 a cluster majority. In addition, if the local node is not up to date with the current leader,
 131                 an attempt is made to first sync the local node with the leader. If this cannot be achieved
 132                 within two election timeout periods the operation fails.";
 133     }
 134
 135     rpc add-prefix-shard-replica {
 136         input {
 137             leaf shard-prefix {
 138                 mandatory true;
 139                 type instance-identifier;
 140             }
 141
 142             leaf data-store-type {
 143                 mandatory true;
 144                 type data-store-type;
 145                 description "The type of the data store to which the replica belongs";
 146             }
 147         }
 148
 149         description "Adds a replica of a shard to this node and joins it to an existing cluster. There must already be
 150                     a shard existing on another node with a leader. This RPC first contacts peer member seed nodes
 151                     searching for a shard. When found, an AddServer message is sent to the shard leader and applied as
 152                     described in the Raft paper.";
 153     }
 154
 155     rpc remove-prefix-shard-replica {
 156         input {
 157             leaf shard-prefix {
 158                 mandatory true;
 159                 type instance-identifier;
 160             }
 161             leaf member-name {
 162                 mandatory true;
 163                 type string;
 164                 description "The cluster member from which the shard replica should be removed";
 165             }
 166
 167             leaf data-store-type {
 168                 mandatory true;
 169                 type data-store-type;
 170                 description "The type of the data store to which the replica belongs";
 171             }
 172         }
 173
 174         description "Removes an existing replica of a prefix shard from this node via the RemoveServer mechanism as
 175                     described in the Raft paper.";
 176     }
 177
 178     rpc add-replicas-for-all-shards {
 179         output {
 180             uses shard-result-output;
 181         }
 182
 183         description "Adds replicas on this node for all currently defined shards. This is equivalent to issuing
 184             an add-shard-replica RPC for all shards.";
 185     }
 186
 187     rpc remove-all-shard-replicas {
 188         input {
 189             leaf member-name {
 190                 mandatory true;
 191                 type string;
 192                 description "The cluster member from which the shard replicas should be removed";
 193             }
 194         }
 195
 196         output {
 197             uses shard-result-output;
 198         }
 199
 200         description "Removes replicas for all shards on this node. This is equivalent to issuing
 201             a remove-shard-replica for all shards and essentially removes this node from a cluster.";
 202     }
 203
 204     rpc change-member-voting-states-for-shard {
 205         input {
 206             leaf shard-name {
 207                 mandatory true;
 208                 type string;
 209                 description "The name of the shard for which to change voting state.";
 210             }
 211
 212             leaf data-store-type {
 213                 mandatory true;
 214                 type data-store-type;
 215                 description "The type of the data store to which the shard belongs";
 216             }
 217
 218             uses member-voting-states-input;
 219         }
 220
 221         description "Changes the voting states, either voting or non-voting, of cluster members for a shard.
 222             Non-voting members will no longer participate in leader elections and consensus but will be
 223             replicated. This is useful for having a set of members serve as a backup cluster in case the
 224             primary voting cluster suffers catastrophic failure. This RPC can be issued to any cluster member
 225             and will be forwarded to the leader.";
 226     }
 227
 228     rpc change-member-voting-states-for-all-shards {
 229         input {
 230             uses member-voting-states-input;
 231         }
 232
 233         output {
 234             uses shard-result-output;
 235         }
 236
 237         description "Changes the voting states, either voting or non-voting, of cluster members for all shards.
 238             Non-voting members will no longer participate in leader elections and consensus but will be
 239             replicated. This is useful for having a set of members serve as a backup cluster in case the
 240             primary voting cluster suffers catastrophic failure. This RPC can be issued to any cluster member
 241             and will be forwarded to the leader.";
 242     }
 243
 244     rpc flip-member-voting-states-for-all-shards {
 245         output {
 246             uses shard-result-output;
 247         }
 248
 249         description "Flips the voting states of all cluster members for all shards, such that if a member
 250             was voting it becomes non-voting and vice versa.";
 251     }
 252
 253     rpc backup-datastore {
 254         input {
 255             leaf file-path {
 256               type string;
 257               description "The path and name of the file in which to store the backup.";
 258             }
 259         }
 260
 261         description "Creates a backup file of the datastore state";
 262     }
 263 }