Sensitive variables in Terraform - Deep Dive

Overview - Sensitive variables

What is it?

Sensitive variables in Terraform are special inputs that hold secret or private information, like passwords or API keys. They help keep this data hidden when Terraform shows outputs or logs. This prevents accidental exposure of secrets during infrastructure deployment. Sensitive variables ensure that private data stays secure while managing cloud resources.

Why it matters

Without sensitive variables, secret information would appear openly in Terraform outputs, logs, or state files, risking leaks to unauthorized people. This could lead to security breaches, data loss, or unauthorized access to cloud resources. Sensitive variables protect secrets, making infrastructure safer and trustworthy.

Where it fits

Before learning sensitive variables, you should understand basic Terraform variables and how Terraform configurations work. After this, you can learn about secret management tools, environment variables, and secure state storage to deepen your security skills.

Mental Model

Core Idea

Sensitive variables are like sealed envelopes that keep secret information hidden during Terraform runs to protect privacy and security.

Think of it like...

Imagine sending a letter with a secret message inside a sealed envelope. Everyone can see the envelope but cannot read the message unless they open it carefully. Sensitive variables act like that sealed envelope, hiding secrets from plain view.

Terraform Configuration
┌─────────────────────────────┐
│ Variables                   │
│ ┌─────────────────────────┐ │
│ │ Normal Variables        │ │
│ │ (shown openly)          │ │
│ └─────────────────────────┘ │
│ ┌─────────────────────────┐ │
│ │ Sensitive Variables     │ │
│ │ (hidden in outputs/logs)│ │
│ └─────────────────────────┘ │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Terraform Variables

Concept: Learn what variables are in Terraform and how they store input values.

Terraform variables let you pass values into your infrastructure code. For example, you can define a variable for a server name or region. Variables make your code flexible and reusable by changing inputs without editing the code itself.

Result

You can customize your infrastructure by changing variable values without rewriting code.

Knowing variables is essential because sensitive variables are a special type of these inputs designed to protect secrets.

2

Foundation

Why Secrets Need Protection

Concept: Understand why secret data like passwords must be kept hidden in infrastructure code.

Secrets such as passwords, API keys, or tokens grant access to systems. If exposed, anyone could misuse them. Terraform shows variable values in logs and outputs by default, which risks leaking secrets if not protected.

Result

You realize that exposing secrets can cause security breaches and must be avoided.

Understanding the risk of exposure motivates using sensitive variables to keep secrets safe.

3

Intermediate

Marking Variables as Sensitive

🤔Before reading on: do you think marking a variable as sensitive hides it everywhere automatically? Commit to your answer.

Concept: Learn how to declare a variable as sensitive in Terraform and what effect it has.

In Terraform, you mark a variable as sensitive by adding sensitive = true in its declaration. For example: variable "db_password" { type = string sensitive = true } This tells Terraform to hide the value in outputs and logs.

Result

Terraform will not show the sensitive variable's value in CLI output or logs, replacing it with .

Knowing how to mark variables as sensitive helps prevent accidental secret leaks during Terraform runs.

4

Intermediate

Handling Sensitive Variables in Outputs

🤔Before reading on: do you think sensitive variables can be safely outputted in Terraform? Commit to your answer.

Concept: Understand how Terraform treats sensitive variables when used in output blocks.

If you output a sensitive variable, Terraform hides its value by default. For example: output "db_password" { value = var.db_password sensitive = true } This prevents the secret from appearing in the output, showing instead.

Result

Outputs containing sensitive variables do not reveal secret values, protecting them from exposure.

Knowing this prevents accidental secret exposure when sharing Terraform outputs with others.

5

Intermediate

Sensitive Variables and State Files

Concept: Learn how sensitive variables are stored in Terraform state files and the implications.

Terraform stores all variable values, including sensitive ones, in the state file. This file is needed to track resources but can contain secrets in plain text. Therefore, securing state files (e.g., using remote backends with encryption) is critical to protect sensitive data.

Result

You understand that marking variables sensitive hides them in outputs but not in state files, so state security is vital.

Knowing this helps you plan secure storage for Terraform state to avoid secret leaks.

6

Advanced

Using Sensitive Variables with Modules

🤔Before reading on: do you think sensitive variables keep their sensitivity when passed between modules? Commit to your answer.

Concept: Explore how sensitive variables behave when passed as inputs or outputs in Terraform modules.

When passing sensitive variables to modules, the sensitivity flag is preserved if declared properly. For example, a module input variable marked sensitive will keep that property. However, if a module output exposes a sensitive variable without marking it sensitive, the secret may leak.

Result

You learn to carefully mark sensitive variables in module inputs and outputs to maintain secrecy across modules.

Understanding this prevents secret leaks in complex Terraform projects using modules.

7

Expert

Limitations and Workarounds of Sensitive Variables

🤔Before reading on: do you think sensitive variables fully secure secrets in all Terraform contexts? Commit to your answer.

Concept: Discover the limits of sensitive variables and best practices to handle secrets securely in Terraform.

Sensitive variables hide secrets in outputs and logs but do not encrypt them in state files or protect them from all exposure. For stronger security, use dedicated secret managers (like AWS Secrets Manager) and inject secrets at runtime. Also, avoid printing sensitive data in debug logs or error messages.

Result

You realize sensitive variables are one layer of security but must be combined with other secret management strategies.

Knowing these limits helps you design secure infrastructure that truly protects secrets in production.

Under the Hood

Terraform marks sensitive variables internally with a flag that tells the CLI and output renderer to replace the actual value with a placeholder like . However, the real value is still stored in the state file in plain text because Terraform needs it to manage resources. Sensitive flags propagate through variable and output declarations to control visibility during plan and apply phases.

