# AWS Secrets Manager Terraform module Terraform module which creates AWS Secrets Manager resources. [![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md) ## Usage See [`examples`](https://github.com/terraform-aws-modules/terraform-aws-secrets-manager/tree/master/examples) directory for working examples to reference: ### Standard ```hcl module "secrets_manager" { source = "terraform-aws-modules/secrets-manager/aws" # Secret name_prefix = "example" description = "Example Secrets Manager secret" recovery_window_in_days = 30 # Policy create_policy = true block_public_policy = true policy_statements = { read = { sid = "AllowAccountRead" principals = [{ type = "AWS" identifiers = ["arn:aws:iam::1234567890:root"] }] actions = ["secretsmanager:GetSecretValue"] resources = ["*"] } } # Version create_random_password = true random_password_length = 64 random_password_override_special = "!@#$%^&*()_+" tags = { Environment = "Development" Project = "Example" } } ``` ### w/ Rotation ```hcl module "secrets_manager" { source = "terraform-aws-modules/secrets-manager/aws" # Secret name_prefix = "rotated-example" description = "Rotated example Secrets Manager secret" recovery_window_in_days = 7 # Policy create_policy = true block_public_policy = true policy_statements = { lambda = { sid = "LambdaReadWrite" principals = [{ type = "AWS" identifiers = ["arn:aws:iam:1234567890:role/lambda-function"] }] actions = [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "secretsmanager:UpdateSecretVersionStage", ] resources = ["*"] } read = { sid = "AllowAccountRead" principals = [{ type = "AWS" identifiers = ["arn:aws:iam::1234567890:root"] }] actions = ["secretsmanager:DescribeSecret"] resources = ["*"] } } # Version ignore_secret_changes = true secret_string = jsonencode({ engine = "mariadb", host = "mydb.cluster-123456789012.us-east-1.rds.amazonaws.com", username = "Bill", password = "Initial" dbname = "ThisIsMySuperSecretString12356!&*()", port = 3306 }) # Rotation enable_rotation = true rotation_lambda_arn = "arn:aws:lambda:us-east-1:123456789012:function:my-function" rotation_rules = { # This should be more sensible in production schedule_expression = "rate(1 minute)" } tags = { Environment = "Development" Project = "Example" } } ``` ### Metadata Only (Value Managed Externally) ```hcl module "secrets_manager" { source = "terraform-aws-modules/secrets-manager/aws" # Secret name = "my-app/prod/api-key" description = "API key managed by CI/CD pipeline" # Skip secret version creation - value is managed outside Terraform create_secret_version = false tags = { Environment = "Production" Project = "Example" } } ``` ## Known limitations (Terraform/OpenTofu, not this module) A few requests come up again and again and cannot be implemented by this module, or by any module: Terraform requires `lifecycle` arguments to be literal values inside the resource block. [hashicorp/terraform#18367](https://github.com/hashicorp/terraform/issues/18367) has been open since 2018, [#22544](https://github.com/hashicorp/terraform/issues/22544) since 2019, and [opentofu/opentofu#1329](https://github.com/opentofu/opentofu/issues/1329) is the same request for OpenTofu. - **terraform destroy deleted a secret other systems depend on** - Native option: keep `recovery_window_in_days` at a real value so a deleted secret can be restored. [Compliance.tf](https://compliance.tf/?utm_source=github&utm_medium=readme&utm_campaign=known-limitations) serves this module with these rules applied at download time, on top of whatever your organization already has enabled there. Inputs and outputs do not change; the `source` line does. Drop the `version` argument and pin the release you use by adding `&version=` and that release number to the URL. To get started, register a free compliance.tf account and configure an access token: source = "https://registry.compliance.tf/terraform-aws-modules/secrets-manager/aws?add_rules=lifecycle_prevent_destroy_encryption" The full workaround for each item above, and the exact diff each rule makes, are in the [compliance.tf docs for this module](https://compliance.tf/docs/workarounds/terraform-aws-secrets-manager/?utm_source=github&utm_medium=readme&utm_campaign=known-limitations). To preview a diff without an account, open this module in the [Rules Playground](https://registry.compliance.tf/playground?module=terraform-aws-modules/secrets-manager/aws&rules=lifecycle_prevent_destroy_encryption). Disclosure: written by this module's maintainer, who also builds [compliance.tf](https://compliance.tf/?utm_source=github&utm_medium=readme&utm_campaign=known-limitations). ## Examples Examples codified under the [`examples`](https://github.com/terraform-aws-modules/terraform-aws-secrets-manager/tree/master/examples) are intended to give users references for how to use the module(s) as well as testing/validating changes to the source code of the module. If contributing to the project, please be sure to make any appropriate updates to the relevant examples to allow maintainers to test your changes and to keep the examples up to date for users. Thank you! - [Complete](https://github.com/terraform-aws-modules/terraform-aws-secrets-manager/tree/master/examples/complete) ## Requirements | Name | Version | | ---- | ------- | | [terraform](#requirement\_terraform) | >= 1.11 | | [aws](#requirement\_aws) | >= 6.28 | | [random](#requirement\_random) | >= 3.7 | ## Providers | Name | Version | | ---- | ------- | | [aws](#provider\_aws) | >= 6.28 | ## Modules No modules. ## Resources | Name | Type | | ---- | ---- | | [aws_secretsmanager_secret.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/secretsmanager_secret) | resource | | [aws_secretsmanager_secret_policy.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/secretsmanager_secret_policy) | resource | | [aws_secretsmanager_secret_rotation.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/secretsmanager_secret_rotation) | resource | | [aws_secretsmanager_secret_version.ignore_changes](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/secretsmanager_secret_version) | resource | | [aws_secretsmanager_secret_version.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/secretsmanager_secret_version) | resource | | [aws_iam_policy_document.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source | ## Inputs | Name | Description | Type | Default | Required | | ---- | ----------- | ---- | ------- | :------: | | [block\_public\_policy](#input\_block\_public\_policy) | Makes an optional API call to Zelkova to validate the Resource Policy to prevent broad access to your secret | `bool` | `null` | no | | [create](#input\_create) | Determines whether resources will be created (affects all resources) | `bool` | `true` | no | | [create\_policy](#input\_create\_policy) | Determines whether a policy will be created | `bool` | `false` | no | | [create\_random\_password](#input\_create\_random\_password) | Determines whether an ephemeral random password will be generated for `secret_string_wo` | `bool` | `false` | no | | [create\_secret\_version](#input\_create\_secret\_version) | Determines whether a secret version is created. Set to `false` when secret values are managed externally (manually, by CI, or by a rotation process outside Terraform) | `bool` | `true` | no | | [description](#input\_description) | A description of the secret | `string` | `null` | no | | [enable\_rotation](#input\_enable\_rotation) | Determines whether secret rotation is enabled | `bool` | `false` | no | | [force\_overwrite\_replica\_secret](#input\_force\_overwrite\_replica\_secret) | Accepts boolean value to specify whether to overwrite a secret with the same name in the destination Region | `bool` | `null` | no | | [ignore\_secret\_changes](#input\_ignore\_secret\_changes) | Determines whether or not Terraform will ignore changes made externally to `secret_string` or `secret_binary`. Changing this value after creation is a destructive operation | `bool` | `false` | no | | [kms\_key\_id](#input\_kms\_key\_id) | ARN or Id of the AWS KMS key to be used to encrypt the secret values in the versions stored in this secret. If you need to reference a CMK in a different account, you can use only the key ARN. If you don't specify this value, then Secrets Manager defaults to using the AWS account's default KMS key (the one named `aws/secretsmanager` | `string` | `null` | no | | [name](#input\_name) | Friendly name of the new secret. The secret name can consist of uppercase letters, lowercase letters, digits, and any of the following characters: `/_+=.@-` | `string` | `null` | no | | [name\_prefix](#input\_name\_prefix) | Creates a unique name beginning with the specified prefix | `string` | `null` | no | | [override\_policy\_documents](#input\_override\_policy\_documents) | List of IAM policy documents that are merged together into the exported document. In merging, statements with non-blank `sid`s will override statements with the same `sid` | `list(string)` | `[]` | no | | [policy\_statements](#input\_policy\_statements) | A map of IAM policy [statements](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document#statement) for custom permission usage |

