Seal High Availability

Seal High Availability is the ability to configure more than one seal in order to have resilience against outage of a seal service or mechanism.

Using Seal HA involves configuring extra seals in Vault's server configuration file and restarting Vault, after having enabled the Seal HA beta feature by setting the environment variable:

VAULT_ENABLE_SEAL_HA_BETA=true

Before using Seal HA, one must have upgraded to Vault 1.15 or higher and started with the environment variable and a single seal.

Adding and Removing Seals

Seal HA adds two new fields to the seal configuration stanza, name, and priority:

seal [TYPE] {
  name = "seal-name"
  priority = "1"
  # ...
}

Name is optional, and if not specified is set to the type of the seal. Names must be unique. If using two seals of the same type name must be specified. Internally, name is used to disambiguate seal wrapped values in some cases, so renaming seals should be avoided if possible.

Priority is mandatory if more than one seal is specified. Priority tells Vault the order in which to try seals during unseal (least priority first), in the case more than one seal can unwrap a seal wrapped value, the order in which to attempt decryption, and which order to attempt to source entropy for entropy augmentation. This can be useful if your seals have different performance or cost characteristics.

All configured, healthy seals are used to seal wrap values. This means that for every write of a seal wrapped value or CSP, an encryption is requested from every configured seal, and the results are stored in the storage entry. When seals are unhealthy, Vault keeps track of values that could not be fully wrapped and will re-wrap them once seals become healthy again. Disabled seals can still be used for decryption of wrapped values, but will be avoided when encrypting values.

When reading a CSP or seal wrapped value, Vault will try to decrypt with the highest priority available seal, and then try other seals on failure.

To add an additional seal, simply add another seal stanza, specifying priority and optionally name, and restart Vault.

To remove a seal, remove the corresponding seal stanza and restart. There must be at least one seal remaining.

It is highly recommended to take a snapshot of your Vault storage before applying any seal configuration change.

Once Vault unseals with the new seal configuration, it will be available to process traffic even as re-wrapping proceeds.

Safety checks

Vault will reject seal configuration changes in the following circumstances, as a safety mechanism:

• The old seal configuration and new seal configuration do not share one seal in common. This is necessary as there would be no seal capable of decrypting CSPs or seal wrapped values previously written.

• Seal re-wrapping is in progress. Vault must be in a clean, fully wrapped state on the previous configuration before attempting a configuration change.

• More than one seal is being added or removed at a time.

Interaction with Shamir Seals

Seal HA is only supported with auto seal mechanisms. To use Seal HA when running a Shamir seal, first use the traditional seal migration mechanism to migrate to an auto seal of your choice. Afterwards you may follow the above instructions to add a second auto seal.

Correspondingly, to migrate back to a shamir seal, first use the above instructions to move to a single auto seal, and use the traditional migration method to migrate back to a Shamir seal.