AWS Secrets Module

This module manages secrets in AWS through Secrets Manager. It will create a KMS key for encrypting secrets, and optionally create one or more secrets.

Caution

OpenTofu state files are stored as plain text. For this reason it is not recommended that you pass secret values to this module, unless you expect them to be rotated immediately. It is safe to use the create_random_password option, as this value will be generated by AWS and not stored in the state file.

Usage

Caution

Version 2.0.0 of this module is a breaking change from previous versions. Please read the release notes for more information.

Add this module to your main.tf (or appropriate) file and configure the inputs to match your desired configuration. For example:

module "secrets" {
  source = "github.com/codeforamerica/tofu-modules-aws-secrets?ref=2.0.0"

  project     = "my-project"
  environment = "dev"

  secrets = {
    example = {
      description = "An example secret."
    }
    "password/test" = {
      create_random_password = true
      description            = "Random password for testing."
    }
    named = {
      description = "A secret with an explicit name."
      name        = "my-project/named/secret"
    }
  }
}

Make sure you re-run tofu init after adding the module to your configuration.

tofu init
tofu plan

Encryption

By default, this module will create a new KMS key to encrypt the secrets. If you already have a key you'd like to use, you can override this behavior:

create_kms_key = false
kms_key_arn    = aws_kms_key.example.arn

Inputs

Name	Description	Type	Default	Required
project	Name of the project.	string	n/a	yes
kms_key_arn	ARN for an existing KMS key to use for encryption. Required if create_kms_key is set to false; ignored otherwise.	string	null	conditional
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
create_kms_key	Whether to create a new KMS key for encrypting secrets. If set to false, kms_key_arn must be provided.	bool	true	no
environment	Environment for the project.	string	"dev"	no
key_recovery_period	Recovery period for deleted KMS keys in days. Must be between 7 and 30. Only used if create_kms_key is set to true.	number	30	no
recovery_window	Recovery window for deleted secrets, in days. Must be between 7 and 30, or 0 to disable recovery when the secret is deleted. This value can be overridden for each secret by setting the recovery_window for the secret.	number	30	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

secrets

An optional map of secrets to be created in AWS Secrets Manager. Once the secret is created, any changes to the value will be ignored. For example, to create a secret named example:

secrets = {
  example = {
    recovery_window = 7
    description     = "Example credentials for our application."
  }
}

The actual name of the secret will use the project, environment, and optionally the service to construct a name prefix for the secret. In the previous example, the secret would be prefixed with my-project/dev/example-. AWS will add a random suffix to the name to ensure uniqueness.

If you wish to override the prefix for the name, you can specify a name key for the secret:

secrets = {
  example = {
    recovery_window = 7
    description     = "Example credentials for our application."
    name            = "my/example/key"
  }
}

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
recovery_window	Override the default recovery window. Must be between 7 and 30, or 0 to disable recovery when the secret is deleted.	number	null	no
start_value	Value to be set into the secret at creation.	string	"{}"	no

Outputs

Name	Description	Type
kms_key_alias	Alias for the created KMS key. If kms_key_arnis 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)