267 lines
8.1 KiB
Plaintext
267 lines
8.1 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: /sys/storage/raft/snapshot-auto - HTTP API
|
||
description: |-
|
||
|
||
The `/sys/storage/raft/snapshot-auto` endpoints are used to manage automated
|
||
snapshots with Vault's Raft storage backend.
|
||
|
||
This is an Enterprise-only feature.
|
||
---
|
||
|
||
## Create/update an automated snapshots config
|
||
|
||
-> **Note**: This feature requires [Vault Enterprise](https://www.hashicorp.com/products/vault/)
|
||
|
||
**This endpoint requires sudo capability.**
|
||
|
||
This endpoint creates or updates a named configuration. Each configuration
|
||
has an interval controlling how often snapshots are taken, a destination
|
||
where the snapshots are written, as well as a retention policy governing when
|
||
older snapshots get deleted.
|
||
|
||
Note that for cloud storage types, you can either provide credentials explicitly
|
||
using the parameters below, or for GCP and AWS you can omit them and rely on the
|
||
other mechanisms the cloud provider's SDK allows for authenticating, e.g.
|
||
environment variables or files on disk in predefined locations.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------------------------------------- |
|
||
| `POST` | `/sys/storage/raft/snapshot-auto/config/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Name of the configuration to modify.
|
||
|
||
- `interval` `(integer or string: <required>)` - Time between snapshots. This
|
||
can be either an integer number of seconds, or a Go duration format string (e.g. 24h)
|
||
|
||
- `retain` `(integer: 1)` - How many snapshots are to be kept; when writing a
|
||
snapshot, if there are more snapshots already stored than this number, the
|
||
oldest ones will be deleted.
|
||
|
||
- `path_prefix` `(string: <required>)` - For `storage_type=local`, the directory to
|
||
write the snapshots in. For cloud storage types, the bucket prefix to use.
|
||
Types `azure-blob` and `google-gcs` require a trailing `/` (slash).
|
||
Types `local` and `aws-s3` the trailing `/` is optional.
|
||
|
||
- `file_prefix` `(string: "vault-snapshot")` - Within the directory or bucket
|
||
prefix given by `path_prefix`, the file or object name of snapshot files
|
||
will start with this string.
|
||
|
||
- `storage_type` `(string: <required>)` - One of "local", "azure-blob", "aws-s3",
|
||
or "google-gcs". The remaining parameters described below are all specific to
|
||
the selected `storage_type` and prefixed accordingly.
|
||
|
||
#### storage_type=local
|
||
|
||
- `local_max_space` `(integer: <required>)` - For `storage_type=local`, the maximum
|
||
space, in bytes, to use for snapshots. Snapshot attempts will fail if there is not enough
|
||
space left in this allowance.
|
||
|
||
#### storage_type=aws-s3
|
||
|
||
- `aws_s3_bucket` `(string: <required>)` - S3 bucket to write snapshots to.
|
||
|
||
- `aws_s3_region` `(string: <required>)` - AWS region bucket is in.
|
||
|
||
- `aws_access_key_id` `(string)` - AWS access key ID.
|
||
|
||
- `aws_secret_access_key` `(string)` - AWS secret access key.
|
||
|
||
- `aws_session_token` `(string)` - AWS session token.
|
||
|
||
- `aws_s3_endpoint` `(string)` - AWS endpoint. This is typically only set when
|
||
using a non-AWS S3 implementation like Minio.
|
||
|
||
- `aws_s3_disable_tls` `(boolean)` - Disable TLS for the S3 endpoint. This
|
||
should only be used for testing purposes, typically in conjunction with
|
||
`aws_s3_endpoint`.
|
||
|
||
- `aws_s3_force_path_style` `(boolean)` - Use the endpoint/bucket URL style
|
||
instead of bucket.endpoint. May be needed when setting `aws_s3_endpoint`.
|
||
|
||
- `aws_s3_enable_kms` `(boolean)` - Use KMS to encrypt bucket contents.
|
||
|
||
- `aws_s3_server_side_encryption` `(boolean)` - Use AES256 to encrypt bucket contents. Cannot use with `aws_s3_enable_kms` parameter.
|
||
|
||
- `aws_s3_kms_key` `(string)` - Use named KMS key, when `aws_s3_enable_kms=true`
|
||
|
||
#### storage_type=google-gcs
|
||
|
||
- `google_gcs_bucket` `(string: <required>)` GCS bucket to write snapshots to.
|
||
|
||
- `google_service_account_key` `(string)` - Google service account key in JSON format. Depending
|
||
on how the API is invoked, this may be need to be JSON-escaped, e.g. for newlines and double quotes.
|
||
The raw value looks like this:
|
||
|
||
```json
|
||
{
|
||
"type": "service_account",
|
||
"project_id": "project-id",
|
||
"private_key_id": "key-id",
|
||
"private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQ ... /WZs=\n-----END RSA PRIVATE KEY-----\n",
|
||
"client_email": "service-account-email",
|
||
"client_id": "client-id",
|
||
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
|
||
"token_uri": "https://accounts.google.com/o/oauth2/token",
|
||
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
|
||
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email"
|
||
}
|
||
```
|
||
|
||
- `google_endpoint` `(string)` - GCS endpoint. This is typically only set when
|
||
using a non-Google GCS implementation like fake-gcs-server.
|
||
|
||
- `google_disable_tls` `(boolean)` - Disable TLS for the GCS endpoint. This
|
||
should only be used for testing purposes, typically in conjunction with
|
||
`google_endpoint`.
|
||
|
||
#### storage_type=azure-blob
|
||
|
||
- `azure_container_name` `(string: <required>)` - Azure container name to write
|
||
snapshots to.
|
||
|
||
- `azure_account_name` `(string)` - Azure account name.
|
||
|
||
- `azure_account_key` `(string)` - Azure account key.
|
||
|
||
- `azure_blob_environment` `(string)` - Azure blob environment.
|
||
|
||
- `azure_endpoint` `(string)` - Azure blob storage endpoint. This is typically
|
||
only set when using a non-Azure implementation like Azurite.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"interval": "24h",
|
||
"retain": 7,
|
||
"path_prefix": "/opt/vault/snapshots/",
|
||
"storage_type": "local",
|
||
"local_max_space": 10000000
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/config/config1
|
||
```
|
||
|
||
## List automated snapshots configs
|
||
|
||
**This endpoint requires sudo capability.**
|
||
|
||
This endpoint lists named configurations.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------------------------------- |
|
||
| `LIST` | `/sys/storage/raft/snapshot-auto/config` |
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/config
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keys": ["config1"]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Read automated snapshots config
|
||
|
||
**This endpoint requires sudo capability.**
|
||
|
||
This endpoint reads a named configuration.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------------------------------------- |
|
||
| `GET` | `/sys/storage/raft/snapshot-auto/config/:name` |
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/config/config1
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"file_prefix": "vault-snapshot",
|
||
"interval": 86400,
|
||
"local_max_space": 10000000,
|
||
"path_prefix": "/opt/vault/snapshots/",
|
||
"retain": 7,
|
||
"storage_type": "local"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Delete automated snapshots config
|
||
|
||
**This endpoint requires sudo capability.**
|
||
|
||
This endpoint deletes a named configuration.
|
||
|
||
| Method | Path |
|
||
| :------- | :--------------------------------------------- |
|
||
| `DELETE` | `/sys/storage/raft/snapshot-auto/config/:name` |
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/config/config1
|
||
```
|
||
|
||
## Read automated snapshots status
|
||
|
||
This endpoint returns the status of a named configuration.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------------------------------------- |
|
||
| `GET` | `/sys/storage/raft/snapshot-auto/status/:name` |
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-auto/status/config1
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"last_snapshot_end": "2020-10-28T11:17:21-04:00",
|
||
"last_snapshot_error": "",
|
||
"last_snapshot_start": "2020-10-28T11:17:21-04:00",
|
||
"last_snapshot_url": "file:///opt/vault/snapshots/vault-snapshot-1603898241699731000.snap",
|
||
"snapshot_start": "2020-10-28T11:17:21-04:00",
|
||
"snapshot_url": "file:///opt/vault/snapshots/vault-snapshot-1603898241699731000.snap"
|
||
}
|
||
}
|
||
```
|