docs: external KMS configuration

website/content/docs/configuration/keyring/awskms.mdx

@@ -0,0 +1,100 @@
+---
+layout: docs
+page_title: AWS KMS - Keyring - Configuration
+description: |-
+  The AWS KMS keyring configures Nomad to use AWS KMS as the key material
+  wrapping mechanism.
+---
+
+# `awskms` keyring
+
+The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This
+example shows configuring AWS KMS keyring through the Nomad configuration file
+by providing all the required values.
+
+```hcl
+keyring "awskms" {
+  active = true
+  name   = "example"
+
+  # fields specific to awskms
+  region     = "us-east-1"
+  access_key = "AKIAIOSFODNN7EXAMPLE"
+  secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
+  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
+}
+```
+
+## `awskms` parameters
+
+These parameters apply to the `keyring` block in the Nomad configuration file:
+
+- `region` `(string: "us-east-1")`: The AWS region where the encryption key
+  lives. If not provided, may be populated from the `AWS_REGION` or
+  `AWS_DEFAULT_REGION` environment variables, from your `~/.aws/config` file, or
+  from instance metadata.
+
+- `access_key` `(string: <required>)`: The AWS access key ID to use. Alternately
+  specify via the `AWS_ACCESS_KEY_ID` environment variable or as part of the AWS
+  profile from the AWS CLI or instance profile.
+
+- `session_token` `(string: "")`: Specifies the AWS session token. Alternately
+  specify via the environment variable `AWS_SESSION_TOKEN`.
+
+- `secret_key` `(string: <required>)`: The AWS secret access key to
+  use. Alternately specify via the `AWS_SECRET_ACCESS_KEY` environment variable
+  or as part of the AWS profile from the AWS CLI or instance profile.
+
+- `kms_key_id` `(string: <required>)`: The AWS KMS key ID or ARN to use for
+  encryption and decryption. You can alternately use an alias in the format
+  `alias/key-alias-name`.
+
+- `endpoint` `(string: "")`: The KMS API endpoint for AWS KMS
+  requests. Alternately specify via the `AWS_KMS_ENDPOINT` environment
+  variable. This is useful, for example, when connecting to KMS over a [VPC
+  Endpoint][]. If not set, Nomad uses the default API endpoint for your region.
+
+## Authentication
+
+You must provide authentication-related values either as environment variables
+or as configuration parameters.
+
+~> **Note:** Although the configuration file allows you to pass in
+`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as part of the keyring block's
+parameters, we strongly recommended that you set these values via environment
+variables or instance profile.
+
+AWS authentication values:
+
+- `AWS_REGION` or `AWS_DEFAULT_REGION`
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+
+Note: The client uses the official AWS SDK and the specified credentials,
+environment credentials, shared file credentials, or IAM role/ECS task
+credentials in that order, if you do not provide the aforementioned AWS-specific
+values. Refer to the [AWS SDK and Tools standard credentials][aws-std-creds]
+documentation.
+
+Nomad needs the following permissions on the KMS key:
+
+- `kms:Encrypt`
+- `kms:Decrypt`
+- `kms:DescribeKey`
+
+Grant these via IAM permissions on the principal that Nomad uses, on the KMS key
+policy for the KMS key, or via KMS Grants on the key.
+
+## Key rotation
+
+This keyring supports rotating the root keys defined in AWS KMS
+[doc][rotate_docs]. Both automatic rotation and manual rotation is supported for
+KMS since the key information is stored with the encrypted data. Old keys must
+not be disabled or deleted and are used to decrypt older data. Any new or
+updated data is encrypted with the current key defined in the keyring
+configuration or set to current under a key alias.
+
+[VPC Endpoint]: https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html
+[rotate_docs]: https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html
+[aws-std-creds]: https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html

website/content/docs/configuration/keyring/azurekeyvault.mdx

@@ -0,0 +1,92 @@
+---
+layout: docs
+page_title: Azure Key Vault - Keyring - Configuration
+description: >-
+  The Azure Key Vault keyring configures Nomad to use Azure Key Vault as the key material
+  wrapping mechanism.
+---
+
+# `azurekeyvault` keyring
+
+The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This
+example shows configuring Azure Key Vault keyring through the Nomad
+configuration file by providing all the required values.
+
+```hcl
+seal "azurekeyvault" {
+  active = true
+  name   = "example"
+
+  # fields specific to azurekeyvault
+  tenant_id      = "46646709-b63e-4747-be42-516edeaf1e14"
+  client_id      = "03dc33fc-16d9-4b77-8152-3ec568f8af6e"
+  client_secret  = "DUJDS3..."
+  vault_name     = "nomad"
+  key_name       = "nomad_key"
+}
+```
+
+## `azurekeyvault` parameters
+
+These parameters apply to the `keyring` block in the Nomad configuration file:
+
+- `tenant_id` `(string: <required>)`: The tenant id for the Azure Active
+  Directory organization. Alternately specify via the `AZURE_TENANT_ID`
+  environment variable.
+
+- `client_id` `(string: <required or MSI>)`: The client id for credentials to
+  query the Azure APIs. Alternately specify via the `AZURE_CLIENT_ID`
+  environment variable.
+
+- `client_secret` `(string: <required or MSI>)`: The client secret for
+  credentials to query the Azure APIs. Alternately specify via the
+  `AZURE_CLIENT_SECRET` environment variable.
+
+- `environment` `(string: "AZUREPUBLICCLOUD")`: The Azure Cloud environment API
+  endpoints to use. Alternately specify via the `AZURE_ENVIRONMENT` environment
+  variable.
+
+- `vault_name` `(string: <required>)`: The Key Vault vault to use the encryption
+  keys for encryption and decryption.
+
+- `key_name` `(string: <required>)`: The Key Vault key to use for encryption and
+  decryption.
+
+- `resource` `(string: "vault.azure.net")`: The AZ KeyVault resource's DNS
+  Suffix to connect to. Alternately specify via the `AZURE_AD_RESOURCE`
+  environment variable. Needs to be changed to connect to Azure's Managed HSM
+  KeyVault instance type.
+
+## Authentication
+
+You must provide authentication-related values either as environment variables
+or as configuration parameters.
+
+Azure authentication values:
+
+- `AZURE_TENANT_ID`
+- `AZURE_CLIENT_ID`
+- `AZURE_CLIENT_SECRET`
+- `AZURE_ENVIRONMENT`
+- `AZURE_AD_RESOURCE`
+
+~> **Note:** If Nomad is hosted on Azure, Nomad can use Managed Service
+Identities (MSI) to access Azure instead of an environment and shared client id
+and secret. MSI must be [enabled][msi_enabled] on the VMs hosting Nomad. We
+recommend this configuration since MSI prevents your Azure credentials from
+being stored as clear text.
+
+-> **Note:** If you are using a Managed HSM KeyVault, you must specify
+`AZURE_AD_RESOURCE` or the `resource` configuration parameter; usually this
+should point to `managedhsm.azure.net` but could point to other suffixes
+depending on Azure environment.
+
+## Key rotation
+
+This keyring supports rotating keys defined in Azure Key Vault. Key metadata is
+stored with the encrypted data to ensure the correct key is used during
+decryption operations. Set up Azure Key Vault with [key rotation][] using Azure
+Automation Account so Vault recognizes newly rotated keys.
+
+[msi_enabled]: https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/qs-configure-portal-windows-vm
+[key rotation]: https://docs.microsoft.com/en-us/azure/key-vault/key-vault-key-rotation-log-monitoring

website/content/docs/configuration/keyring/gcpckms.mdx

@@ -0,0 +1,92 @@
+---
+layout: docs
+page_title: GCP Cloud KMS - Keyrings - Configuration
+description: >-
+  The GCP Cloud KMS keyring configures Nomad to use GCP Cloud KMS as the keyring
+  wrapping mechanism.
+---
+
+# `gcpckms` keyring
+
+
+The GCP Cloud KMS keyring configures Nomad to use GCP Cloud KMS to wrap its
+keyring. This example shows configuring GCP Cloud KMS keyring through the Nomad
+configuration file by providing all the required values.
+
+```hcl
+keyring "gcpckms" {
+  active = true
+  name   = "example"
+
+  credentials = "/etc/nomad.d/nomad-user-creds.json"
+  project     = "nomad-project"
+  region      = "global"
+  key_ring    = "nomad-keyring"
+  crypto_key  = "nomad-key"
+}
+```
+
+## `gcpckms` parameters
+
+These parameters apply to the `keyring` stanza in the Nomad configuration file:
+
+- `credentials` `(string: <required>)`: The path to the credentials JSON file to
+  use. Alternately specify via the `GOOGLE_CREDENTIALS` or
+  `GOOGLE_APPLICATION_CREDENTIALS` environment variable or set automatically if
+  running under Google Compute Engine.
+
+- `project` `(string: <required>)`: The GCP project ID to use. Alternately
+  specify via the `GOOGLE_PROJECT` environment variable.
+
+- `region` `(string: <required>)`: The GCP region/location where the key ring
+  lives. Alternately specify via the `GOOGLE_REGION` environment variable.
+
+- `key_ring` `(string: <required>)`: The GCP CKMS key ring to use.
+
+- `crypto_key` `(string: <required>)`: The GCP CKMS crypto key to use for
+  encryption and decryption.
+
+## Authentication &amp; permissions
+
+You must provide authentication-related values either as environment
+variables or as configuration parameters.
+
+GCP authentication values:
+
+- `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS`
+- `GOOGLE_PROJECT`
+- `GOOGLE_REGION`
+
+Note: The client uses the official Google SDK and the specified credentials,
+environment credentials, or [application default credentials][] in that order,
+if you do not provide the aforementioned GCP-specific values.
+
+The service account needs the following minimum permissions on the crypto key:
+
+```text
+cloudkms.cryptoKeyVersions.useToEncrypt
+cloudkms.cryptoKeyVersions.useToDecrypt
+cloudkms.cryptoKeys.get
+```
+
+These permissions can be described with the following role:
+
+```text
+roles/cloudkms.cryptoKeyEncrypterDecrypter
+cloudkms.cryptoKeys.get
+```
+
+Use `cloudkms.cryptoKeys.get` permission for retrieving metadata information of
+keys from CloudKMS within this engine initialization process.
+
+## Key rotation
+
+This keyring supports rotating keys defined in Google Cloud KMS
+[doc][rotating_keys]. Both scheduled rotation and manual rotation is supported
+for CKMS since the key information. Old keys version must not be disabled or
+deleted and are used to decrypt older data. Any new or updated data is encrypted
+with the primary key version.
+
+
+[application default credentials]: https://developers.google.com/identity/protocols/application-default-credentials
+[rotating_keys]: https://cloud.google.com/kms/docs/rotating-keys

website/content/docs/configuration/keyring/index.mdx

@@ -0,0 +1,107 @@
+---
+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