### Migrate Terraform State Objects (Script Example)

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

This example shows the output of a migration script that iterates through secrets and moves them from the old list index format to the new map key format in the Terraform state file.

```bash
$ ./secret_list_to_map.sh secrets-manager-1

Move "module.secrets-manager-1.aws_secretsmanager_secret.sm[0]" to "module.secrets-manager-1.aws_secretsmanager_secret.sm[\"secret-1\"]"
Successfully moved 1 object(s).
Move "module.secrets-manager-1.aws_secretsmanager_secret_version.sm-sv[0]" to "module.secrets-manager-1.aws_secretsmanager_secret_version.sm-sv[\"secret-1\"]"
Successfully moved 1 object(s).
Move "module.secrets-manager-1.aws_secretsmanager_secret.sm[1]" to "module.secrets-manager-1.aws_secretsmanager_secret.sm[\"secret-2\"]"
Successfully moved 1 object(s).
Move "module.secrets-manager-1.aws_secretsmanager_secret_version.sm-sv[1]" to "module.secrets-manager-1.aws_secretsmanager_secret_version.sm-sv[\"secret-2\"]"
Successfully moved 1 object(s).

```

--------------------------------

### Security Enhancement Prompt

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Example prompt for Claude to research and implement enhanced encryption configurations for Secrets Manager security.

```markdown
@claude Research the latest Secrets Manager security best practices and help me implement enhanced encryption configurations in this module.
```

--------------------------------

### Ephemeral Mode Development Prompt

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Example prompt for Claude to research ephemeral resource patterns and improve write-only secret handling.

```markdown
@claude Look up the latest Terraform ephemeral resource patterns and help me improve the write-only secret handling in this module.
```

--------------------------------

### Configure Context7 MCP Server

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Local configuration for the Context7 MCP server. This setup enables access to general library and framework documentation.

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}
```

--------------------------------

### Configure Replica Regions with Default KMS Key

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/replication/README.md

This example shows how to configure replica regions. Leaving the KMS key ARN empty for a region will use the default KMS key for that region.

```terraform
    replica_regions = {
      us-west-2 = {}
      us-west-1 = "arn:aws:kms:us-west-1:1234567890:key/12345678-1234-1234-1234-123456789012"

    }
```

--------------------------------

### Secrets Manager Resource Development Prompt

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Example prompt for Claude to assist with Secrets Manager resource development, specifically cross-region secret replication.

```markdown
@claude I need to add support for cross-region secret replication. Can you look up the latest aws_secretsmanager_secret_replica documentation and show me how to implement this feature?
```

--------------------------------

### Create Multiple Secret Replicas with for_each

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Example of using `for_each` to create multiple secret replicas across different regions. Ensure the `secret_replicas` variable is structured correctly.

```hcl
# Example: Creating multiple secret replicas
resource "aws_secretsmanager_secret_replica" "this" {
  for_each = {
    for idx, replica in var.secret_replicas : 
    "${replica.region}_${idx}" => replica
  }
  
  secret_id = aws_secretsmanager_secret.this[each.value.secret_name].id
  region    = each.value.region
  
  kms_key_id = try(each.value.kms_key_id, null)
}
```

--------------------------------

### Manage Secret Lifecycle with create_before_destroy and ignore_changes

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Configure lifecycle rules for secrets, including `create_before_destroy` and `ignore_changes`. This example demonstrates protecting a secret created alongside module-managed secrets.

```hcl
# Use module for convenience, then protect specific secrets separately
module "secrets-manager" {
  source = "lgallard/secrets-manager/aws"

  secrets = {
    app-config = {
      description   = "Application configuration"
      secret_string = "app-configuration-data"
    }
  }
}

# Create additional protected secret with lifecycle rules
resource "aws_secretsmanager_secret" "protected_secret" {
  name        = "critical-database-password"
  description = "Critical database password - protected from accidental deletion"

  lifecycle {
    prevent_destroy       = true
    create_before_destroy = true
  }

  tags = {
    Environment = "production"
    Critical    = "true"
  }
}

resource "aws_secretsmanager_secret_version" "protected_version" {
  secret_id     = aws_secretsmanager_secret.protected_secret.id
  secret_string = "super-secret-password"

  lifecycle {
    ignore_changes = [secret_string]
  }
}
```

--------------------------------

### Create Secrets with KMS Encryption using Terraform

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

This example shows how to encrypt secrets using a customer-managed KMS key. Provide the `kms_key_id` to enable KMS encryption for the secret.

```hcl
module "secrets-manager-kms" {
  source = "lgallard/secrets-manager/aws"

