86 lines
2.8 KiB
Plaintext
86 lines
2.8 KiB
Plaintext
|
---
|
||
|
|
layout: api
|
||
|
|
page_title: Snapshot - Operator - HTTP API
|
||
|
|
description: |-
|
||
|
|
The /operator/snapshot endpoints save and restore Nomad's server state for disaster recovery.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Snapshot Operator HTTP API
|
||
|
|
|
||
|
|
## Generate Snapshot
|
||
|
|
|
||
|
|
This endpoint generates and returns an atomic, point-in-time snapshot of the
|
||
|
|
Nomad server state for disaster recovery. Snapshots include all state managed by Nomad's
|
||
|
|
Raft [consensus protocol](/docs/internals/consensus).
|
||
|
|
|
||
|
|
Snapshots are exposed as gzipped tar archives which internally contain the Raft
|
||
|
|
metadata required to restore, as well as a binary serialized version of the
|
||
|
|
Nomad server state. The contents are covered internally by SHA-256 hashes.
|
||
|
|
These hashes are verified during snapshot restore operations. The structure of
|
||
|
|
the archive is internal to Nomad and not intended to be used other than for
|
||
|
|
restore operations. The archives are not designed to be modified before a
|
||
|
|
restore.
|
||
|
|
|
||
|
|
| Method | Path | Produces |
|
||
|
|
| :----- | :---------------------- | ------------------------ |
|
||
|
|
| `GET` | `/v1/operator/snapshot` | `200 application/x-gzip` |
|
||
|
|
|
||
|
|
The table below shows this endpoint's support for
|
||
|
|
[blocking queries](/api-docs#blocking-queries) and
|
||
|
|
[required ACLs](/api-docs#acls).
|
||
|
|
|
||
|
|
| Blocking Queries | ACL Required |
|
||
|
|
| ---------------- | ------------ |
|
||
|
|
| `NO` | `management` |
|
||
|
|
|
||
|
|
### Parameters
|
||
|
|
|
||
|
|
- `stale` - Specifies if the cluster should respond without an active leader.
|
||
|
|
This is specified as a query string parameter.
|
||
|
|
|
||
|
|
### Sample Request
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ curl \
|
||
|
|
-o snapshot.tgz \
|
||
|
|
http://127.0.0.1:4646/v1/operator/snapshot
|
||
|
|
```
|
||
|
|
|
||
|
|
The above example results in a tarball named `snapshot.tgz` in the current working directory.
|
||
|
|
|
||
|
|
## Restore Snapshot
|
||
|
|
|
||
|
|
This endpoint restores a point-in-time snapshot of the Nomad server state.
|
||
|
|
|
||
|
|
Restores involve a potentially dangerous low-level Raft operation that is not
|
||
|
|
designed to handle server failures during a restore. This operation is primarily
|
||
|
|
intended to be used when recovering from a disaster, restoring into a fresh
|
||
|
|
cluster of Nomad servers.
|
||
|
|
|
||
|
|
The body of the request should be a snapshot archive returned from a previous
|
||
|
|
call to the `GET` method.
|
||
|
|
|
||
|
|
| Method | Path | Produces |
|
||
|
|
| :----- | :---------------------- | ----------------------------- |
|
||
|
|
| `PUT` | `/v1/operator/snapshot` | `200 text/plain (empty body)` |
|
||
|
|
|
||
|
|
The table below shows this endpoint's support for
|
||
|
|
[blocking queries](/api-docs#blocking-queries) and
|
||
|
|
[required ACLs](/api-docs#acls).
|
||
|
|
|
||
|
|
| Blocking Queries | ACL Required |
|
||
|
|
| ---------------- | ------------ |
|
||
|
|
| `NO` | `management` |
|
||
|
|
|
||
|
|
### Sample Request
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ curl \
|
||
|
|
--request PUT \
|
||
|
|
--data-binary @snapshot.tgz \
|
||
|
|
http://127.0.0.1:4646/v1/operator/snapshot
|
||
|
|
```
|
||
|
|
|
||
|
|
~> Some tools default to www/encoded uploads. Nomad expects the snapshot to be
|
||
|
|
in pure binary form.
|