keyring Block in Agent Configuration

This page provides reference information for configuring keyring protection behavior in the keyring block of a Nomad agent configuration. Enable a keyring and configure a name. Learn how to configure keyring high availability (HA) and migrate keyrings.

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" (authenticated encryption with associated data). Using the keyring configuration block, Nomad servers can instead use an external key management system (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. The keyring block only applies to Nomad servers, not Nomad clients.

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.

Migrating Keyrings

To migrate to a new keyring, add the new keyring block to the servers with active=true, and restart the servers. The server starts using the new keyring wrapper when the current key is rotated either periodically or via the nomad operator root keyring rotate command.

Adding or removing a keyring requires restarting the Nomad server. You should not remove a keyring until all keys it wraps have been garbage collected. You can examine the contents of the keystore directory found in the Nomad server's data directory and compare this against the output of nomad operator root keyring list.

High Availability

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 encrypts each key it creates in all the active KMS providers. On startup, Nomad tries each KMS provider in order until it finds a provider that can decrypt each key.

In this example high availability configuration, both keyring blocks use the "awskms" provider, but each block uses a different KMS key in a different AWS region.

keyring "awskms" {
  active     = true
  name       = "kms-us-east-1"
  region     = "us-east-1"
  kms_key_id = "arn:aws:kms:us-east-1:000000000000:key/7d23633a-4464-11ef-a273-abd12example"
}

keyring "awskms" {
  active     = true
  name       = "kms-us-east-2"
  region     = "us-east-2"
  kms_key_id = "alias/nomad-keyring-us-east-2"
}