  secrets = {
    database-credentials = {
      description = "Database credentials encrypted with customer KMS key"
      secret_key_value = {
        username = "admin"
        password = "super-secret-password"
        host     = "db.example.com"
        port     = "5432"
      }
      kms_key_id              = "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
      recovery_window_in_days = 7
    }
  }

  tags = {
    Environment = "production"
    KMSEncrypted = "true"
  }
}
```

--------------------------------

### Configure Terraform MCP Server

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Local configuration for the Terraform MCP server. This setup allows access to up-to-date Terraform and AWS provider documentation.

```json
{
  "mcpServers": {
    "terraform": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-terraform@latest"]
    }
  }
}
```

--------------------------------

### Generate Multiple Ephemeral Passwords with for_each

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

When using `for_each` with ephemeral resources, direct AWS resource creation is required due to Terraform limitations. This example shows generating multiple passwords and creating secrets directly.

```hcl
# Generate multiple ephemeral passwords
ephemeral "random_password" "db_passwords" {
  for_each = var.db_users
  length   = 24
  special  = true
}

# Create secrets directly (not through module)
resource "aws_secretsmanager_secret_version" "db_secret_versions" {
  for_each = var.db_users
  
  secret_id = aws_secretsmanager_secret.db_secrets[each.key].id
  
  secret_string_wo = jsonencode({
    username = each.key
    password = ephemeral.random_password.db_passwords[each.key].result
  })
  
  secret_string_wo_version = 1
}
```

--------------------------------

### Manage Secret Lifecycle with prevent_destroy

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Protect secrets from accidental deletion by setting `prevent_destroy = true` in the lifecycle block. This example shows creating a secret directly with this protection.

```hcl
# Create secret directly with lifecycle protection
resource "aws_secretsmanager_secret" "critical_secret" {
  name        = "critical-database-password"
  description = "Critical database password - protected from accidental deletion"

  lifecycle {
    prevent_destroy = true
  }

  tags = {
    Environment = "production"
    Critical    = "true"
  }
}

resource "aws_secretsmanager_secret_version" "critical_secret_version" {
  secret_id     = aws_secretsmanager_secret.critical_secret.id
  secret_string = "super-secret-password"

  lifecycle {
    ignore_changes = [secret_string]
  }
}
```

--------------------------------

### Ephemeral variable limitation

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/ephemeral-limitations.md

This example illustrates how declaring a variable with `ephemeral = true` makes the entire variable ephemeral, preventing its use with `for_each`.

```hcl
variable "rotate_secrets" {
  ephemeral = true  # This makes the ENTIRE map ephemeral
}

resource "aws_secretsmanager_secret" "rsm" {
  for_each = var.rotate_secrets  # ❌ FAILS: Cannot use ephemeral value in for_each
}
```

--------------------------------

### Terraform Limitation: Ephemeral Variables with for_each

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/ephemeral-for-each-patterns.md

This example illustrates a fundamental Terraform limitation where variables marked as `ephemeral = true` cannot be used with `for_each` in resource definitions.

```hcl
variable "rotate_secrets" {
  ephemeral = true  # Makes the whole map ephemeral
}

resource "aws_secretsmanager_secret" "rsm" {
  for_each = var.rotate_secrets  # ❌ FAILS: Cannot use ephemeral in for_each
}
```

--------------------------------

### Terraform Variable Validation for Naming Conventions

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Implement validation blocks for critical input variables to enforce specific formats or constraints. This example validates a secret name against a regex pattern.

```hcl
# Example: Basic validation for naming conventions
variable "secret_name" {
  description = "Name of the secret to create"
  type        = string
  default     = null

  validation {
    condition     = var.secret_name == null ? true : can(regex("^[0-9A-Za-z-_/.]{1,512}$", var.secret_name))
    error_message = "The secret_name must be between 1 and 512 characters, contain only alphanumeric characters, hyphens, underscores, periods, and forward slashes."
  }
}
```

--------------------------------

### Fix Tag Validation Error

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Corrects 'Tag Validation Error' by removing tags where keys start with 'aws:' (case-insensitive).

```text
Error: Tag keys cannot start with 'aws:' (case insensitive).
**Solution**: Remove any tags that start with `aws:`, `AWS:`, or any case variation.
```

--------------------------------

### Solution 2: Individual Module Instances for Known Secrets

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/ephemeral-for-each-patterns.md

This approach uses individual module instances for a small, known set of secrets. It configures the module to handle ephemeral secrets for specific use cases.

```hcl
# Ephemeral passwords
ephemeral "random_password" "db_passwords" {
  for_each = var.db_users
  length   = 24
  special  = true
}

# Individual module for admin
module "db_admin_secret" {
  source = "lgallard/secrets-manager/aws"
  version = "0.16.0"  # Use latest version
  
  ephemeral = true

