mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-23 23:51:08 +02:00
d00715d129
* restructure * update command * fixes * fix command flags * revert makefile change * remove tick log
253 lines
6.4 KiB
Plaintext
253 lines
6.4 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: /sys/storage/raft/autopilot - HTTP API
|
|
description: |-
|
|
|
|
The `/sys/storage/raft/autopilot` endpoints are used to manage raft clusters using autopilot with Vault's Integrated Storage backend.
|
|
|
|
---
|
|
|
|
# `/sys/storage/raft/autopilot`
|
|
|
|
@include 'alerts/restricted-root.mdx'
|
|
|
|
The `/sys/storage/raft/autopilot` endpoints are used to manage raft clusters using autopilot
|
|
with Vault's [Integrated Storage backend](/vault/docs/internals/integrated-storage).
|
|
Refer to the [Integrated Storage Autopilot](/vault/tutorials/raft/raft-autopilot) tutorial to learn how to manage raft clusters using autopilot.
|
|
|
|
## Get cluster state
|
|
|
|
This endpoint is used to retrieve the raft cluster state. See the [docs page](/vault/docs/commands/operator/raft#autopilot-state) for a description of the output.
|
|
|
|
| Method | Path |
|
|
| :----- | :---------------------------------- |
|
|
| `GET` | `/sys/storage/raft/autopilot/state` |
|
|
|
|
### Sample request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--header "X-Vault-Token: ..." \
|
|
http://127.0.0.1:8200/v1/sys/storage/raft/autopilot/state
|
|
```
|
|
|
|
### Sample response
|
|
|
|
```json
|
|
{
|
|
"failure_tolerance": 1,
|
|
"healthy": true,
|
|
"leader": "vault_1",
|
|
"servers": {
|
|
"vault_1": {
|
|
"address": "127.0.0.1:8201",
|
|
"healthy": true,
|
|
"id": "vault_1",
|
|
"last_contact": "0s",
|
|
"last_index": 63,
|
|
"last_term": 3,
|
|
"name": "vault_1",
|
|
"node_status": "alive",
|
|
"node_type": "voter",
|
|
"stable_since": "2024-08-29T16:02:45.639829+02:00",
|
|
"status": "leader",
|
|
"version": "1.17.3"
|
|
},
|
|
"vault_2": {
|
|
"address": "127.0.0.1:8203",
|
|
"healthy": true,
|
|
"id": "vault_2",
|
|
"last_contact": "678.62575ms",
|
|
"last_index": 63,
|
|
"last_term": 3,
|
|
"name": "vault_2",
|
|
"node_status": "alive",
|
|
"node_type": "voter",
|
|
"stable_since": "2024-08-29T16:02:47.640976+02:00",
|
|
"status": "voter",
|
|
"version": "1.17.3"
|
|
},
|
|
"vault_3": {
|
|
"address": "127.0.0.1:8205",
|
|
"healthy": true,
|
|
"id": "vault_3",
|
|
"last_contact": "3.969159375s",
|
|
"last_index": 63,
|
|
"last_term": 3,
|
|
"name": "vault_3",
|
|
"node_status": "alive",
|
|
"node_type": "voter",
|
|
"stable_since": "2024-08-29T16:02:49.640905+02:00",
|
|
"status": "voter",
|
|
"version": "1.17.3"
|
|
}
|
|
},
|
|
"voters": [
|
|
"vault_1",
|
|
"vault_2",
|
|
"vault_3"
|
|
]
|
|
}
|
|
```
|
|
The `failure_tolerance` of a cluster is the number of nodes in the cluster that could
|
|
fail gradually without causing an outage.
|
|
|
|
When verifying the health of your cluster, check the following fields of each server:
|
|
- `healthy`: whether Autopilot considers this node healthy or not
|
|
- `status`: the voting status of the node. This will be `voter`, `leader`, or [`non-voter`](/vault/docs/concepts/integrated-storage#non-voting-nodes-enterprise-only)")
|
|
- `last_index`: the index of the last applied Raft log. This should be close to the `last_index` value of the leader.
|
|
- `version`: the version of Vault running on the server
|
|
- `node_type`: the type of node. On CE, this will always be `voter`. See below for an explanation of Enterprise node types.
|
|
|
|
### Enterprise only
|
|
Vault Enterprise will include additional output in its API response to indicate the current state of redundancy zones,
|
|
automated upgrade progress (if any), and optimistic failure tolerance.
|
|
|
|
#### Sample response (Enterprise)
|
|
```json
|
|
{
|
|
"failure_tolerance": 0,
|
|
"healthy": true,
|
|
"leader": "vault_1",
|
|
"optimistic_failure_tolerance": 3,
|
|
"redundancy_zones": {
|
|
"a": {
|
|
"servers": [
|
|
"vault_1",
|
|
"vault_2",
|
|
"vault_5"
|
|
],
|
|
"voters": [
|
|
"vault_1"
|
|
],
|
|
"failure_tolerance": 2
|
|
},
|
|
"b": {
|
|
"servers": [
|
|
"vault_3",
|
|
"vault_4"
|
|
],
|
|
"voters": [
|
|
"vault_3"
|
|
],
|
|
"failure_tolerance": 1
|
|
}
|
|
},
|
|
"upgrade_info": {
|
|
"other_version_non_voters": [
|
|
"vault_2",
|
|
"vault_4"
|
|
],
|
|
"other_version_voters": [
|
|
"vault_1",
|
|
"vault_3"
|
|
],
|
|
"redundancy_zones": {
|
|
"a": {
|
|
"target_version_non_voters": [
|
|
"vault_5"
|
|
],
|
|
"other_version_voters": [
|
|
"vault_1"
|
|
],
|
|
"other_version_non_voters": [
|
|
"vault_2"
|
|
]
|
|
},
|
|
"b": {
|
|
"other_version_voters": [
|
|
"vault_3"
|
|
],
|
|
"other_version_non_voters": [
|
|
"vault_4"
|
|
]
|
|
}
|
|
},
|
|
"status": "await-new-voters",
|
|
"target_version": "1.17.5",
|
|
"target_version_non_voters": [
|
|
"vault_5"
|
|
]
|
|
},
|
|
"voters": [
|
|
"vault_1",
|
|
"vault_3"
|
|
]
|
|
}
|
|
```
|
|
|
|
`optimistic_failure_tolerance` describes the number of healthy active and
|
|
back-up voting servers that can fail gradually without causing an outage.
|
|
|
|
@include 'autopilot/node-types.mdx'
|
|
|
|
## Get configuration
|
|
|
|
This endpoint is used to get the configuration of the autopilot subsystem of Integrated Storage.
|
|
|
|
| Method | Path |
|
|
| :----- | :------------------------------------------ |
|
|
| `GET` | `/sys/storage/raft/autopilot/configuration` |
|
|
|
|
### Sample request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--header "X-Vault-Token: ..." \
|
|
http://127.0.0.1:8200/v1/sys/storage/raft/autopilot/configuration
|
|
```
|
|
|
|
### Sample response
|
|
|
|
```json
|
|
{
|
|
"cleanup_dead_servers": false,
|
|
"dead_server_last_contact_threshold": "24h0m0s",
|
|
"last_contact_threshold": "10s",
|
|
"max_trailing_logs": 1000,
|
|
"min_quorum": 0,
|
|
"server_stabilization_time": "10s",
|
|
"disable_upgrade_migration": true
|
|
}
|
|
```
|
|
|
|
Note that in the above sample response, `disable_upgrade_migration` is an Enterprise-only field.
|
|
|
|
## Set configuration
|
|
|
|
This endpoint is used to modify the configuration of the autopilot subsystem of Integrated Storage.
|
|
|
|
| Method | Path |
|
|
| :----- | :------------------------------------------ |
|
|
| `POST` | `/sys/storage/raft/autopilot/configuration` |
|
|
|
|
### Parameters
|
|
|
|
@include 'autopilot/config.mdx'
|
|
|
|
### Sample request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--header "X-Vault-Token: ..." \
|
|
--request POST \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8200/v1/sys/storage/raft/autopilot/configuration
|
|
```
|
|
|
|
### Sample payload
|
|
|
|
```json
|
|
{
|
|
"cleanup_dead_servers": true,
|
|
"last_contact_threshold": "10s",
|
|
"dead_server_last_contact_threshold": "24h",
|
|
"max_trailing_logs": "1000",
|
|
"min_quorum": "3",
|
|
"server_stabilization_time": "10s",
|
|
"disable_upgrade_migration": true
|
|
}
|
|
```
|
|
|
|
Note that in the above sample payload, `disable_upgrade_migration` is an Enterprise-only field.
|