mirror of
https://github.com/kemko/nomad.git
synced 2026-01-07 19:05:42 +03:00
0f4014b4a9
In #23580 we're implementing support for encrypting Nomad's key material with external KMS providers or Vault Transit. This changeset breaks out the documentation from that PR to keep the review manageable and present it to a wider set of reviewers. Ref: https://hashicorp.atlassian.net/browse/NET-10334 Ref: https://github.com/hashicorp/nomad/issues/14852 Ref: https://github.com/hashicorp/nomad/pull/23580
108 lines
4.0 KiB
Plaintext
108 lines
4.0 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: keyring Block - Agent Configuration
|
|
description: >-
|
|
The "keyring" block configures the Nomad servers keyring decryption behavior.
|
|
---
|
|
|
|
# `keyring` Block
|
|
|
|
<Placement groups={['keyring']} />
|
|
|
|
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.
|
|
|
|
```hcl
|
|
keyring [TYPE] {
|
|
name = "example"
|
|
active = true
|
|
}
|
|
```
|
|
|
|
The default `keyring` configuration is as follows:
|
|
|
|
```hcl
|
|
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`][keyring_rotate_cmd] 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`][keyring_list_cmd].
|
|
|
|
## High Availability
|
|
|
|
<EnterpriseAlert>
|
|
This functionality only exists in Nomad Enterprise.
|
|
</EnterpriseAlert>
|
|
|
|
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.
|
|
|
|
```hcl
|
|
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"
|
|
}
|
|
```
|
|
|
|
[variables]: /nomad/docs/concepts/variables
|
|
[workload identities]: /nomad/docs/concepts/workload-identity
|
|
[Key Management]: /nomad/docs/operations/key-management
|
|
[key rotation]: /nomad/docs/operations/key-management#key-rotation
|
|
[keyring_rotate_cmd]: /nomad/docs/commands/operator/root/keyring-rotate
|
|
[keyring_list_cmd]: /nomad/docs/commands/operator/root/keyring-list
|