HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Boundary
Boundary Home

awskms

The AWS KMS configures Boundary to use AWS KMS for key management.

awskms example

This example shows configuring AWS KMS through the Boundary configuration file by providing all the required values:

kms "awskms" {
  purpose    = "root"
  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 kms stanza in the Boundary configuration file:

  • purpose - Purpose of this KMS, acceptable values are: worker-auth, worker-auth-storage, root, previous-root, recovery, bsr, or config.

    To enable session recording, you must configure the bsr value for the purpose.

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

  • kms_key_id (string: <required>): The AWS KMS key ID to use for encryption and decryption. May also be specified by the AWSKMS_WRAPPER_KEY_ID environment variable.

  • access_key (string: ""): The AWS access key ID to use. May also be specified by 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. This can also be provided via the environment variable AWS_SESSION_TOKEN.

  • secret_key (string: ""): The AWS secret access key to use. May also be specified by the AWS_SECRET_ACCESS_KEY environment variable or as part of the AWS profile from the AWS CLI or instance profile.

  • shared_creds_filename (string: ""): (Boundary 0.5.1+) If set, the file name to read as a shared credentials file.

  • shared_creds_profile (string: ""): (Boundary 0.5.1+) If set, the profile to use from the shared credentials file. If not set, will use the AWS_PROFILE env var, or if that is not set, "default".

  • role_arn (string: ""): (Boundary 0.5.1+) If this and web_identity_token_file are set, the role ARN to use when using a web identity role provider with STS.

  • web_identity_token_file (string: ""): (Boundary 0.5.1+) If this and role_arn are set, the token file to use when using a web identity role provider with STS.

  • role_session_name (string: ""): (Boundary 0.5.1+) If using the web identity role provider, the role session to use.

  • endpoint (string: ""): The KMS API endpoint to be used to make AWS KMS requests. May also be specified by the AWS_KMS_ENDPOINT environment variable. This is useful, for example, when connecting to KMS over a VPC Endpoint. If not set, Boundary will use the default API endpoint for your region.

Authentication

Authentication-related values must be provided, 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 KMS's parameters, it is strongly recommended to set these values via environment variables.

AWS authentication values:

Note: The client uses the official AWS SDK and will use the specified credentials, environment credentials, shared file credentials, or IAM role/ECS task credentials in that order, if the above AWS specific values are not provided.

Boundary needs the following permissions on the KMS key:

These can be granted via IAM permissions on the principal that Boundary uses, on the KMS key policy for the KMS key, or via KMS Grants on the key.

Key rotation

This KMS supports rotating the master 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 will be encrypted with the current key defined in the KMS configuration or set to current under a key alias.

Edit this page on GitHub