keyring Block

The keyring block configures how the Nomad server protects the keyring used for encrypting variables and signing workload identities. By default, Nomad encrypts the key material with a unique key encryption key (KEK) that is not shared between servers, and writes the wrapped key material to disk as described in Key Management. Nomad refers to this as "aead". Using the keyring configuration block, Nomad servers can instead use an external KMS or Vault transit encryption. The encrypted key is stored on disk but is now protected against offline attacks because the KEK is not present in the file.

All keyring blocks require a label for the KMS type. Each external KMS has its own configuration options.

keyring [TYPE] {
  name   = "example"
  active = true
}

The default keyring configuration is as follows:

keyring "aead" {
  active = true
}

keyring Parameters

All keyring blocks support the following parameters.

• name (string: "") - A unique identifier for the keyring block, used to disambiguate when there are multiple blocks of the same type.

• active (bool: false) - Indicates which block to use for encrypting keys. For existing servers, changing which block is active only impacts new keys created by a key rotation. Existing keys are encrypted with the previous active block, so those blocks should not be removed from the configuration until they have been garbage collected and the keys have been removed from the keystore. In Nomad Community Edition, only a single keyring can be active at a time.

High Availabilty

Keyring high availability provides the means to configure multiple active keyring blocks, in order to have resilience against an outage of an external KMS. When there are multiple keyring blocks with active = true, Nomad Enterprise will encrypt each key it creates in all the active KMS providers. On startup, Nomad will try each KMS provider in order until it finds a provider that can decrypt each key.