github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/source/docs/agent/http/snapshot.html.markdown

3.9 KiB
Raw Blame History

layout page_title sidebar_current description
docs Consul Snapshots (HTTP) docs-agent-http-snapshots The Snapshot endpoints are used to save and restore Consul's server state for disaster recovery.

Snapshot HTTP Endpoint

The Snapshot endpoints are used to save and restore the state of the Consul servers for disaster recovery. Snapshots include all state managed by Consul's Raft consensus protocol, including:

  • Key/Value Entries
  • Service Catalog
  • Prepared Queries
  • Sessions
  • ACLs

Available in Consul 0.7.1 and later, these endpoints allow for atomic, point-in-time snapshots of the above data in a format that can be saved externally. Snapshots can then be used to restore the server state into a fresh cluster of Consul servers in the event of a disaster.

The following endpoints are supported:

These endpoints do not support blocking queries. Saving snapshots uses the consistent mode by default and stale mode is supported.

The endpoints support the use of ACL Tokens. Because snapshots contain all server state, including ACLs, a management token is required to perform snapshot operations is ACLs are enabled.

/v1/snapshot

The snapshot endpoint supports the GET and PUT methods.

GET Method

When using the GET method, Consul will perform an atomic, point-in-time snapshot of the Consul server state.

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 Consul 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 Consul and not intended to be used other than for restore operations. In particular, the archives are not designed to be modified before a restore.

By default, the datacenter of the agent is queried; however, the dc can be provided using the ?dc= query parameter.

By default, snapshots use consistent mode which means the request is internally forwarded to the cluster leader, and leadership is checked before performing the snapshot. If stale is specified using the ?stale query parameter, then any server can handle the request and the results may be arbitrarily stale. To support bounding the acceptable staleness of snapshots, responses provide the X-Consul-LastContact header containing the time in milliseconds that a server was last contacted by the leader node. The X-Consul-KnownLeader header also indicates if there is a known leader. These can be used by clients to gauge the staleness of a snapshot and take appropriate action. The stale mode is particularly useful from taking a snapshot of a cluster in a failed state with no current leader.

If ACLs are enabled, the client will need to supply an ACL Token with management privileges.

The return code is 200 on success, and the snapshot will be returned in the body as a gzipped tar archive. In addition to the stale-related headers described above, the X-Consul-Index header will also be set to the index at which the snapshot took place.

PUT Method

When using the PUT method, Consul will atomically restore a point-in-time snapshot of the Consul 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 Consul servers.

By default, the datacenter of the agent is targeted; however, the dc can be provided using the ?dc= query parameter.

If ACLs are enabled, the client will need to supply an ACL Token with management privileges.

The body of the request should be a snapshot archive returned from a previous call to the GET method.

The return code is 200 on success.