Raft Operator HTTP API

The /operator/raft endpoints provide tools for management of the Raft subsystem.

Please see the Consensus Protocol Guide for more information about Raft consensus protocol and its use.

Read Raft Configuration

This endpoint queries the status of a client node registered with Nomad.

The table below shows this endpoint's support for blocking queries and required ACLs.

Parameters

• stale - Specifies if the cluster should respond without an active leader. This is specified as a query string parameter.

Sample Request

$ nomad operator api /v1/operator/raft/configuration

$ curl \
    https://localhost:4646/v1/operator/raft/configuration

Sample Response

{
    "Index": 0,
    "Servers": [
        {
            "Address": "10.1.0.10:4647",
            "ID": "c13f9998-a0f3-d765-0b52-55a0b3ce5f88",
            "Leader": false,
            "Node": "node1.global",
            "RaftProtocol": "3",
            "Voter": true
        },
        {
            "Address": "10.1.0.20:4647",
            "ID": "d7927f2b-067f-45a4-6266-af8bb84de082",
            "Leader": true,
            "Node": "node2.global",
            "RaftProtocol": "3",
            "Voter": true
        },
        {
            "Address": "10.1.0.30:4647",
            "ID": "00d56ef8-938e-abc3-6f8a-f8ac80a80fb9",
            "Leader": false,
            "Node": "node3.global",
            "RaftProtocol": "3",
            "Voter": true
        }

    ]
}

Field Reference

• Index (int) - The Index value is the Raft corresponding to this configuration. The latest configuration may not yet be committed if changes are in flight.

• Servers (array: Server) - The returned Servers array has information about the servers in the Raft peer configuration.

  • ID (string) - The ID of the server. For Raft protocol v2, this is the same as the Address. Raft protocol v3 uses GUIDs as the ID.

  • Node (string) - The node name of the server, as known to Nomad, or "(unknown)" if the node is stale and not known.

  • Address (string) - The ip:port for the server.

  • Leader (bool) - is either "true" or "false" depending on the server's role in the Raft configuration.

  • Voter (bool) - is "true" or "false", indicating if the server has a vote in the Raft configuration. Future versions of Nomad may add support for non-voting servers.

Remove Raft Peer

This endpoint removes a Nomad server with given address from the Raft configuration. The return code signifies success or failure.

The table below shows this endpoint's support for blocking queries and required ACLs.

Parameters

• address (string: <optional>) - Specifies the Raft Address of the server to remove as provided in the output of /v1/operator/raft/configuration API endpoint or the nomad operator raft list-peers command.

• id (string: <optional>) - Specifies the Raft ID of the server to remove as provided in the output of /v1/operator/raft/configuration API endpoint or the nomad operator raft list-peers command.

  Note

  Either address or id must be provided, but not both.

Sample Request

$ nomad operator api -X DELETE \
   /v1/operator/raft/peer?address=1.2.3.4:4647

$ curl \
    --request DELETE \
    --header "X-Nomad-Token: ${NOMAD_TOKEN}"
    https://127.0.0.1:4646/v1/operator/raft/peer?address=1.2.3.4:4647

Transfer Leadership to another Raft Peer

This endpoint tells the current cluster leader to transfer leadership to the Nomad server with given address or ID in the Raft configuration. The return code signifies success or failure.

The table below shows this endpoint's support for blocking queries and required ACLs.

Parameters

• address (string: <optional>) - Specifies the Raft Address of the target server as provided in the output of /v1/operator/raft/configuration API endpoint or the nomad operator raft list-peers command.

• id (string: <optional>) - Specifies the Raft ID of the target server as provided in the output of /v1/operator/raft/configuration API endpoint or the nomad operator raft list-peers command.

Sample Requests

$ nomad operator api -X PUT \
    "/v1/operator/raft/transfer-leadership?address=1.2.3.4:4647"

$ curl --request PUT \
    --header "X-Nomad-Token: ${NOMAD_TOKEN}"
    "https://127.0.0.1:4646/v1/operator/raft/transfer-leadership?address=1.2.3.4:4647"