  rotate_secrets = {
    "db-${var.app_name}-admin" = {
      description = "Database admin credentials"
      secret_key_value = {
        username = "admin"
        password = ephemeral.random_password.db_passwords["admin"].result
        host     = "db.${var.app_name}.internal"
        port     = 5432
      }
      secret_string_wo_version  = 1
      rotation_lambda_arn       = var.rotation_lambda_arn
      automatically_after_days  = 90
    }
  }
}
```

--------------------------------

### Solution 1: Direct AWS Resources with Ephemeral Passwords

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/ephemeral-for-each-patterns.md

This solution uses AWS resources directly, including ephemeral passwords, to manage secrets. It demonstrates the recommended approach for handling ephemeral secrets with `for_each`.

```hcl
# Variables
variable "db_users" {
  type = map(object({
    role = string
  }))
  default = {
    "admin" = { role = "admin" }
    "app"   = { role = "application" }
  }
}

variable "app_name" {
  type = string
  default = "myapp"
}

# Ephemeral passwords - THIS WORKS!
ephemeral "random_password" "db_passwords" {
  for_each         = var.db_users
  length           = 24
  special          = true
  override_special = "!@#%^&*-_=?"
  min_numeric      = 1
}

# KMS key
resource "aws_kms_key" "secrets_key" {
  description             = "KMS key for secrets"
  deletion_window_in_days = 7
}

# Create secrets directly - THIS WORKS WITH EPHEMERAL!
resource "aws_secretsmanager_secret" "db_secrets" {
  for_each = var.db_users

  name                    = "db-${var.app_name}-${each.key}"
  description             = "${var.app_name} database credentials for ${each.key}"
  kms_key_id              = aws_kms_key.secrets_key.arn
  recovery_window_in_days = 0

  tags = {
    Environment = "production"
    User        = each.key
  }
}

# Create secret versions with ephemeral values - THIS WORKS!
resource "aws_secretsmanager_secret_version" "db_secret_versions" {
  for_each = var.db_users

  secret_id = aws_secretsmanager_secret.db_secrets[each.key].id
  
  # Using write-only parameter prevents state storage
  secret_string_wo = jsonencode({
    username = each.key
    password = ephemeral.random_password.db_passwords[each.key].result
    host     = "db.${var.app_name}.internal"
    port     = 5432
    engine   = "postgres"
    dbname   = var.app_name
  })
  
  secret_string_wo_version = 1  # Required for ephemeral mode
}

# Add rotation
resource "aws_secretsmanager_secret_rotation" "db_rotations" {
  for_each = var.db_users

  secret_id           = aws_secretsmanager_secret.db_secrets[each.key].id
  rotation_lambda_arn = "arn:aws:lambda:us-east-1:123456789012:function:rotate-secret"

  rotation_rules {
    automatically_after_days = 90
  }
}
```

--------------------------------

### Ephemeral Mode Validation Rule

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Example Terraform validation rule for secrets when ephemeral mode is enabled. It ensures `secret_string_wo_version` is present and greater than or equal to 1.

```hcl
variable "secrets" {
  type = map(object({
    description              = string
    secret_string            = optional(string)
    secret_string_wo_version = optional(number)
    # ... other fields
  }))
  
  validation {
    condition = alltrue([
      for k, v in var.secrets :
      var.ephemeral == false || (can(v.secret_string_wo_version) && try(v.secret_string_wo_version >= 1, false))
    ])
    error_message = "secret_string_wo_version is required and must be >= 1 when ephemeral is enabled."
  }
}
```

--------------------------------

### Individual module instances for ephemeral secrets

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/ephemeral-limitations.md

This solution involves creating separate module instances for each secret, allowing for the management of ephemeral values when dealing with a smaller number of secrets.

```hcl
# Ephemeral passwords
ephemeral "random_password" "db_passwords" {
  for_each = var.db_users
  length   = 24
  special  = true
}

# Individual module for admin user
module "db_admin_secret" {
  source = "lgallard/secrets-manager/aws"
  
  ephemeral = true

  rotate_secrets = {
    "db-${var.app_name}-admin" = {
      description = "Database admin credentials"
      secret_key_value = {
        username = "admin"
        password = ephemeral.random_password.db_passwords["admin"].result
        host     = "db.${var.app_name}.internal"
        port     = 5432
      }
      secret_string_wo_version  = 1
      rotation_lambda_arn       = var.rotation_lambda_arn
      automatically_after_days  = 90
    }
  }
}

# Individual module for app user  
module "db_app_secret" {
  source = "lgallard/secrets-manager/aws"
  
  ephemeral = true

