Introduction
Terraform codifies infrastructure as code while AWS Secrets Manager provides a managed store for sensitive credentials. Combining the two allows infrastructure definitions to reference secrets without hardcoding values, but the integration introduces distinct security considerations around state storage, secret values, and provider interactions. The workflow spans secret creation, versioning, retrieval, rotation, and access control, all of which must be handled with awareness of how Terraform persists information and how Secrets Manager encrypts data at rest.
How AWS Secrets Manager and Terraform Interact
AWS Secrets Manager is a service for securely encrypting, storing, and rotating credentials for databases and other services. It helps replace hardcoded credentials in code, including passwords, with an API call to retrieve the secret programmatically. In Secrets Manager, a secret consists of credentials information which is the secret value and its metadata. The secret value can be binary, a single string, or multiple strings.
Secrets Manager uses 256-bit Advanced Encryption Standard AES symmetric data keys to encrypt secret values.
You can access and work with Secrets Manager by using any of the following approaches:
- Secrets Manager console
- Command line tools
- AWS SDKs
- HTTPS Query API, also called the Secrets Manager API
- AWS Secrets Manager endpoints
Terraform stores information about your managed AWS infrastructure and its configurations. This information is called the state. By default, the state is stored in a local file named Terraform.tfstate. This file is in JSON format, and Terraform might store sensitive data in this state file in plain text.
When secret values are managed with Terraform, they can still be stored in Terraform state, so protect your state backend carefully or use write-only attributes where available.
Secret Creation and Value Storage in Terraform
The simplest case is creating a secret and storing a value.
hcl
resource "aws_secretsmanager_secret" "database" {
name = "production/database/credentials"
description = "Database credentials for the production environment"
recovery_window_in_days = 30
tags = {
Environment = "production"
ManagedBy = "terraform"
}
}
Store the secret value with a separate version resource.
hcl
resource "aws_secretsmanager_secret_version" "database" {
secret_id = aws_secretsmanager_secret.database.id
secret_string = jsonencode({
username = "admin"
password = random_password.database.result
engine = "postgres"
host = aws_db_instance.main.address
port = 5432
dbname = "myapp"
})
}
Generate a random password dynamically.
hcl
resource "random_password" "database" {
length = 32
special = true
override_special = "!#$%&*()-_=+[]{}<>:?"
}
Managing Terraform secrets securely is a key part of infrastructure automation. Terraform often requires sensitive information such as API keys, passwords, and cloud credentials to create and manage resources.
To create and manage secrets dynamically, three key Terraform resources are used:
- random_password
- awssecretsmanagersecret
- awssecretsmanagersecret_version
random_password { } generates a random password dynamically.
hcl
resource "random_password" "db_password"{
length = 16
special = true
override_special = "_!%^"
}
aws_secretsmanager_secret { } defines secret name in AWS secrets manager.
Retrieving Secrets and Data Sources
Read existing secrets using data sources. Secret values managed with Terraform can still be stored in Terraform state, so protect your state backend carefully or use write-only attributes where available. This guide covers the full range of Secrets Manager operations in Terraform.
Secrets protect sensitive information about the organization’s infrastructure and operations. This includes system passwords, encryption keys, APIs, service certificates, and other forms of confidential data. Secrets secure such information by preventing unauthorized access, data breaches, or critical security incidents.
Secrets are used in various phases of Terraform provisioning for activities like:
- Securing access to services provided by cloud platforms such as AWS, Azure, and Google Cloud
- Securing access to active databases that contain sensitive data, such as customer information, financial records, etc.
- Setting up authentication through API keys, OAuth tokens, and SSL certificates to allow the user access to applications
- Setting up access to network components such as routers, switches, and firewalls
Terraform uses secrets to automate infrastructure provisioning activities similar to the ones listed above.
Protecting Terraform State and Sensitive Variables
Terraform often requires sensitive information such as API keys, passwords, and cloud credentials to create and manage resources. Managing these secrets securely is a key part of infrastructure automation.
Mark variables as sensitive to prevent their values from being displayed in the CLI output or logs.
hcl
variable "db-password"{
description= "Database password"
type = "string"
sensitive = true
}
Although Terraform hides sensitive values in logs, they are still stored in the state file, so we need to secure the state file properly with remote backend like S3 + DynamoDB with encryption at rest SSE.
Terraform provides multiple mechanisms for managing secrets securely, including environment variables, secret management tools such as HashiCorp Vault and AWS Secrets Manager, or encrypted storage solutions.
If secrets are exposed or stored in plaintext directly inside Terraform configuration, it creates serious risks:
- Unauthorized individuals with access to Git repos, CI/CD logs, or state files can retrieve secrets.
- It becomes nearly impossible to audit who accessed sensitive values.
- Infrastructure security is compromised if API keys or access credentials are leaked.
Prerequisites:
- Terraform CLI on your local machine.
- Access credentials for your target cloud provider.
- A remote backend such as S3, GCS, or Azure Storage for securely storing Terraform state.
Module-Based Secrets Manager Workflows
Terraform modules provide reusable patterns for Secrets Manager.
Terraform module to create Amazon Secrets Manager resources with comprehensive input validation and advanced features.
AWS Secrets Manager helps you protect secrets needed to access your applications, services, and IT resources. The service enables you to easily rotate, manage, and retrieve database credentials, API keys, and other secrets throughout their lifecycle.
Features of a comprehensive module:
- Input Validation: Comprehensive validation for all variables to prevent configuration errors
- Type Safety: Strongly typed variables with structured object definitions
- Secret Rotation: Built-in support for automatic secret rotation with Lambda functions
- Cross-Region Replication: Support for replicating secrets across AWS regions
- KMS Encryption: Support for customer-managed KMS keys
- Resource Policies: Attach custom IAM policies to secrets
- Flexible Secret Types: Support for plain text, key/value pairs, and binary secrets
Minimum version requirements:
| Component | Minimum version | Notes |
|---|---|---|
| Terraform | >= 1.11.0 | Required for ephemeral resources and write-only arguments. |
| AWS provider | >= 6.50.0 | Required so the module can use awssecretsmanagersecretversion.secretstringwo / secretstringwoversion safely. Version 6.50.0 includes Secrets Manager fixes for final-plan consistency, creation eventual consistency, empty versionstages, and switching between secretstring and secretstringwo. |
The module declares the AWS provider minimum at the root, so all usage modes use the same compatibility policy.
Terraform module which creates AWS Secrets Manager resources.
Example usage with name prefix and policy.
hcl
module "secrets_manager" {
source = "terraform-aws-modules/secrets-manager/aws"
name_prefix = "example"
description = "Example Secrets Manager secret"
recovery_window_in_days = 30
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 = ["*"]
}
}
create_random_password = true
random_password_length = 64
random_password_override_special = "!@#$%^&*()_+"
tags = {
Environment = "Development"
Project = "Example"
}
}
Example with rotation enabled.
hcl
module "secrets_manager" {
source = "terraform-aws-modules/secrets-manager/aws"
name_prefix = "rotated-example"
description = "Rotated example Secrets Manager secret"
recovery_window_in_days = 7
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
}
}
}
External Secret Management and Terraform Variable Handling
Terraform can fetch and manage secrets stored in external secret management services such as Hashicorp vault, AWS secrets manager, Azure key vault etc.
Let's look at how to generate and store secrets securely using AWS Secrets Manager in a Terraform project.
Terraform offers many different methods for managing these secrets, such as using environment variables, leveraging secret management tools like HashiCorp Vault and AWS Secrets Manager, or encrypting sensitive data.
Where are the secrets used in Terraform?
Secrets protect sensitive information about the organization’s infrastructure and operations. This includes system passwords, encryption keys, APIs, service certificates, and other forms of confidential data.
Secrets are used in various phases of Terraform provisioning for activities like:
- Securing access to services provided by cloud platforms such as AWS, Azure, and Google Cloud
- Securing access to active databases that contain sensitive data, such as customer information, financial records, etc.
- Setting up authentication through API keys, OAuth tokens, and SSL certificates to allow the user access to applications
- Setting up access to network components such as routers, switches, and firewalls
Terraform uses secrets to automate infrastructure provisioning activities similar to the ones listed above.
Terraform secrets are required across multiple stages of provisioning and operations:
- Accessing cloud services: AWS, Azure, and GCP credentials are needed to authenticate against APIs.
- Connecting to databases: Credentials are required to set up and manage sensitive data stores.
- Configuring networking components: Firewalls, routers, and SSL certificates often require sensitive keys.
- Automating deployments: Secrets like OAuth tokens or SSH keys allow access to applications and services.
There are multiple ways to manage Terraform secrets securely.
Summary of Security Considerations
AWS Secrets Manager encrypts secret values with 256-bit AES symmetric data keys. Terraform state may contain sensitive data in plain text by default. Using write-only arguments, remote encrypted backends, and variable sensitivity reduces exposure. Modules provide validation, type safety, rotation, cross-region replication, KMS encryption, resource policies, and flexible secret types. Minimum Terraform 1.11.0 and AWS provider 6.50.0 are required for safe write-only usage and final-plan consistency.
The integration pattern is to let Terraform create the secret resource, generate values with randompassword, store them via awssecretsmanagersecretversion, and reference them in other resources via data sources without persisting cleartext in configuration files.
Conclusion
Using AWS Secrets Manager with Terraform shifts secret storage out of configuration files and into a managed encrypted service while keeping the secret lifecycle under infrastructure code control. The critical risk remains Terraform state, which can hold secret values in plain text. Protecting state with remote encrypted backends, using sensitive variables, and leveraging write-only attributes where available mitigates this risk. Module-based approaches add input validation, rotation, replication, and policy attachment, but they still require matching Terraform and AWS provider minimum versions for eventual consistency and safe secret string handling. Combining programmatic secret creation with retrieval via data sources provides a clean workflow where infrastructure code creates secrets and references them without hardcoding values, provided state and access controls are treated as part of the secret boundary.