feat: Allow using an existing KMS key.

Author: jamesiarmes

README.md

@@ -61,11 +61,12 @@ tofu init -upgrade
 ## Inputs
 
 | Name                | Description                                                                                                                                     | Type          | Default | Required |
-|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|---------------|---------|----------|
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------- | -------- |
 | project             | Name of the project.                                                                                                                            | `string`      | n/a     | yes      |
 | add_suffix          | Apply a random suffix to the secret name. Useful when secrets may need to be replaced, but makes identify secrets by name alone more difficult. | `bool`        | `true`  | no       |
 | environment         | Environment for the project.                                                                                                                    | `string`      | `"dev"` | no       |
 | key_recovery_period | Number of days to recover the KMS key after deletion.                                                                                           | `number`      | `30`    | no       |
+| kms_key_arn         | Optional KMS key ARN to use for encryption. If not provided, a new KMS key will be created.                                                     | `string`      | `null`  | no       |
 | [secrets]           | Secrets to be created.                                                                                                                          | `map(object)` | `{}`    | no       |
 | service             | Optional service that these resources are supporting. Example: `"api"`, `"web"`, `"worker"`                                                     | `string`      | n/a     | no       |
 | tags                | Optional tags to be applied to all resources.                                                                                                   | `list`        | `[]`    | no       |
@@ -107,7 +108,7 @@ This would result in a key named `my/example/key-` before the random suffix is
 applied.
 
 | Name                   | Description                                                   | Type     | Default | Required |
-|------------------------|---------------------------------------------------------------|----------|---------|----------|
+| ---------------------- | ------------------------------------------------------------- | -------- | ------- | -------- |
 | description            | Description of the secret.                                    | `string` | n/a     | yes      |
 | create_random_password | Creates a random password as the staring value.               | `bool`   | `false` | no       |
 | name                   | Name to use as the prefix for the secret.                     | `string` | `""`    | no       |
@@ -116,11 +117,11 @@ applied.
 
 ## Outputs
 
-| Name          | Description                                   | Type          |
-|---------------|-----------------------------------------------|---------------|
-| kms_key_alias | Alias for of the KMS key used for encryption. | `string`      |
-| kms_key_arn   | ARN for of the KMS key used for encryption.   | `string`      |
-| secrets       | A map of created secrets.                     | `map(object)` |
+| Name          | Description                                                                      | Type          |
+| ------------- | -------------------------------------------------------------------------------- | ------------- |
+| kms_key_alias | Alias for the created KMS key. If `kms_key_arn`is provided, this will be `null`. | `string`      |
+| kms_key_arn   | ARN of the KMS key used for encryption.                                          | `string`      |
+| secrets       | A map of created secrets.                                                        | `map(object)` |
 
 [2.0.0]: CHANGELOG.md#200-2025-08-19
 [badge-release]: https://img.shields.io/github/v/release/codeforamerica/tofu-modules-aws-secrets?logo=github&label=Latest%20Release

data.tf

@@ -3,3 +3,9 @@ data "aws_caller_identity" "identity" {}
 data "aws_partition" "current" {}
 
 data "aws_region" "current" {}
+
+data "aws_kms_key" "secrets" {
+  for_each = var.kms_key_arn != null ? toset(["this"]) : toset([])
+
+  key_id = var.kms_key_arn
+}

kms.tf

@@ -1,4 +1,6 @@
 resource "aws_kms_key" "secrets" {
+  for_each = var.kms_key_arn == null ? toset(["this"]) : toset([])
+
   description             = "Secrets encryption key for ${var.project} ${var.environment}"
   deletion_window_in_days = var.key_recovery_period
   enable_key_rotation     = true
@@ -12,6 +14,8 @@ resource "aws_kms_key" "secrets" {
 }
 
 resource "aws_kms_alias" "secrets" {
+  for_each = var.kms_key_arn == null ? toset(["this"]) : toset([])
+
   name          = "alias/${var.project}/${var.environment}/${var.service != "" ? "${var.service}/" : ""}secrets"
-  target_key_id = aws_kms_key.secrets.id
+  target_key_id = aws_kms_key.secrets["this"].id
 }

locals.tf

@@ -0,0 +1,4 @@
+locals {
+  kms_key_arn = var.kms_key_arn != null ? var.kms_key_arn : aws_kms_key.secrets["this"].arn
+  kms_key_id  = var.kms_key_arn != null ? data.aws_kms_key.secrets["this"].id : aws_kms_key.secrets["this"].id
+}

main.tf

@@ -15,7 +15,7 @@ module "secrets_manager" {
   create_random_password  = each.value.create_random_password
   description             = each.value.description
   recovery_window_in_days = each.value.recovery_window
-  kms_key_id              = aws_kms_alias.secrets.id
+  kms_key_id              = local.kms_key_id
   secret_string           = each.value.start_value
 
   ignore_secret_changes = true

outputs.tf

@@ -1,11 +1,14 @@
 output "kms_key_alias" {
-  description = "Alias for of the KMS key used for encryption."
-  value       = aws_kms_alias.secrets.name
+  description = <<-EOT
+    Alias for the created KMS key. If `kms_key_arn`is provided, this will be
+    `null`.
+    EOT
+  value       = var.kms_key_arn == null ? aws_kms_alias.secrets["this"].name : null
 }
 
 output "kms_key_arn" {
-  description = "ARN for of the KMS key used for encryption."
-  value       = aws_kms_key.secrets.arn
+  description = "ARN of the KMS key used for encryption."
+  value       = local.kms_key_arn
 }
 
 output "secrets" {

variables.tf

@@ -21,6 +21,15 @@ variable "key_recovery_period" {
   }
 }
 
+variable "kms_key_arn" {
+  type        = string
+  description = <<-EOT
+    Optional KMS key ARN to use for encryption. If not provided, a new KMS key
+    will be created.
+    EOT
+  default     = null
+}
+
 variable "project" {
   type        = string
   description = "Project that these resources are supporting."