  rotate_secrets = {
    "db-${var.app_name}-app" = {
      description = "Database app credentials"
      secret_key_value = {
        username = "app"
        password = ephemeral.random_password.db_passwords["app"].result
        host     = "db.${var.app_name}.internal"
        port     = 5432
      }
      secret_string_wo_version  = 1
      rotation_lambda_arn       = var.rotation_lambda_arn
      automatically_after_days  = 90
    }
  }
}
```

--------------------------------

### User's Original Request (Fails)

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/ephemeral-for-each-patterns.md

This pattern demonstrates the user's original request which fails due to Terraform core limitations regarding ephemeral resources and `for_each`.

```hcl
# USER'S DESIRED PATTERN (DOESN'T WORK):
ephemeral "random_password" "db_passwords" {
  for_each = var.db_users
  length = 24
  special = true
}

module "db_users_secrets_manager" {
  source = "lgallard/secrets-manager/aws"
  ephemeral = true
  rotate_secrets = {
    for username, role in var.db_users : "db-${var.name}-${username}" => {
      password = ephemeral.random_password.db_passwords[username].result # ❌ FAILS
    }
  }
}
```

--------------------------------

### Create Key-Value Secrets

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/key-value/README.md

Define multiple key-value secrets with descriptions, key-value pairs, recovery windows, and optional policies and tags. Ensure the 'secrets' map is correctly structured.

```HCL
module "secrets-manager-2" {

  #source = "lgallard/secrets-manager/aws"
  source = "../../"

  secrets = {
    secret-kv-1 = {
      description = "This is a key/value secret"
      secret_key_value = {
        key1 = "value1"
        key2 = "value2"
      }
      recovery_window_in_days = 7
      policy                  = <<POLICY
				{
					"Version": "2012-10-17",
					"Statement": [
						{
							"Sid": "EnableAllPermissions",
							"Effect": "Allow",
							"Principal": {
								"AWS": "*"
							},
							"Action": "secretsmanager:GetSecretValue",
							"Resource": "*"
						}
					]
				}
				POLICY
    },
    secret-kv-2 = {
      description = "Another key/value secret"
      secret_key_value = {
        username = "user"
        password = "topsecret"
      }
      tags = {
        app = "web"
      }
      recovery_window_in_days = 7
      policy                  = null
    },
  }

  tags = {
    Owner       = "DevOps team"
    Environment = "dev"
    Terraform   = true
  }
}
```

--------------------------------

### Direct resource usage for ephemeral secrets

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/ephemeral-limitations.md

This solution demonstrates creating secrets directly using AWS resources, bypassing the module wrapper to manage ephemeral values.

```hcl
# Variables
variable "db_users" {
  type = map(object({
    role = string
  }))
}

variable "app_name" {
  type = string
}

# Ephemeral passwords
ephemeral "random_password" "db_passwords" {
  for_each         = var.db_users
  length           = 24
  special          = true
  override_special = "!@#%^&*-_=?"
  min_numeric      = 1
}

# KMS key
resource "aws_kms_key" "secrets_key" {
  description = "KMS key for secrets"
}

# Create secrets directly (THIS WORKS!)
resource "aws_secretsmanager_secret" "db_secrets" {
  for_each = var.db_users

  name                    = "db-${var.app_name}-${each.key}"
  description             = "${var.app_name} database credentials for ${each.key}"
  kms_key_id              = aws_kms_key.secrets_key.arn
  recovery_window_in_days = 0

  tags = {
    Environment = "production"
    User        = each.key
  }
}

# Create secret versions with ephemeral values (THIS WORKS!)
resource "aws_secretsmanager_secret_version" "db_secret_versions" {
  for_each = var.db_users

  secret_id = aws_secretsmanager_secret.db_secrets[each.key].id
  
  # Using write-only parameter with ephemeral value
  secret_string_wo = jsonencode({
    username = each.key
    password = ephemeral.random_password.db_passwords[each.key].result
    host     = "db.${var.app_name}.internal"
    port     = 5432
    engine   = "postgres"
    dbname   = var.app_name
  })
  
  secret_string_wo_version = 1
}

# Add rotation
resource "aws_secretsmanager_secret_rotation" "db_rotations" {
  for_each = var.db_users

  secret_id           = aws_secretsmanager_secret.db_secrets[each.key].id
  rotation_lambda_arn = "arn:aws:lambda:us-east-1:123456789012:function:rotate-secret"

  rotation_rules {
    automatically_after_days = 90
  }
}
```

--------------------------------

### Configure Binary Secret in Ephemeral Mode

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Manage binary secrets like SSL certificates in ephemeral mode. Use `file()` to reference the binary file and set `secret_string_wo_version`.

```hcl
secrets = {
  ssl_certificate = {
    description              = "SSL private key"
    secret_binary            = file("${path.module}/private.key")
    secret_string_wo_version = 1  # Binary secrets use string version parameter
  }
}
```

--------------------------------

### Module with Pre-defined Keys for Ephemeral Secrets

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/ephemeral-limitations.md

Use this pattern for static configurations of ephemeral secrets. It defines specific secrets with pre-defined keys, leveraging `ephemeral = true` and `secret_string_wo_version` to prevent state storage.

```hcl
module "ephemeral_db_secrets" {
  source = "lgallard/secrets-manager/aws"
  
