HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Nomad
Nomad Home

You are viewing documentation for version v1.8.x. View latest version.

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.

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:

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 documentation.

Nomad needs the following permissions on the KMS key:

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. 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.