Update the seal migration docs (hashicorp#9432)

* update the seal migration docs * Update website/pages/docs/concepts/seal.mdx Co-authored-by: Alexander Bezobchuk <[email protected]> Co-authored-by: Alexander Bezobchuk <[email protected]>
qk4l · Jul 15, 2020 · b557b76 · b557b76
1 parent f709eac
commit b557b76
Showing 1 changed file with 39 additions and 28 deletions.
diff --git a/website/pages/docs/concepts/seal.mdx b/website/pages/docs/concepts/seal.mdx
@@ -141,37 +141,48 @@ These steps are common for seal migrations between any supported kinds and for
 any storage backend.
 
 1. Take a standby node down and update the [seal
-   configuration](/docs/configuration/seal). If the migration is from Shamir seal
-   to KMS seal, add the desired new KMS seal block to the config. If the migration
-   is from KMS seal to Shamir seal, add `disabled = "true"` to the old seal block.
-   If the migration is from KMS seal to another KMS seal, add `disabled = "true"`
-   to the old seal block and add the desired new KMS seal block. Now, bring the
-   standby node back up and run the unseal command on each by supplying the
-   `-migrate` flag. Supply Shamir unseal keys if old seal was Shamir, which will be
-   migrated as the recovery keys for the KMS seal. Supply recovery keys if the old
-   seal is one of KMS seals, which will be migrated as the recovery keys of the new
-   KMS seal or as Shamir unseal keys if the new seal is Shamir.
-
-2. Perform step 1 for all the standby nodes, one at a time. It is necessary to
+   configuration](/docs/configuration/seal). 
+
+    * If the migration is from Shamir seal to KMS seal, add the desired new KMS
+      seal block to the configuration. 
+    * If the migration is from KMS seal to Shamir seal, add `disabled = "true"`
+      to the old seal block.
+    * If the migration is from KMS seal to another KMS seal, add `disabled =
+      "true"` to the old seal block and add the desired new KMS seal block. 
+
+    Now, bring the standby node back up and run the unseal command on each key, by
+    supplying the `-migrate` flag. 
+
+    * Supply Shamir unseal keys if the old seal was Shamir, which will be migrated
+      as the recovery keys for the KMS seal. 
+    * Supply recovery keys if the old seal is one of KMS seals, which will be
+      migrated as the recovery keys of the new KMS seal, or as Shamir unseal
+      keys if the new seal is Shamir.
+
+1. Perform step 1 for all the standby nodes, one at a time. It is necessary to
    bring back the downed standby node before moving on to the other standby nodes,
-   specifically when integrated storage is in use for it helps to retain the
+   specifically when Integrated Storage is in use for it helps to retain the
    quorum.
 
-3. Stop the active node. One of the standby nodes will become the active node
-   and perform the migration. When using Integrated Storage, ensure that quorum is
-   reached and a leader is elected. Monitor the server log in the active node to
-   witness the completion of the seal migration process. Wait for a little while
-   for the migration information to replicate to all the nodes in case of
-   Integrated Storage. In enterprise Vault, switching a KMS seal implies that the
-   seal wrapped storage entries get re-wrapped. Monitor the log and wait until this
-   process is complete (look for `seal re-wrap completed`).
-
-4. Seal migration is now completed. Update the config of the old active node
-   (that is still down) to use the new seal blocks (completely unaware of the old
-   seal type) and bring it up. It will be auto-unsealed if the new seal is one of the
-   KMS seals or will require unseal keys if the new seal is Shamir.
-
-5. At this point, config files of all the nodes can be updated to only have the
+1. [Step down](https://www.vaultproject.io/docs/commands/operator/step-down) the
+   active node. One of the standby nodes will become the new active node.
+   When using Integrated Storage, ensure that quorum is reached and a leader is
+   elected. 
+
+1. The new active node will perform the migration. Monitor the server log in
+   the active node to witness the completion of the seal migration process.
+   Wait for a little while for the migration information to replicate to all the
+   nodes in case of Integrated Storage. In enterprise Vault, switching a KMS seal
+   implies that the seal wrapped storage entries get re-wrapped. Monitor the log
+   and wait until this process is complete (look for `seal re-wrap completed`).
+
+1. Seal migration is now completed. Take down the old active node, update its
+   configuration of the old active node to use the new seal blocks (completely
+   unaware of the old seal type) and bring it back up. It will be auto-unsealed if
+   the new seal is one of the KMS seals, or will require unseal keys if the new
+   seal is Shamir.
+
+1. At this point, configuration files of all the nodes can be updated to only have the
    new seal information. Standby nodes can be restarted right away and the active
    node can be restarted upon a leadership change.