mirror of
https://github.com/kemko/nomad.git
synced 2026-01-06 18:35:44 +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
101 lines
3.8 KiB
Plaintext
101 lines
3.8 KiB
Plaintext
---
|
|
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
|