  ephemeral = true

  rotate_secrets = {
    "db-admin" = {
      description = "Database admin credentials"
      secret_key_value = {
        username = "admin"
        password = ephemeral.random_password.db_passwords["admin"].result
      }
      secret_string_wo_version = 1
    }
    "db-app" = {
      description = "Database app credentials"  
      secret_key_value = {
        username = "app"
        password = ephemeral.random_password.db_passwords["app"].result
      }
      secret_string_wo_version = 1
    }
  }
}
```

--------------------------------

### After Migration to Ephemeral Secrets

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/README.md

This is the configuration after migrating to ephemeral secrets. It includes `ephemeral = true` and `secret_string_wo_version = 1` to ensure sensitive values are not stored in the state file.

```hcl
module "secrets" {
  source = "../../"
  
  ephemeral = true
  
  secrets = {
    db_password = {
      description = "Database password (ephemeral)"
      secret_string = var.db_password
      secret_string_wo_version = 1
    }
  }
}
```

--------------------------------

### Resource Creation with for_each vs count in Terraform

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Favor using `for_each` over `count` for resource creation in Terraform for better management and readability. `for_each` is preferred when creating multiple instances of a resource based on a map or set.

```hcl
# Preferred: Using for_each
resource "aws_secretsmanager_secret" "this" {
  for_each = var.enabled ? var.secrets : {}
  
  name = each.value.name
  # ...
}

# Avoid: Using count when for_each is more appropriate
resource "aws_secretsmanager_secret" "this" {
  count = var.enabled ? length(var.secrets) : 0
  # ...
}
```

--------------------------------

### Configure Secrets Rotation with Lambda

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Enable automatic rotation for secrets by specifying a rotation Lambda function ARN and the rotation interval in days. The Lambda function must exist and have appropriate permissions.

```hcl
module "secrets-manager-rotation" {
  source = "lgallard/secrets-manager/aws"

  rotate_secrets = {
    database-password = {
      description             = "Database password rotated every 30 days"
      secret_string           = "initial-password"
      rotation_lambda_arn     = "arn:aws:lambda:us-east-1:123456789012:function:rotate-secret"
      automatically_after_days = 30
      recovery_window_in_days = 15
    },
    api-key = {
      description             = "API key rotated weekly"
      secret_string           = "initial-api-key"
      rotation_lambda_arn     = "arn:aws:lambda:us-east-1:123456789012:function:rotate-secret"
      automatically_after_days = 7
      recovery_window_in_days = 7
    }
  }

  tags = {
    Owner       = "DevOps team"
    Environment = "dev"
    Terraform   = true
  }
}
```

--------------------------------

### Migrate to Ephemeral Mode

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Transition an existing secret configuration to ephemeral mode. This involves setting `ephemeral = true` and adding the `secret_string_wo_version` parameter to your secrets.

```hcl
module "secrets" {
  source = "lgallard/secrets-manager/aws"
  
  # Before Migration:
  # secrets = {
  #   database_password = {
  #     description   = "Database password"
  #     secret_string = var.db_password
  #   }
  # }

  # After Migration:
  ephemeral = true  # Enable ephemeral mode
  
  secrets = {
    database_password = {
      description              = "Database password (ephemeral)"
      secret_string            = var.db_password
      secret_string_wo_version = 1  # Add version parameter
    }
  }
}
```

--------------------------------

### Create Plain Text and Key/Value Secrets with Replica Regions

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/replication/README.md

Use this snippet to create both plain text and key/value secrets. It configures replica regions and specifies recovery window days and force overwrite behavior.

```terraform
module "secrets-manager-6" {

  source = "lgallard/secrets-manager/aws"

  secrets = {
    secret-plain = {
      description             = "My plain text secret"
      recovery_window_in_days = 7
      secret_string           = "This is an example"
      replica_regions = {
        us-west-2 = "arn:aws:kms:us-west-2:1234567890:key/12345678-1234-1234-1234-123456789012"
      }
      force_overwrite_replica_secret = true
    },
    secret-key-value = {
      description = "This is a key/value secret"
      secret_key_value = {
        username = "user"
        password = "topsecret"
      }
      replica_regions = {
        us-west-1 = "arn:aws:kms:us-west-1:1234567890:key/12345678-1234-1234-1234-123456789012"
      }
      force_overwrite_replica_secret = false
      tags = {
        app = "web"
      }
      recovery_window_in_days = 7
    },
  }

