From 3d06eef65dcd443b8fefc91ebb4eb65d7ff4218f Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Mon, 26 Aug 2024 11:25:26 -0500 Subject: [PATCH] Docs: CE-705 Highlight that user must backup keyring separately --- .../commands/operator/snapshot/restore.mdx | 28 +++++++++------ .../docs/commands/operator/snapshot/save.mdx | 34 ++++++++++++------- 2 files changed, 39 insertions(+), 23 deletions(-) diff --git a/website/content/docs/commands/operator/snapshot/restore.mdx b/website/content/docs/commands/operator/snapshot/restore.mdx index 53ab82520..049282452 100644 --- a/website/content/docs/commands/operator/snapshot/restore.mdx +++ b/website/content/docs/commands/operator/snapshot/restore.mdx @@ -7,21 +7,29 @@ description: | # Command: operator snapshot restore -Restores an atomic, point-in-time snapshot of the state of the Nomad servers -which includes jobs, nodes, allocations, periodic jobs, and ACLs. +The `operator snapshot restore` command restores an atomic, point-in-time +snapshot of the state of the Nomad servers, which includes jobs, nodes, +allocations, periodic jobs, and ACLs. -Restores involve a potentially dangerous low-level Raft operation that is not -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. +Restoration involves a potentially dangerous low-level Raft operation that is +not designed to handle server failures during a restore. This command is +primarily intended for 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 +This command only restores the Raft snapshot, which does not include keyrings. + +If you are recovering a cluster, you also need to restore the keyring onto at +least one server. Refer to the Key Management's [Restoring the +Keyring from Backup][restore the keyring] section for instructions. + + + +If you enabled ACLs, you must supply a management token in order to perform snapshot operations. -To restore a snapshot from the file "backup.snap": +This example srestore a snapshot from the file `backup.snap`. ```shell-session $ nomad operator snapshot restore backup.snap diff --git a/website/content/docs/commands/operator/snapshot/save.mdx b/website/content/docs/commands/operator/snapshot/save.mdx index 9f7a2bfbe..d1e4a4a5e 100644 --- a/website/content/docs/commands/operator/snapshot/save.mdx +++ b/website/content/docs/commands/operator/snapshot/save.mdx @@ -7,28 +7,36 @@ description: | # Command: operator snapshot save -Retrieves an atomic, point-in-time snapshot of the state of the Nomad servers -which includes jobs, nodes, allocations, periodic jobs, and ACLs for [outage -recovery]. +The `operator snapshot save` command retrieves an atomic, point-in-time +snapshot of the state of the Nomad servers, which includes jobs, nodes, +allocations, periodic jobs, and ACLs for [outage recovery]. -If ACLs are enabled, a management token must be supplied in order to perform +If you enabled ACLs, you must supply a management token in order to perform snapshot operations. -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. +This command only saves a Raft snapshot. This snapshot does not include +keyrings. You must back up keyrings separately. + +If you use this snapshot to recover a cluster, you also need to restore the +keyring onto at least one server. Refer to the Key Management's [Restoring the +Keyring from Backup][restore the keyring] section for instructions. -To create a snapshot from the leader server and save it to "backup.snap": +Run the `nomad operator snapshot save` command to create a snapshot from the +leader server. + +This example saves the backup to `backup.snap`. ```shell-session $ nomad operator snapshot save backup.snap ``` -To create a potentially stale snapshot from any available server (useful if no -leader is available): +This example creates a potentially stale snapshot from any available server +and saves it to `backup.snap`. The `-stale` option is useful if no +leader is available. ```shell-session $ nomad operator snapshot save -stale backup.snap @@ -46,10 +54,10 @@ nomad operator snapshot save [options] ## Snapshot Save Options -- `-stale`: The stale argument defaults to "false" which means the leader - provides the result. If the cluster is in an outage state without a leader, you - may need to set `-stale` to "true" to get the configuration from a non-leader - server. +- `-stale`: The stale argument defaults to `false`, which means the leader + provides the result. If the cluster is in an outage state without a leader, + you may need to set `-stale` to `true` to get the configuration from a + non-leader server. [outage recovery]: /nomad/tutorials/manage-clusters/outage-recovery [restore the keyring]: /nomad/docs/operations/key-management#restoring-the-keyring-from-backup