> ## 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.1.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.1.0/security/kms)

## Inputs reference

All inputs for `rvn-aws-kms` version `0.1.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="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>