Skip to content

Commit

Permalink
docs: add warnings about backing up keyring to snapshot commands (#19400
Browse files Browse the repository at this point in the history
)

The `operator snapshot` commands and agent don't back up Nomad's key
material. Add some warnings about this to places where users might be looking
for information on cluster recovery.

Fixes: #19389
  • Loading branch information
tgross authored Dec 8, 2023
1 parent ad9520c commit e551814
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 5 deletions.
11 changes: 11 additions & 0 deletions website/content/docs/commands/operator/snapshot/agent.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,15 @@ automatic failover. In daemon mode, the agent will also register itself with
Consul as a service, along with health checks that show the agent is alive
and able to take snapshots.

<Warning>

This snapshot agent only saves a Raft snapshot. Key material for the Nomad
keyring is stored on disk and must be saved separately. To use a snapshot saved
by the agent to recover a cluster, you will also need to [restore the keyring][]
onto at least one server.

</Warning>

If ACLs are enabled, a management token must be supplied in order to perform
snapshot operations.

Expand Down Expand Up @@ -155,3 +164,5 @@ Note that despite the AWS references, any S3-compatible endpoint can be specifie
### Google Storage Options

- `-google-bucket`: The bucket to use.

[restore the keyring]: /nomad/docs/operations/key-management#restoring-the-keyring-from-backup
13 changes: 8 additions & 5 deletions website/content/docs/commands/operator/snapshot/save.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,13 @@ recovery].
If ACLs are enabled, a management token must be supplied in order to perform
snapshot operations.

<Warning>

This command only saves a Raft snapshot. If you use this snapshot to recover a
cluster, you will also need to [restore the keyring][] onto at least one server.

</Warning>

To create a snapshot from the leader server and save it to "backup.snap":

```shell-session
Expand All @@ -27,10 +34,6 @@ leader is available):
$ nomad operator snapshot save -stale backup.snap
```

This command only saves a Raft snapshot. If you use this snapshot to recover a
cluster, you will also need to [restore the keyring][] onto at least one server.


## Usage

```plaintext
Expand All @@ -49,4 +52,4 @@ nomad operator snapshot save [options] <file>
server.

[outage recovery]: /nomad/tutorials/manage-clusters/outage-recovery
[restore the keyring]: /nomad/docs/operations/key-management#restoring-the-keyring-from-backu
[restore the keyring]: /nomad/docs/operations/key-management#restoring-the-keyring-from-backup

0 comments on commit e551814

Please sign in to comment.