---
layout: docs
page_title: AWS Key Management Service (KMS) Keyring Configuration
description: |-
  Configure an AWS Key Management Service (KMS) keyring in the `keyring "awskms"` block of a Nomad agent configuration. Configure AWS region, KMS API endpoint, KMA key ID, and AWS authentication. Learn how Nomad supports KMS root key rotation.
---

# AWS Key Management Service (KMS) Keyring Configuration

This page provides reference information for configuring an AWS Key Management
Service (KMS) keyring in the `keyring "awskms"` block of a Nomad agent
configuration. Configure AWS region, KMS API endpoint, KMA key ID, and AWS
authentication. Learn how Nomad supports KMS root key rotation.

The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This
example shows configuring an 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
