raft
Join a raft cluster
This endpoint joins a new server node to the Raft cluster. When using Shamir
seal, as soon as the Vault server is brought up, this API should be invoked
instead of sys/init
. This API completes in 2 phases. Once this is invoked,
the joining node will receive a challenge from the Raft's leader node. This
challenge can be answered by the joining node only after a successful unseal.
Hence, the joining node should be unsealed using the unseal keys of the Raft's
leader node.
Method | Path |
---|---|
POST | /sys/storage/raft/join |
Parameters
leader_api_addr
(string: <required>)
– Address of the leader node in the Raft cluster to which this node is trying to join.retry
(bool: false)
- Retry joining the Raft cluster in case of failures.leader_ca_cert
(string: "")
- CA certificate used to communicate with Raft's leader node.leader_client_cert
(string: "")
- Client certificate used to communicate with Raft's leader node.leader_client_key
(string: "")
- Client key used to communicate with Raft's leader node.leader_tls_servername
(string: "")
- TLS servername to use when connecting with HTTPS. Should match one of the names in the DNS SANs of the remote server certificate.auto_join
(string: "")
- Defines any cloud auto-join metadata. If supplied, Vault will attempt to automatically discover peers in addition to what can be provided via 'leader_api_addr'.auto_join_scheme
(string: "https")
- URI scheme to be used forauto_join
.auto_join_port
(int: 8200)
- Port to be used forauto_join
.non_voter
(bool: false) (enterprise)
- If set, will make the server not participate in the Raft quorum, and have it only receive the data replication stream. This can be used to add read scalability to a cluster in cases where a high volume of reads to servers are needed. The default is false.
Additionally, the following options are allowed in Vault open-source, but relevant functionality is only supported in Vault Enterprise:
non_voter
(bool: false)
- Joins the node to the cluster in non-voter mode which results in Vault's data being replicated to it, but does not contribute to the quorum count.
Sample payload
Sample request
Note: Unseal the joining node immediately after this API is invoked.
Read raft configuration
This endpoint returns the details of all the nodes in the raft cluster.
Method | Path |
---|---|
GET | /sys/storage/raft/configuration |
Sample request
Sample response
Remove a node from raft cluster
This endpoint removes a node from the raft cluster. An optional dr_operation_token
may be provided if the node is in a DR secondary cluster.
Method | Path |
---|---|
POST | /sys/storage/raft/remove-peer |
Sample payload
Sample request
Take a snapshot of the raft cluster
This endpoint returns a snapshot of the current state of the raft cluster. The
snapshot is returned as binary data and should be redirected to a file.
Unavailable if Raft is used exclusively for ha_storage
.
Method | Path |
---|---|
GET | /sys/storage/raft/snapshot |
Large raft snapshots
Taking and restoring Raft snapshots can exceed Vault's default and recommended
timeout settings. The
VAULT_CLIENT_TIMEOUT
environment variable can
be used to allow for more time to take or restore a snapshot.
Sample request
Restore raft using a snapshot
Installs the provided snapshot, returning the cluster to the state defined in
it. Unavailable if Raft is used exclusively for ha_storage
.
Method | Path |
---|---|
POST | /sys/storage/raft/snapshot |
Large raft snapshots
Taking and restoring Raft snapshots can exceed Vault's default and recommended
timeout settings. The
VAULT_CLIENT_TIMEOUT
environment variable can
be used to allow for more time to take or restore a snapshot.
Sample request
Force restore raft using a snapshot
Installs the provided snapshot, returning the cluster to the state defined in
it. This is same as writing to /sys/storage/raft/snapshot
except that this
bypasses checks ensuring the Autounseal or shamir keys are consistent with the
snapshot data. Unavailable if Raft is used exclusively for ha_storage
.
Method | Path |
---|---|
POST | /sys/storage/raft/snapshot-force |
Sample request
Bootstrap an HA node
When a node uses Raft exclusively for ha_storage
, this endpoint is used to activate
Raft. It is analogous to using sys/init
to initialize storage, in that it
only needs to be done once per cluster, after which vault operator raft join
is used to add more nodes to the Raft cluster.
Method | Path |
---|---|
POST | /sys/storage/raft/bootstrap |
Sample request