Introduction

Terraform can read a secret from AWS Secrets Manager, but the important detail is not just how to fetch it. The important detail is what happens afterward: once Terraform reads a secret value, that value can participate in state unless you design around that fact carefully.

The Standard Data-Source Pattern

The common workflow uses two data sources:

• one for the secret metadata
• one for the current secret value

1provider "aws" {
2  region = "us-east-1"
3}
4
5data "aws_secretsmanager_secret" "app" {
6  name = "prod/app-config"
7}
8
9data "aws_secretsmanager_secret_version" "current" {
10  secret_id = data.aws_secretsmanager_secret.app.id
11}
12
13output "raw_secret" {
14  value     = data.aws_secretsmanager_secret_version.current.secret_string
15  sensitive = true
16}

That is the basic retrieval flow. The secret_string attribute contains the plaintext secret value if the secret is stored as text.

Reading Structured Secrets

Many Secrets Manager values are JSON documents rather than one raw string. In that case, decode the JSON before using individual fields.

1locals {
2  app_secret = jsondecode(data.aws_secretsmanager_secret_version.current.secret_string)
3}
4
5output "db_username" {
6  value     = local.app_secret.username
7  sensitive = true
8}

This is a clean way to access fields such as username, password, host, or token from one secret bundle.

Using the Secret in a Resource

You can wire the decoded value into a resource attribute.

1resource "aws_db_instance" "example" {
2  identifier             = "app-db"
3  engine                 = "postgres"
4  instance_class         = "db.t3.micro"
5  allocated_storage      = 20
6  username               = local.app_secret.username
7  password               = local.app_secret.password
8  skip_final_snapshot    = true
9}

This works, but it also means Terraform is now handling the secret as part of provisioning logic, which has security implications.

The State File Warning Is Real

Marking an output as sensitive = true only affects how Terraform displays it in normal CLI output. It does not mean Terraform forgets the value internally. If Terraform reads the secret, the value may still appear in state or in resource arguments derived from it.

That means you should treat the Terraform backend as sensitive infrastructure. Restrict access to it, encrypt it, and avoid reading secrets in Terraform unless Terraform truly needs the plaintext value.

IAM and KMS Permissions

Retrieval also depends on AWS permissions. The IAM identity running Terraform typically needs permission to describe the secret and get its current value. If the secret is encrypted with a customer-managed KMS key, the identity may also need decrypt permission for that key.

When this pattern fails, the issue is often IAM or KMS policy, not HCL syntax.

When Not to Retrieve the Secret in Terraform

A common better design is to give the application or runtime environment permission to fetch the secret directly at runtime. That avoids copying the secret through Terraform at all.

Terraform retrieval makes sense when the infrastructure resource itself requires the plaintext during provisioning. It is a less attractive pattern when the secret is really only an application runtime concern.

Newer Terraform Features Do Not Remove All Risk

Recent Terraform features such as ephemeral values and write-only arguments can reduce secret exposure in some workflows when the provider and resource support them. That is useful, but it does not change the general rule: if Terraform must read a secret value, you still need to reason carefully about where that value will live during planning, applying, and state storage.

Common Pitfalls

• Assuming sensitive = true keeps the secret out of state is incorrect.
• Forgetting jsondecode when the secret is structured JSON makes downstream access awkward.
• Debugging HCL when the real problem is missing IAM or KMS permission wastes time.
• Passing secrets through Terraform when the application could fetch them directly increases exposure.
• Treating the backend as ordinary storage is dangerous when it may contain retrieved secrets.

Summary

• Use aws_secretsmanager_secret and aws_secretsmanager_secret_version to read a secret from AWS Secrets Manager.
• Use secret_string for plaintext values and jsondecode for structured JSON secrets.
• Mark outputs as sensitive, but remember that sensitivity does not remove values from state.
• Secure the Terraform backend if Terraform is involved in secret retrieval.
• Prefer runtime secret retrieval when Terraform does not actually need the secret value itself.