  tags = {
    Owner       = "DevOps team"
    Environment = "dev"
    Terraform   = true
  }

}
```

--------------------------------

### Configure Key-Value Secret in Ephemeral Mode

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Configure a key-value secret for ephemeral storage. This includes defining username, password, host, and port, along with the `secret_string_wo_version` parameter.

```hcl
secrets = {
  database_credentials = {
    description = "Database connection details"
    secret_key_value = {
      username = "admin"
      password = var.db_password
      host     = "db.example.com"
      port     = "5432"
    }
    secret_string_wo_version = 1
  }
}
```

--------------------------------

### Create Key/Value Secrets with Terraform

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

This configuration demonstrates creating key/value secrets. It allows defining multiple key-value pairs within a single secret and optionally applying tags at the secret level.

```hcl
module "secrets-manager-2" {
  source = "lgallard/secrets-manager/aws"

  secrets = {
    secret-kv-1 = {
      description = "This is a key/value secret"
      secret_key_value = {
        key1 = "value1"
        key2 = "value2"
      }
      recovery_window_in_days = 7
    },
    secret-kv-2 = {
      description = "Another key/value secret"
      secret_key_value = {
        username = "user"
        password = "topsecret"
      }
      tags = {
        app = "web"
      }
      recovery_window_in_days = 7
    },
  }

  tags = {
    Owner       = "DevOps team"
    Environment = "dev"
    Terraform   = true
  }
}
```

--------------------------------

### Define Secrets as List (Before 0.5.0)

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

This is how secrets were defined using a list in versions prior to 0.5.0. This format is no longer supported and will cause secrets to be recreated if changed.

```hcl
secrets = [
    {
      name                    = "secret-1"
      description             = "My secret 1"
      recovery_window_in_days = 7
      secret_string           = "This is an example"
    },
  ]
```

--------------------------------

### Terraform Locals for Resource Conditions and Data Processing

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Organize locals to define resource creation conditions, process data, and create validation helpers for clarity and reusability within Terraform configurations.

```hcl
locals {
  # Resource creation conditions
  should_create_secret = var.enabled && var.secret_name != null
  should_create_replica = local.should_create_secret && length(var.replica_regions) > 0
  
  # Data processing
  secrets = concat(local.secret, var.secrets)
  
  # Validation helpers
  rotation_requirements_met = var.rotation_enabled && var.rotation_lambda_arn != null
}
```

--------------------------------

### Use Ephemeral Passwords with For_each

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/README.md

This solution uses direct AWS resources instead of the module wrapper to handle ephemeral `random_password` resources with `for_each` patterns, overcoming Terraform limitations where module variables cannot accept ephemeral values with `for_each`.

```hcl
ephemeral "random_password" "db_passwords" {
  for_each = var.db_users
  length   = 24
  special  = true
}

resource "aws_secretsmanager_secret_version" "db_secret_versions" {
  for_each = var.db_users
  secret_id = aws_secretsmanager_secret.db_secrets[each.key].id
  
  secret_string_wo = jsonencode({
    password = ephemeral.random_password.db_passwords[each.key].result
    username = each.key
    # ... other fields
  })
  
  secret_string_wo_version = 1
}
```

--------------------------------

### Generate Random Password for Ephemeral Secrets

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Integrate with the `random_password` resource to dynamically generate ephemeral secrets like database passwords. This ensures strong, unique credentials.

```hcl
# Generate ephemeral password
ephemeral "random_password" "db_password" {
  length  = 16
  special = true
}

# Example usage within secrets module (assuming db_password is a variable)
# module "secrets" {
#   ... 
#   secrets = {
#     db_password = {
#       description              = "Database password (ephemeral)"
#       secret_string            = random_password.db_password.result
#       secret_string_wo_version = 1
#     }
#   }
#   ...
# }
```

--------------------------------

### Configure Rotating Secret in Ephemeral Mode

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Set up auto-rotating secrets, such as database passwords, in ephemeral mode. Specify the rotation Lambda ARN and the rotation interval in days.

```hcl
rotate_secrets = {
  rotating_password = {
    description              = "Auto-rotating database password"
    secret_string            = var.initial_password
    secret_string_wo_version = 1
    rotation_lambda_arn      = var.rotation_lambda_arn
    automatically_after_days = 30
  }
}
```

--------------------------------

### Use Ephemeral Password in Secret

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Configure a secret to use an ephemeral, randomly generated password. Ensure the `ephemeral` resource is defined and referenced correctly.

```hcl
module "secrets_manager" {
  source = "lgallard/secrets-manager/aws"
  
