61 lines
2.7 KiB
Plaintext
61 lines
2.7 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Key Management
|
|
description: Learn about the key management in Nomad.
|
|
---
|
|
|
|
# Key Management
|
|
|
|
Nomad servers maintain an encryption keyring used to encrypt [Secure
|
|
Variables][] and sign task [workload identities][]. The servers store key
|
|
metadata in raft, but the encryption key material is stored in a separate file
|
|
in the `keystore` subdirectory of the Nomad [data directory][]. These files have
|
|
the extension `.nks.json`.
|
|
|
|
Under normal operations the keyring is entirely managed by Nomad, but this
|
|
section provides administrators additional context around key replication and
|
|
recovery.
|
|
|
|
## Key Rotation
|
|
|
|
Only one key in the keyring is "active" at any given time, and all encryption
|
|
and signing operations happen on the leader. Nomad automatically rotates the
|
|
active encryption key every 30 days. When a key is rotated, the existing keys
|
|
are marked as "inactive" but not deleted, so they can be used for decrypting
|
|
previously encrypted variables and verifying workload identities for existing
|
|
allocations.
|
|
|
|
If you believe key material has been compromised, you can execute [`nomad
|
|
operator keyring secure-variables rotate -full`][]. A new "active" key will be
|
|
created and "inactive" keys will be marked "rekeying". Nomad will asynchronously
|
|
decrypt and re-encrypt all secure variables with the new key. As each key's
|
|
variables are encrypted with the new key, the old key will marked as
|
|
"deprecated".
|
|
|
|
## Key Replication
|
|
|
|
When a leader is elected, it creates the keyring if it does not already
|
|
exist. When a key is added, the metadata will be replicated via raft. Each
|
|
server runs a key replication process that watches for changes to the state
|
|
store and will fetch the key material from the leader asynchronously, falling
|
|
back to retrieving from other servers in the case where a key is written
|
|
immediately before a leader election.
|
|
|
|
## Restoring the Keyring from Backup
|
|
|
|
Key material is never stored in raft. This prevents an attacker with a backup of
|
|
the state store from getting access to encrypted secure variables. It also
|
|
allows the HashiCorp engineering and support organization to safely handle
|
|
cluster snapshots you might provide without exposing any of your keys or secure
|
|
variables.
|
|
|
|
However, this means that to restore a cluster from snapshot you need to also
|
|
provide the keystore directory with the `.nks.json` key files on at least one
|
|
server. Operators should include these files as part of your organization's
|
|
backup and recovery strategy for the cluster.
|
|
|
|
[Secure Variables]: /docs/concepts/secure-variables
|
|
[workload identities]: /docs/concepts/workload-identity
|
|
[data directory]: /docs/configuration#data_dir
|
|
[`nomad operator keyring secure-variables rotate -full`]: /docs/commands/operator/secure-variables/keyring-rotate.mdx
|