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 "2025-01-31" {
  10     description "A number of modeling updates:
  11                  - split out 'shard-name' typedef
  12                  - use 'member-name' from odl-controller-cds-types
  13                  - 'member-voting-state' now expresses what it means
  14                  - 'local' is now a presence container, a better modeling practice,
  15                  - choice/case statements are spelled out for codegen ergonomy,
  16                  - 'shard-result' error reporting has been cleaned up clarity and ergonomy";
  17   }
  18
  19   revision "2015-10-13" {
  20     description "Initial revision.";
  21   }
  22
  23   import odl-controller-cds-types { prefix cds; }
  24
  25   typedef data-store-type {
  26     type enumeration {
  27       enum config {
  28         value 1;
  29       }
  30       enum operational {
  31         value 2;
  32       }
  33     }
  34   }
  35
  36   typedef shard-name {
  37     description "A valid name for a shard.";
  38     type string {
  39       length "1..max" {
  40         error-app-tag "odl-named-shards";
  41         error-message "Shard name must not be empty";
  42       }
  43     }
  44   }
  45
  46   grouping datastore-shard-id {
  47     description
  48       "Grouping holding combined identifiers of a shard -- its name and datastore type";
  49
  50     leaf shard-name {
  51       mandatory true;
  52       type shard-name;
  53       description "The name of the shard.";
  54     }
  55
  56     leaf data-store-type {
  57       mandatory true;
  58       type data-store-type;
  59       description "The type of the data store to which the shard belongs";
  60     }
  61   }
  62
  63   grouping shard-result-output {
  64     list shard-result {
  65       key "shard-name data-store-type";
  66       description "The list of results, one per shard";
  67
  68       uses datastore-shard-id;
  69
  70       choice result {
  71         mandatory true;
  72
  73         case success-case {
  74           container success {
  75             presence "Indicates the operation was successful";
  76           }
  77         }
  78         case failure-case {
  79           container failure {
  80             presence "Indicates the operation was unsuccessful";
  81
  82             leaf message {
  83               type string;
  84               description "Indicates the operation failed with this message, which should be descriptive, if possible.";
  85             }
  86           }
  87         }
  88       }
  89     }
  90   }
  91
  92   grouping member-voting-states-input {
  93     list member-voting-state {
  94       key member-name;
  95       min-elements 1;
  96       description "The list of member voting states";
  97
  98       leaf member-name {
  99         type cds:member-name;
 100       }
 101
 102       leaf voting {
 103         mandatory true;
 104         type boolean;
 105       }
 106     }
 107   }
 108
 109   rpc add-shard-replica {
 110     description "Adds a replica of a shard to this node and joins it to an existing cluster. The shard must
 111                  already have a module configuration defined for it and there must already be a shard existing on
 112                  another node with a leader. This RPC first contacts peer member seed nodes searching for a shard.
 113                  When found, an AddServer message is sent to the shard leader and applied as described in the Raft
 114                  paper.";
 115
 116     input {
 117       uses datastore-shard-id;
 118     }
 119   }
 120
 121   rpc remove-shard-replica {
 122     description "Removes an existing replica of a shard from this node via the RemoveServer mechanism as
 123                  described in the Raft paper.";
 124
 125     input {
 126       uses datastore-shard-id;
 127
 128       leaf member-name {
 129         mandatory true;
 130         type cds:member-name;
 131         description "The cluster member from which the shard replica should be removed";
 132       }
 133     }
 134   }
 135
 136   rpc make-leader-local {
 137     description "Attempts to move the shard leader of the given module based shard to the local node.
 138                  The rpc returns a response after handling of the underlying MakeLeaderLocal message completes.
 139                  This operation fails if there is no current shard leader due to lack of network connectivity or
 140                  a cluster majority. In addition, if the local node is not up to date with the current leader,
 141                  an attempt is made to first sync the local node with the leader. If this cannot be achieved
 142                  within two election timeout periods the operation fails.";
 143
 144     input {
 145       uses datastore-shard-id;
 146     }
 147   }
 148
 149   rpc add-replicas-for-all-shards {
 150     description "Adds replicas on this node for all currently defined shards. This is equivalent to issuing
 151                  an add-shard-replica RPC for all shards.";
 152
 153     output {
 154       uses shard-result-output;
 155     }
 156   }
 157
 158   rpc remove-all-shard-replicas {
 159     description "Removes replicas for all shards on this node. This is equivalent to issuing
 160                  a remove-shard-replica for all shards and essentially removes this node from a cluster.";
 161
 162     input {
 163       leaf member-name {
 164         mandatory true;
 165         type cds:member-name;
 166         description "The cluster member from which the shard replicas should be removed";
 167       }
 168     }
 169
 170     output {
 171       uses shard-result-output;
 172     }
 173   }
 174
 175   rpc change-member-voting-states-for-shard {
 176     description "Changes the voting states, either voting or non-voting, of cluster members for a shard.
 177                  Non-voting members will no longer participate in leader elections and consensus but will be
 178                  replicated. This is useful for having a set of members serve as a backup cluster in case the
 179                  primary voting cluster suffers catastrophic failure. This RPC can be issued to any cluster member
 180                  and will be forwarded to the leader.";
 181
 182     input {
 183       uses datastore-shard-id;
 184       uses member-voting-states-input;
 185     }
 186   }
 187
 188   rpc change-member-voting-states-for-all-shards {
 189     description "Changes the voting states, either voting or non-voting, of cluster members for all shards.
 190                  Non-voting members will no longer participate in leader elections and consensus but will be
 191                  replicated. This is useful for having a set of members serve as a backup cluster in case the
 192                  primary voting cluster suffers catastrophic failure. This RPC can be issued to any cluster member
 193                  and will be forwarded to the leader.";
 194
 195     input {
 196       uses member-voting-states-input;
 197     }
 198
 199     output {
 200       uses shard-result-output;
 201     }
 202   }
 203
 204   rpc flip-member-voting-states-for-all-shards {
 205     description "Flips the voting states of all cluster members for all shards, such that if a member
 206                  was voting it becomes non-voting and vice versa.";
 207
 208     output {
 209       uses shard-result-output;
 210     }
 211   }
 212
 213   rpc backup-datastore {
 214     description "Creates a backup file of the datastore state";
 215
 216     input {
 217       leaf file-path {
 218         type string;
 219         description "The path and name of the file in which to store the backup.";
 220       }
 221
 222       leaf timeout {
 223         type uint32 {
 224           range 1..max;
 225         }
 226         units "seconds";
 227         default 60;
 228         description "Optional timeout in seconds for the backup operation which will override all the different
 229                      timeouts that are being hit on the backend.";
 230       }
 231     }
 232   }
 233
 234   rpc get-shard-role {
 235     description "Returns the current role for the requested module shard.";
 236
 237     input {
 238         uses datastore-shard-id;
 239     }
 240
 241     output {
 242       leaf role {
 243         type string;
 244         description "Current role for the given shard, if not present the shard currently does not have a role";
 245       }
 246     }
 247   }
 248
 249   rpc locate-shard {
 250     description "Return the transport-level information about where a shard has a home.";
 251
 252     input {
 253         uses datastore-shard-id;
 254     }
 255
 256     output {
 257       choice member-node {
 258         description "Location of the hypothetical cluster member node. Relationship to the input parameters
 259                      and the transport protocol.";
 260
 261         case local-case {
 262           container local {
 263             presence "Local node is the best node to talk to when it comes from efficiency perspective
 264                       of underlying implementation. The requester of this RPC is advised to contact
 265                       any services to the specified shard via the channel on which this RPC was invoked.";
 266           }
 267         }
 268         case leader-actor-ref-case {
 269           leaf leader-actor-ref {
 270             description "Actor reference to the actor which is currently acting as the leader.";
 271             type string;
 272           }
 273         }
 274       }
 275     }
 276   }
 277
 278   rpc get-known-clients-for-all-shards {
 279     description "Request all shards to report their known frontend clients. This is useful for determining what
 280                  generation should a resurrected member node should use.";
 281
 282     output {
 283       uses shard-result-output {
 284         augment shard-result/result/success-case/success {
 285           list known-clients {
 286             uses cds:client-identifier;
 287             key "member type";
 288           }
 289         }
 290       }
 291     }
 292   }
 293
 294   rpc activate-eos-datacenter {
 295     description "Activates the datacenter that the node this rpc is called on belongs to. The caller must maintain
 296                  only a single active datacenter at a time as the singleton components will interfere with each
 297                  other otherwise. This only needs to be used if configuring multiple datacenters or if not using
 298                  default datacenter.";
 299   }
 300
 301   rpc deactivate-eos-datacenter {
 302     description "Deactivates the datacenter that the node this rpc is called on belongs to. The caller must maintain
 303                  only a single active datacenter at a time as the singleton components will interfere with each
 304                  other otherwise. This only needs to be used if configuring multiple datacenters or if not using
 305                  default datacenter.";
 306   }
 307 }