  ephemeral = true
  
  secrets = {
    database_password = {
      description              = "Random database password (ephemeral)"
      secret_string            = ephemeral.random_password.db_password.result
      secret_string_wo_version = 1
    }
  }
}
```

--------------------------------

### Security Best Practices with Ephemeral Mode and KMS

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Configure sensitive secrets using ephemeral mode and KMS encryption. Mark input variables as sensitive and specify a `kms_key_id` for enhanced security.

```hcl
# Use sensitive variables for input
variable "database_password" {
  description = "Database password"
  type        = string
  sensitive   = true  # Mark as sensitive
}

# Enable ephemeral mode for sensitive secrets
module "secrets" {
  source = "lgallard/secrets-manager/aws"
  
  ephemeral = true
  
  secrets = {
    db_password = {
      description              = "Database password (ephemeral)"
      secret_string            = var.database_password
      secret_string_wo_version = 1
      kms_key_id              = aws_kms_key.secrets_key.arn  # Use KMS encryption
    }
  }
  
  tags = {
    Security    = "high"
    Compliance  = "required"
  }
}
```

--------------------------------

### Non-working ephemeral pattern

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/ephemeral-limitations.md

This pattern demonstrates a user's desired but non-functional approach to passing ephemeral values to a module.

```hcl
# THIS PATTERN DOES NOT WORK:
ephemeral "random_password" "db_passwords" {
  for_each = var.db_users  # Creates ephemeral passwords
}

module "db_users_secrets_manager" {
  ephemeral = true
  rotate_secrets = {
    for username, role in var.db_users : "db-${var.name}-${username}" => {
      password = ephemeral.random_password.db_passwords[username].result  # ❌ Cannot pass ephemeral to module
    }
  }
}
```

--------------------------------

### Configure String Secret in Ephemeral Mode

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Define a string secret with ephemeral mode enabled. Ensure `secret_string_wo_version` is set to a positive integer to manage updates.

```hcl
secrets = {
  api_token = {
    description              = "API authentication token"
    secret_string            = var.api_token
    secret_string_wo_version = 1
  }
}
```

--------------------------------

### Address Rotation Lambda Missing Error

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Resolves 'Rotation Lambda Missing Error' by providing a valid `rotation_lambda_arn` when using `rotate_secrets`, ensuring the Lambda function exists and has correct permissions.

```text
Error: All rotate_secrets must have a valid rotation_lambda_arn specified.
**Solution**: When using `rotate_secrets`, always provide a valid `rotation_lambda_arn`. The Lambda function must exist and have proper permissions.
```

--------------------------------

### Before Migration to Ephemeral Secrets

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/ephemeral/README.md

This is the configuration before migrating to ephemeral secrets. It uses regular secrets where sensitive values might be stored in the Terraform state file.

```hcl
module "secrets" {
  source = "../../"
  
  secrets = {
    db_password = {
      description = "Database password"
      secret_string = var.db_password
    }
  }
}
```

--------------------------------

### Define Secrets as Map (0.5.0+)

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

After version 0.5.0, secrets must be defined as a map where the map key is the secret name. The `name` field within the map is no longer required.

```hcl
secrets = {
    secret-1 = {
      description             = "My secret 1"
      recovery_window_in_days = 7
      secret_string           = "This is an example"
    },
  }
```

--------------------------------

### Terraform Module Configuration: Standard Mode

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Standard configuration for the secrets-manager module, where secrets are stored in Terraform state. This is the default behavior.

```hcl
module "secrets_manager" {
  source = "lgallard/secrets-manager/aws"
  
  secrets = {
    database_password = {
      description   = "Database password"
      secret_string = var.db_password
    }
  }
}
```

--------------------------------

### Resolve Recovery Window Validation Error

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Addresses 'Recovery Window Validation Error' by setting `recovery_window_in_days` to `0` for immediate deletion or a value between `7` and `30` days.

```text
Error: Recovery window must be 0 (for immediate deletion) or between 7 and 30 days.
**Solution**: Set `recovery_window_in_days` to either `0` or a value between `7` and `30`.
```

--------------------------------

### Correct KMS Key Format Error

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Fixes 'KMS Key Format Error' by ensuring the KMS key ID follows a valid ARN, alias, or UUID format.

```text
Error: KMS key ID must be a valid KMS key ARN, alias, or key ID format.
**Solution**: Ensure your KMS key follows one of these formats:
- `arn:aws:kms:region:account:key/key-id`
- `alias/key-alias`
- `key-id` (UUID format)
```

--------------------------------

### Create Secret with Resource Policy

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Define a secret with a resource policy to control access. The policy is defined using an IAM policy document data source.

```hcl
data "aws_iam_policy_document" "secret_policy" {
  statement {
    sid    = "AllowApplicationAccess"
    effect = "Allow"
    
    principals {
      type        = "AWS"
      identifiers = ["arn:aws:iam::123456789012:role/MyApplicationRole"]
    }
    
    actions   = ["secretsmanager:GetSecretValue"]
    resources = ["*"]
  }
}

