Skip to content

Commit

Permalink
docs: add notes about keyring to snapshot restore (#16663) (#16687)
Browse files Browse the repository at this point in the history
When cluster administrators restore from Raft snapshot, they also need to ensure the
keyring is in place. For on-prem users doing in-place upgrades this is less of a
concern but for typical cloud workflows where the whole host is replaced, it's
an important warning (at least until #14852 has been implemented).

Co-authored-by: Tim Gross <tgross@hashicorp.com>
  • Loading branch information
hc-github-team-nomad-core and tgross committed Mar 28, 2023
1 parent 3299d83 commit 039edef
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 6 deletions.
7 changes: 6 additions & 1 deletion website/content/docs/commands/operator/snapshot/restore.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ designed to handle server failures during a restore. This command is primarily
intended to be used when recovering from a disaster, restoring into a fresh
cluster of Nomad servers.

This command only restores the Raft snapshot. If you are recovering a cluster,
you will also need to [restore the keyring][] onto at least one server.

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

Expand All @@ -34,4 +37,6 @@ nomad operator snapshot restore [options] <file>

@include 'general_options_no_namespace.mdx'

[outage recovery]: https://learn.hashicorp.com/tutorials/nomad/outage-recovery

[outage recovery]: /nomad/tutorials/manage-clusters/outage-recovery
[restore the keyring]: /nomad/docs/operations/key-management#restoring-the-keyring-from-backup
7 changes: 6 additions & 1 deletion website/content/docs/commands/operator/snapshot/save.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@ 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 @@ -44,4 +48,5 @@ nomad operator snapshot save [options] <file>
may need to set `-stale` to "true" to get the configuration from a non-leader
server.

[outage recovery]: https://learn.hashicorp.com/tutorials/nomad/outage-recovery
[outage recovery]: /nomad/tutorials/manage-clusters/outage-recovery
[restore the keyring]: /nomad/docs/operations/key-management#restoring-the-keyring-from-backu
13 changes: 9 additions & 4 deletions website/content/docs/operations/key-management.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,12 @@ key files are needed to recover the cluster. Operators should include these
files as part of your organization's backup and recovery strategy for the
cluster.

[variables]: /docs/concepts/variables
[workload identities]: /docs/concepts/workload-identity
[data directory]: /docs/configuration#data_dir
[`nomad operator root keyring rotate -full`]: /docs/commands/operator/root/keyring-rotate
If you are recovering a Raft snapshot onto a new cluster without running
workloads, you can skip restoring the keyring and run [`nomad operator root
keyring rotate`][] once the servers have joined.

[variables]: /nomad/docs/concepts/variables
[workload identities]: /nomad/docs/concepts/workload-identity
[data directory]: /nomad/docs/configuration#data_dir
[`nomad operator root keyring rotate -full`]: /nomad/docs/commands/operator/root/keyring-rotate
[`nomad operator root keyring rotate`]: /nomad/docs/commands/operator/root/keyring-rotate

0 comments on commit 039edef

Please sign in to comment.