map(object({
    sid           = optional(string)
    actions       = optional(list(string))
    not_actions   = optional(list(string))
    effect        = optional(string)
    resources     = optional(list(string))
    not_resources = optional(list(string))
    principals = optional(list(object({
      type        = string
      identifiers = list(string)
    })))
    not_principals = optional(list(object({
      type        = string
      identifiers = list(string)
    })))
    condition = optional(list(object({
      test     = string
      values   = list(string)
      variable = string
    })))
  }))

| `null` | no | | [random\_password\_length](#input\_random\_password\_length) | The length of the generated random password | `number` | `32` | no | | [random\_password\_override\_special](#input\_random\_password\_override\_special) | Supply your own list of special characters to use for string generation. This overrides the default character list in the special argument | `string` | `"!@#$%&*()-_=+[]{}<>:?"` | no | | [recovery\_window\_in\_days](#input\_recovery\_window\_in\_days) | Number of days that AWS Secrets Manager waits before it can delete the secret. This value can be `0` to force deletion without recovery or range from `7` to `30` days. The default value is `30` | `number` | `null` | no | | [region](#input\_region) | Region where the resource(s) will be managed. Defaults to the Region set in the provider configuration | `string` | `null` | no | | [replica](#input\_replica) | Configuration block to support secret replication |

map(object({
    kms_key_id = optional(string)
    region     = optional(string) # will default to the key name
  }))

object({
    automatically_after_days = optional(number)
    duration                 = optional(string)
    schedule_expression      = optional(string)
  })

| `null` | no | | [secret\_binary](#input\_secret\_binary) | Specifies binary data that you want to encrypt and store in this version of the secret. This is required if `secret_string` or `secret_string_wo` is not set. Needs to be encoded to base64 | `string` | `null` | no | | [secret\_string](#input\_secret\_string) | Specifies text data that you want to encrypt and store in this version of the secret. This is required if `secret_binary` or `secret_string_wo` is not set | `string` | `null` | no | | [secret\_string\_wo](#input\_secret\_string\_wo) | Specifies text data that you want to encrypt and store in this version of the secret. This is required if `secret_binary` or `secret_string` is not set | `string` | `null` | no | | [secret\_string\_wo\_version](#input\_secret\_string\_wo\_version) | Used together with `secret_string_wo` to trigger an update. Increment this value when an update to `secret_string_wo` is required | `string` | `null` | no | | [source\_policy\_documents](#input\_source\_policy\_documents) | List of IAM policy documents that are merged together into the exported document. Statements must have unique `sid`s | `list(string)` | `[]` | no | | [tags](#input\_tags) | A map of tags to add to all resources | `map(string)` | `{}` | no | | [version\_stages](#input\_version\_stages) | Specifies a list of staging labels that are attached to this version of the secret. A staging label must be unique to a single version of the secret | `list(string)` | `null` | no | ## Outputs | Name | Description | | ---- | ----------- | | [secret\_arn](#output\_secret\_arn) | The ARN of the secret | | [secret\_binary](#output\_secret\_binary) | The secret binary | | [secret\_id](#output\_secret\_id) | The ID of the secret | | [secret\_name](#output\_secret\_name) | The name of the secret | | [secret\_replica](#output\_secret\_replica) | Attributes of the replica created | | [secret\_string](#output\_secret\_string) | The secret string | | [secret\_version\_id](#output\_secret\_version\_id) | The unique identifier of the version of the secret | ## License Apache-2.0 Licensed. See [LICENSE](https://github.com/terraform-aws-modules/terraform-aws-secrets-manager/blob/master/LICENSE).

AWS Secrets Manager Terraform module

Terraform Module Source