github.com/outbrain/consul@v1.4.5/website/source/api/operator/raft.html.md (about)

     1  ---
     2  layout: api
     3  page_title: Raft - Operator - HTTP API
     4  sidebar_current: api-operator-raft
     5  description: |-
     6    The /operator/raft endpoints provide tools for management of Raft the
     7    consensus subsystem and cluster quorum.
     8  ---
     9  
    10  # Raft Operator HTTP API
    11  
    12  The `/operator/raft` endpoints provide tools for management of Raft the
    13  consensus subsystem and cluster quorum.
    14  
    15  Please see the [Consensus Protocol Guide](/docs/internals/consensus.html) for
    16  more information about Raft consensus protocol and its use.
    17  
    18  ## Read Configuration
    19  
    20  This endpoint reads the current raft configuration.
    21  
    22  | Method | Path                           | Produces                   |
    23  | ------ | ------------------------------ | -------------------------- |
    24  | `GET`  | `/operator/raft/configuration` | `application/json`         |
    25  
    26  The table below shows this endpoint's support for
    27  [blocking queries](/api/index.html#blocking-queries),
    28  [consistency modes](/api/index.html#consistency-modes),
    29  [agent caching](/api/index.html#agent-caching), and
    30  [required ACLs](/api/index.html#acls).
    31  
    32  | Blocking Queries | Consistency Modes     | Agent Caching | ACL Required    |
    33  | ---------------- | --------------------- | ------------- | --------------- |
    34  | `NO`             | `default` and `stale` | `none`        | `operator:read` |
    35  
    36  ### Parameters
    37  
    38  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
    39    the datacenter of the agent being queried. This is specified as part of the
    40    URL as a query string.
    41  
    42  - `stale` `(bool: false)` - If the cluster does not currently have a leader an
    43    error will be returned. You can use the `?stale` query parameter to read the
    44    Raft configuration from any of the Consul servers. Not setting this will choose
    45    the default consistency mode which will forward the request to the leader for
    46    processing but not re-confirm the server is still the leader before returning
    47    results. See [default consistency](/api/index.html#default) for more details.
    48  
    49  ### Sample Request
    50  
    51  ```text
    52  $ curl \
    53      http://127.0.0.1:8500/v1/operator/raft/configuration
    54  ```
    55  
    56  ### Sample Response
    57  
    58  ```json
    59  {
    60    "Servers": [
    61      {
    62        "ID": "127.0.0.1:8300",
    63        "Node": "alice",
    64        "Address": "127.0.0.1:8300",
    65        "Leader": true,
    66        "Voter": true
    67      },
    68      {
    69        "ID": "127.0.0.2:8300",
    70        "Node": "bob",
    71        "Address": "127.0.0.2:8300",
    72        "Leader": false,
    73        "Voter": true
    74      },
    75      {
    76        "ID": "127.0.0.3:8300",
    77        "Node": "carol",
    78        "Address": "127.0.0.3:8300",
    79        "Leader": false,
    80        "Voter": true
    81      }
    82    ],
    83    "Index": 22
    84  }
    85  ```
    86  
    87  - `Servers` is has information about the servers in the Raft peer configuration:
    88  
    89    - `ID` is the ID of the server. This is the same as the `Address` in Consul
    90      0.7 but may be upgraded to a GUID in a future version of Consul.
    91  
    92    - `Node` is the node name of the server, as known to Consul, or "(unknown)" if
    93      the node is stale and not known.
    94  
    95    - `Address` is the IP:port for the server.
    96  
    97    - `Leader` is either "true" or "false" depending on the server's role in the
    98      Raft configuration.
    99  
   100    - `Voter` is "true" or "false", indicating if the server has a vote in the
   101      Raft configuration. Future versions of Consul may add support for non-voting
   102      servers.
   103  
   104  - `Index` is the Raft corresponding to this configuration. The latest
   105    configuration may not yet be committed if changes are in flight.
   106  
   107  ## Delete Raft Peer
   108  
   109  This endpoint removes the Consul server with given address from the Raft
   110  configuration.
   111  
   112  There are rare cases where a peer may be left behind in the Raft configuration
   113  even though the server is no longer present and known to the cluster. This
   114  endpoint can be used to remove the failed server so that it is no longer affects
   115  the Raft quorum.
   116  
   117  If ACLs are enabled, the client will need to supply an ACL Token with `operator`
   118  write privileges.
   119  
   120  | Method   | Path                         | Produces                   |
   121  | -------- | ---------------------------- | -------------------------- |
   122  | `DELETE` | `/operator/raft/peer`        | `application/json`         |
   123  
   124  The table below shows this endpoint's support for
   125  [blocking queries](/api/index.html#blocking-queries),
   126  [consistency modes](/api/index.html#consistency-modes),
   127  [agent caching](/api/index.html#agent-caching), and
   128  [required ACLs](/api/index.html#acls).
   129  
   130  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required     |
   131  | ---------------- | ----------------- | ------------- | ---------------- |
   132  | `NO`             | `none`            | `none`        | `operator:write` |
   133  
   134  ### Parameters
   135  
   136  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
   137    the datacenter of the agent being queried. This is specified as part of the
   138    URL as a query string.
   139  
   140  - `id|address` `(string: <required>)` - Specifies the ID or address (IP:port) of the raft peer to remove.
   141  
   142  ### Sample Request
   143  
   144  ```text
   145  $ curl \
   146      --request DELETE \
   147      http://127.0.0.1:8500/v1/operator/raft/peer?address=1.2.3.4:5678
   148  ```