Why designed this way?

Terraform was designed to balance usability and security. Hiding secrets in outputs prevents accidental leaks during normal use, while storing them in state files allows Terraform to track resource dependencies. Encrypting state files is left to backend storage solutions to keep Terraform flexible and compatible with many environments.

Terraform Run
┌───────────────────────────────┐
│ Variable Declaration           │
│ ┌───────────────────────────┐ │
│ │ sensitive = true           │ │
│ └───────────────────────────┘ │
│               │               │
│               ▼               │
│ Terraform Core                │
│ ┌───────────────────────────┐ │
│ │ Replace value with <sensitive>│
│ │ in CLI outputs and logs    │ │
│ └───────────────────────────┘ │
│               │               │
│               ▼               │
│ State File (plain text)       │
│ ┌───────────────────────────┐ │
│ │ Stores actual secret value │ │
│ └───────────────────────────┘ │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does marking a variable sensitive encrypt it in the Terraform state file? Commit yes or no.

Common Belief: Marking a variable as sensitive encrypts it everywhere, including the state file.

Reality: Sensitive variables are hidden in outputs and logs but stored in plain text in the state file.

Why it matters: Assuming encryption leads to lax state file security, risking secret exposure if the state file is accessed.

Quick: Can you safely output a sensitive variable without marking the output sensitive? Commit yes or no.

Common Belief: Sensitive variables remain hidden even if output blocks don't mark them sensitive.

Reality: If the output block is not marked sensitive, Terraform will show the secret value, exposing it.

Why it matters: This can cause accidental secret leaks when sharing outputs with others.

Quick: Do sensitive variables protect secrets from all Terraform logs and debug messages? Commit yes or no.

Common Belief: Sensitive variables hide secrets in all logs and debug outputs automatically.

Reality: Some debug logs or error messages may still reveal sensitive data if not handled carefully.

Why it matters: Believing otherwise can cause secret leaks during troubleshooting or verbose logging.

Quick: When passing sensitive variables between modules, do they always keep their sensitivity? Commit yes or no.

Common Belief: Sensitive variables automatically keep their sensitivity across all module boundaries.

Reality: Sensitivity must be explicitly declared in module inputs and outputs to maintain secrecy.

Why it matters: Failing to declare sensitivity in modules can expose secrets unintentionally.

Expert Zone

1

Terraform's sensitive flag only affects CLI output and plan/apply display, not the underlying data storage or transmission.

2

Sensitive variables can cause Terraform plans to show placeholders, which may confuse debugging if the real value is needed.

3

Combining sensitive variables with remote state backends that encrypt data at rest is essential for end-to-end secret protection.

When NOT to use

Sensitive variables are not a full secret management solution. For highly sensitive data, use dedicated secret managers like HashiCorp Vault or cloud provider secret services. Avoid storing secrets directly in Terraform variables when possible.

Production Patterns

In production, teams use sensitive variables to hide secrets in Terraform outputs while integrating with external secret stores for injection. They secure state files with encryption and access controls, and carefully mark module inputs/outputs to maintain sensitivity across large codebases.

Connections

Secret Management

Sensitive variables build on secret management principles by hiding secrets in outputs but rely on secret managers for full protection.

Understanding sensitive variables helps grasp why secret managers are needed to securely store and inject secrets beyond Terraform's scope.

Encryption

Sensitive variables hide secrets visually but do not encrypt data at rest, unlike encryption technologies.

Knowing this distinction clarifies the role of encryption in protecting data stored in Terraform state files.

Privacy in Communication

Sensitive variables relate to privacy concepts by controlling what information is visible to others during communication (Terraform runs).

This connection shows how privacy principles apply in cloud infrastructure, similar to how people protect private information in conversations.

Common Pitfalls

#1 Exposing secrets by outputting sensitive variables without marking outputs sensitive.

Wrong approach:

output "db_password" {
value = var.db_password
}

Correct approach:

output "db_password" {
value = var.db_password
sensitive = true
}

Root cause:

Not understanding that outputs must also be marked sensitive to hide secret values.

#2 Assuming sensitive variables encrypt secrets in the state file.

Wrong approach:

variable "api_key" {
type = string
sensitive = true
}
# No additional state security

Correct approach:

# Use remote backend with encryption
terraform {
backend "s3" {
bucket = "my-terraform-state"
key = "state.tfstate"
region = "us-east-1"
encrypt = true
}
}

Root cause:

Believing sensitive = true alone protects secrets everywhere.

#3 Passing sensitive variables to modules without declaring sensitivity on inputs and outputs.

Wrong approach:

module "db" {
source = "./db_module"
db_password = var.db_password
}

# db_module variables.tf
variable "db_password" {
type = string
# missing sensitive = true
}

# db_module outputs.tf
output "db_password" {
value = var.db_password
# missing sensitive = true
}

Correct approach:

module "db" {
source = "./db_module"
db_password = var.db_password
}

# db_module variables.tf
variable "db_password" {
type = string
sensitive = true
}

# db_module outputs.tf
output "db_password" {
value = var.db_password
sensitive = true
}

Root cause:

Not propagating sensitivity flags in module variable and output declarations.

Key Takeaways

Sensitive variables in Terraform hide secret values in outputs and logs but do not encrypt them in state files.

Marking variables and outputs as sensitive is essential to prevent accidental secret exposure during Terraform runs.

Terraform state files can contain secrets in plain text, so securing state storage is critical for overall secret protection.

Passing sensitive variables through modules requires explicit sensitivity declarations to maintain secrecy.

Sensitive variables are one part of secret management; combining them with external secret stores and encrypted state backends ensures stronger security.