github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/api-docs/operator/raft.mdx (about)

     1  ---
     2  layout: api
     3  page_title: Raft - Operator - HTTP API
     4  description: |-
     5    The /operator/raft endpoints provide tools for management of  the Raft subsystem.
     6  ---
     7  
     8  # Raft Operator HTTP API
     9  
    10  The `/operator/raft` endpoints provide tools for management of the Raft subsystem.
    11  
    12  Please see the [Consensus Protocol Guide] for more information about Raft consensus protocol and its use.
    13  
    14  ## Read Raft Configuration
    15  
    16  This endpoint queries the status of a client node registered with Nomad.
    17  
    18  | Method | Path                              | Produces           |
    19  | ------ | --------------------------------- | ------------------ |
    20  | `GET`  | `/v1/operator/raft/configuration` | `application/json` |
    21  
    22  The table below shows this endpoint's support for
    23  [blocking queries](/api-docs#blocking-queries) and
    24  [required ACLs](/api-docs#acls).
    25  
    26  | Blocking Queries | ACL Required |
    27  | ---------------- | ------------ |
    28  | `NO`             | `management` |
    29  
    30  ### Parameters
    31  
    32  - `stale` - Specifies if the cluster should respond without an active leader.
    33    This is specified as a query string parameter.
    34  
    35  ### Sample Request
    36  
    37  ```shell-session
    38  $ curl \
    39      https://localhost:4646/v1/operator/raft/configuration
    40  ```
    41  
    42  ### Sample Response
    43  
    44  ```json
    45  {
    46    "Index": 1,
    47    "Servers": [
    48      {
    49        "Address": "127.0.0.1:4647",
    50        "ID": "127.0.0.1:4647",
    51        "Leader": true,
    52        "Node": "bacon-mac.global",
    53        "RaftProtocol": 2,
    54        "Voter": true
    55      }
    56    ]
    57  }
    58  ```
    59  
    60  #### Field Reference
    61  
    62  - `Index` `(int)` - The `Index` value is the Raft corresponding to this
    63    configuration. The latest configuration may not yet be committed if changes
    64    are in flight.
    65  
    66  - `Servers` `(array: Server)` - The returned `Servers` array has information
    67    about the servers in the Raft peer configuration.
    68  
    69    - `ID` `(string)` - The ID of the server. This is the same as the `Address`
    70      but may be upgraded to a GUID in a future version of Nomad.
    71  
    72    - `Node` `(string)` - The node name of the server, as known to Nomad, or
    73      `"(unknown)"` if the node is stale and not known.
    74  
    75    - `Address` `(string)` - The `ip:port` for the server.
    76  
    77    - `Leader` `(bool)` - is either "true" or "false" depending on the server's
    78      role in the Raft configuration.
    79  
    80    - `Voter` `(bool)` - is "true" or "false", indicating if the server has a vote
    81      in the Raft configuration. Future versions of Nomad may add support for
    82      non-voting servers.
    83  
    84  ## Remove Raft Peer
    85  
    86  This endpoint removes a Nomad server with given address from the Raft
    87  configuration. The return code signifies success or failure.
    88  
    89  | Method   | Path                     | Produces           |
    90  | -------- | ------------------------ | ------------------ |
    91  | `DELETE` | `/v1/operator/raft/peer` | `application/json` |
    92  
    93  The table below shows this endpoint's support for
    94  [blocking queries](/api-docs#blocking-queries) and
    95  [required ACLs](/api-docs#acls).
    96  
    97  | Blocking Queries | ACL Required |
    98  | ---------------- | ------------ |
    99  | `NO`             | `management` |
   100  
   101  ### Parameters
   102  
   103  - `address` `(string: <optional>)` - Specifies the server to remove as
   104    `ip:port`. This cannot be provided along with the `id` parameter.
   105  
   106  - `id` `(string: <optional>)` - Specifies the server to remove as
   107    `id`. This cannot be provided along with the `address` parameter.
   108  
   109  ### Sample Request
   110  
   111  ```shell-session
   112  $ curl \
   113      --request DELETE \
   114      https://localhost:4646/v1/operator/raft/peer?address=1.2.3.4:4646
   115  ```
   116  
   117  [consensus protocol guide]: /docs/concepts/consensus