diff --git a/website/pages/docs/concepts/seal.mdx b/website/pages/docs/concepts/seal.mdx index 8cc913ab9..fb49245ad 100644 --- 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. + configuration](/docs/configuration/seal). -2. Perform step 1 for all the standby nodes, one at a time. It is necessary to + * 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`). +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. -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. +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`). -5. At this point, config files of all the nodes can be updated to only have the +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.