> ## Documentation Index
> Fetch the complete documentation index at: https://www.ravion.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS KMS Key

> Creates a regional symmetric AWS KMS encryption key and stable alias.

**Type:** `rvn-aws-kms` · **Latest version:** `0.2.0`

## Readme

Creates a regional symmetric AWS KMS encryption key and stable alias.

### Overview

Use this module to create one customer-managed key for application data, secrets, storage, and envelope encryption. The key uses the standard AWS KMS symmetric encryption configuration and receives a stable alias derived from the key name.

The module creates a key policy that preserves account-root IAM administration and can grant encryption access directly to selected IAM principals. The key can be created before its consumers because the key user list may be empty.

### Use cases

| Scenario | Benefit |
| - | - |
| Application data encryption | Encrypt application data directly or through envelope encryption. |
| AWS service encryption | Supply the key ARN to services that support customer-managed KMS keys. |
| Secrets and credentials | Encrypt sensitive values with a key whose access policy is managed independently. |
| Data key generation | Allow workloads to generate data keys while keeping the root key material inside KMS. |

### Encryption defaults

The standard form creates a regional `SYMMETRIC_DEFAULT` key with `ENCRYPT_DECRYPT` usage. Annual automatic rotation is enabled, and the deletion waiting period is 30 days. The alias defaults to `alias/<key name>`, and the generated key description also uses the key name.

Specialized settings such as asymmetric keys, signing, HMAC, key agreement, custom aliases, multi-Region keys, key administrators, signers, public key readers, rotation changes, and shorter deletion windows remain available through Advanced Terraform variables.

### Key access

Key user principal ARNs grants the selected account roots, IAM roles, or IAM users permission to encrypt, decrypt, re-encrypt, generate data keys, and describe the key. Keep the list as narrow as possible.

The account root principal remains in the key policy with `kms:*`, following the AWS pattern that allows IAM policies in the account to delegate administration. A principal may require both a key policy grant and an IAM identity policy, depending on how access is managed in the account.

### Configuration

| Setting | Required | Default | Notes |
| - | - | - | - |
| AWS account | Yes | None | AWS account where the KMS key is created. |
| Region | Yes | None | AWS Region where the key is created. |
| Key name | Yes | Project, environment, and module given IDs | Used for the alias, generated description, and tags. |
| Key user principal ARNs | No | Empty list | Principals granted encryption and data-key operations. |
| Tags | No | Standard Ravion tags | Additional tags merged with Ravion ownership and identity tags. |
| Terraform execution environment | No | None | Optional runner environment override. |
| OpenTofu version override | No | Environment default | Optional OpenTofu version override. |
| Ravion Terraform workspace name | No | Generated from project, environment, module, and stack IDs | Backend workspace override. |
| Advanced Terraform variables | No | Empty object | Escape hatch for one-off Terraform variable overrides. |

### Design decisions

The standard form deliberately targets regional symmetric encryption, which covers the common customer-managed key use case without exposing uncommon cryptographic or lifecycle controls. Advanced Terraform variables remain available for exceptional requirements.

The module always creates an alias so consumers can use a stable, readable identifier. Key name, AWS account, and Region are immutable in Ravion because changing them alters key identity or deployment target.

Ravion adds standard tags for ownership and traceability. User-provided Tags are merged on top for team, cost, or environment metadata.

### Learn more

* [AWS KMS concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html)
* [AWS KMS key policies](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)
* [AWS KMS key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)
* [Source module](https://github.com/ravionhq/modules/tree/rvn-aws-kms@0.2.0/security/kms)

## Inputs reference

All inputs for `rvn-aws-kms` version `0.2.0`. Use the `name` shown for each field as the input key in module config.

### AWS account & region

<ResponseField name="aws_account_id" type="string" required>
  **AWS account.**

  * Immutable after creation
</ResponseField>

<ResponseField name="aws_region" type="string" required>
  **Region.**

  * Immutable after creation
</ResponseField>

### KMS key

<ResponseField name="name" type="string" required>
  **Key name.** Name used for the key's default alias, description, and tags.

  * Default: `<<project.given_id>>-<<environment.given_id>>-<<module.given_id>>`
  * Immutable after creation
  * Pattern: `^[A-Za-z0-9/_-]{1,64}$` — 1-64 letters, numbers, slashes, underscores, or hyphens.
</ResponseField>

### Key access

<ResponseField name="key_user_role_arns" type="string_array">
  **Key user principal ARNs.** IAM principals allowed to encrypt, decrypt, re-encrypt, generate data keys, and describe the key.

  * Default: `[]`
  * Pattern: `^arn:aws(-us-gov|-cn|-iso|-iso-b|-iso-e|-iso-f)?:iam::[0-9]{12}:(root|(role|user)/[!-~]*[A-Za-z0-9+=,.@_-])$` — Invalid IAM principal ARN. Use an account root, role, or user ARN with a 12-digit account ID.
</ResponseField>

### Misc

<ResponseField name="tags" type="keyvalue">
  **Tags.** A map of tags to assign to all resources. Default tags are `Owner`, `ProjectGivenId`, `EnvironmentGivenId`, `ModuleGivenId`, `ModuleId`
</ResponseField>

### Terraform settings

<ResponseField name="opentofu_version" type="string">
  **OpenTofu version override.** Override the environment's default version for this module
</ResponseField>

<ResponseField name="ravion_state_backend_workspace" type="string">
  **Ravion Terraform workspace name.** Override Terraform state backend workspace name. Defaults to project + environment + module given ids.

  * Immutable after creation
</ResponseField>

<ResponseField name="terraform_plan_default_policies_enabled" type="boolean">
  **Include default plan policies.** Turn off to plan with only the policies below instead of the default read-only policies. Requires at least one policy below.

  * Default: `true`
</ResponseField>

<ResponseField name="terraform_plan_iam_policy_arns" type="string_array">
  **Terraform plan IAM policies.** IAM managed policy ARNs for the Terraform plan runner role. Without default policies, allow s3:CreateBucket, s3:PutObject, s3:GetObject, and s3:ListBucket on the ravion-terraform-plans-\<AWS account number> bucket in this account.

  * Default: `[]`
</ResponseField>

<ResponseField name="terraform_apply_default_policies_enabled" type="boolean">
  **Include default apply policies.** Turn off to apply and destroy with only the policies below instead of AdministratorAccess. Requires at least one policy below.

  * Default: `true`
</ResponseField>

<ResponseField name="terraform_apply_iam_policy_arns" type="string_array">
  **Terraform apply IAM policies.** IAM managed policy ARNs for the Terraform apply runner role. Without default policies, allow s3:CreateBucket, s3:PutObject, s3:GetObject, and s3:ListBucket on the ravion-terraform-plans-\<AWS account number> bucket in this account.

  * Default: `[]`
</ResponseField>

<ResponseField name="advanced_terraform_variables" type="object">
  **Advanced Terraform variables.** Optional raw Terraform variable overrides for advanced module inputs or one-off overrides. Values here override the generated variables above.

  * Default: `{}`
</ResponseField>

<ResponseField name="execution_environment_id" type="string">
  **Terraform execution environment.** Override the execution environment for Terraform runners. Must use the same AWS account as selected above.
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.