module "secrets-manager-policy" {
  source = "lgallard/secrets-manager/aws"

  secrets = {
    app-config = {
      description   = "Application configuration with resource policy"
      secret_string = jsonencode({
        api_key = "secret-api-key"
        config  = "production-config"
      })
      policy                  = data.aws_iam_policy_document.secret_policy.json
      recovery_window_in_days = 14
    }
  }
}
```

--------------------------------

### Terraform Provider Configuration

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Specify the required Terraform version and the AWS provider with its version constraint. Adjust versions based on project requirements and compatibility.

```hcl
terraform {
  required_version = ">= 1.0"
  
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0"

    }
  }
}
```

--------------------------------

### Configure Cross-Region Secret Replication

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Set up a secret to be replicated across multiple AWS regions. Specify KMS keys for encryption in each replica region and optionally force overwrite.

```hcl
module "secrets-manager-replication" {
  source = "lgallard/secrets-manager/aws"

  secrets = {
    global-config = {
      description   = "Global configuration replicated across regions"
      secret_string = "global-configuration-data"
      
      replica_regions = {
        "us-west-2" = "arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012"
        "eu-west-1" = "arn:aws:kms:eu-west-1:123456789012:key/87654321-4321-4321-4321-210987654321"
      }
      
      force_overwrite_replica_secret = true
      recovery_window_in_days        = 7
    }
  }

  tags = {
    ReplicationEnabled = "true"
    GlobalResource     = "true"
  }
}
```

--------------------------------

### Migrate Terraform State Object (Single Secret)

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Use this command to move a single secret version object in your Terraform state file from the old list index format to the new map key format.

```bash
terraform state mv 'module.secrets-manager-1.aws_secretsmanager_secret_version.sm-sv[0]' 'module.secrets-manager-1.aws_secretsmanager_secret_version.sm-sv["secret-1"]'
```

--------------------------------

### Terraform Module Configuration: Ephemeral Mode

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/CLAUDE.md

Configure the secrets-manager module for ephemeral mode to prevent sensitive data from being stored in Terraform state files. Requires Terraform 1.11+ and `secret_string_wo_version`.

```hcl
module "secrets_manager" {
  source = "lgallard/secrets-manager/aws"
  
  # Enable ephemeral mode
  ephemeral = true
  
  secrets = {
    database_password = {
      description              = "Database password (ephemeral)"
      secret_string            = var.db_password
      secret_string_wo_version = 1  # Required for ephemeral mode
    }
  }
}
```

--------------------------------

### Configure Secrets Manager Rotation with Terraform

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/examples/rotation/README.md

This Terraform configuration defines secrets to be rotated automatically. It specifies the rotation Lambda ARN and recovery window for each secret. Ensure the Lambda ARN points to a valid rotation function.

```hcl
module "secrets-manager-4" {

  #source = "lgallard/secrets-manager/aws"
  source = "../../"

  rotate_secrets = {
    secret-rotate-1 = {
      description             = "This is a secret to be rotated by a lambda"
      secret_string           = "This is an example"
      rotation_lambda_arn     = "arn:aws:lambda:us-east-1:123455678910:function:lambda-rotate-secret"
      recovery_window_in_days = 15
    },
    secret-rotate-2 = {
      description             = "This is another secret to be rotated by a lambda"
      secret_string           = "This is another example"
      rotation_lambda_arn     = "arn:aws:lambda:us-east-1:123455678910:function:lambda-rotate-secret"
      recovery_window_in_days = 7
    },
  }

  tags = {
    Owner       = "DevOps team"
    Environment = "dev"
    Terraform   = true
  }

}
```

--------------------------------

### Create Plain Text Secrets with Terraform

Source: https://github.com/lgallard/terraform-aws-secrets-manager/blob/master/README.md

Use this snippet to create plain text secrets in AWS Secrets Manager. Specify descriptions, recovery windows, and the secret string content.

```hcl
module "secrets-manager-1" {
  source = "lgallard/secrets-manager/aws"

  secrets = {
    secret-1 = {
      description             = "My secret 1"
      recovery_window_in_days = 7
      secret_string           = "This is an example"
    },
    secret-2 = {
      description             = "My secret 2"
      recovery_window_in_days = 7
      secret_string           = "This is another example"
    }
  }

  tags = {
    Owner       = "DevOps team"
    Environment = "dev"
    Terraform   = true
  }
}
```