August 21, 2026
10 min read
Table of Contents
By Kokil Thapa | Last reviewed: August 2026
Terraform variables, locals, and outputs form the data contract layer of every reusable infrastructure module. Getting these three primitives right determines whether your code is a flexible, composable system or a rigid copy-paste nightmare that breaks on every environment change. This guide covers the practical patterns I use daily when building CI/CD pipelines and automated deployments for clients who need infrastructure that survives team turnover and business pivots.
Quick answer: Terraform variables accept external input with type constraints and validation, locals compute derived values within a module to reduce repetition, and outputs expose specific attributes for downstream consumption. Use variables for configuration, locals for internal logic, and outputs strictly for cross-module dependencies.
How do you choose between Terraform variables, locals, and outputs correctly?
The most common mistake in Terraform modules is misusing these three primitives. The decision framework is straightforward once you understand the data flow direction and mutability rules.
Variables are your module's public API surface. They accept values from callers (root modules, parent modules, CI/CD systems, or tfvars files). Every variable should have an explicit type constraint and, where meaningful, a validation block. Never use a variable just to store a constant — that is what locals are for.
Locals exist to make your module code readable and maintainable. They compute intermediate values, normalize input formats, build complex strings, or implement conditional logic that would otherwise be repeated across multiple resource blocks. Locals cannot be overridden by callers and are invisible outside the module. If you find yourself writing the same expression three times, extract it to a local.
Outputs define what your module promises to provide. Only expose values that downstream modules genuinely need. Every output becomes part of your module's permanent contract — removing or renaming one is a breaking change. In my experience maintaining automated deployment systems, over-exposed outputs create coupling that makes refactoring painful months later.
How do you implement Terraform variable validation and type constraints effectively?
Type constraints catch errors at plan time rather than apply time. Validation blocks enforce business rules that types alone cannot express. Both are non-negotiable in production modules.
Type constraints prevent entire categories of bugs
Always specify explicit types. The primitive types (string, number, bool) cover simple cases. Complex structures require object(), list(), map(), or set() with nested type annotations.
variable "database_config" {
description = "RDS instance configuration"
type = object({
engine = string
engine_version = string
instance_class = string
storage_gb = number
multi_az = optional(bool, false)
tags = optional(map(string), {})
})
validation {
condition = contains(["mysql", "postgres"], var.database_config.engine)
error_message = "Engine must be 'mysql' or 'postgres'."
}
validation {
condition = var.database_config.storage_gb >= 20 && var.database_config.storage_gb <= 65536
error_message = "Storage must be between 20 GB and 65,536 GB."
}
}The optional() modifier (stable since Terraform 1.3, widely used through 2026) eliminates boilerplate null checks. Provide sensible defaults so callers only override what matters for their context. On legal-tech portals I have built, this pattern lets development environments skip multi-AZ while production enables it without separate variable definitions.
Validation blocks encode domain knowledge
Types verify structure; validations verify semantics. Common patterns include:
- Enum enforcement: Restrict strings to known-good values using
contains(). - Range checks: Ensure numeric values fall within provider limits or budget constraints.
- Format validation: Use
regex()for naming conventions, CIDR notation, or ARN patterns. - Cross-variable consistency: Verify related variables agree (e.g., subnet count matches availability zone count).
- Conditional requirements: Require a field only when another field has a specific value using ternary logic inside the condition.
A frequent gotcha: validation conditions can only reference the variable being validated. You cannot cross-validate between two variables directly. Work around this by consolidating related fields into a single object() variable, then validate the object holistically.
Sensitive variables and state security
Mark passwords, API keys, and tokens with sensitive = true. Terraform redacts these from CLI output and logs. However, sensitive values still appear in plaintext in state files. This is why remote state backends with encryption (S3 + KMS, GCS with CMEK, Terraform Cloud) are mandatory for any project handling credentials. For Nepal-based clients concerned about data residency, I discuss these trade-offs explicitly during security planning.
When should you use Terraform locals instead of variables or inline expressions?
Locals solve three specific problems. If your situation does not match one of these, you probably do not need a local.
Normalization and format unification
Callers provide data in inconsistent formats. Locals normalize once, then resources consume clean structures.
locals {
# Normalize tags: merge defaults with caller overrides, enforce lowercase keys
normalized_tags = merge(
{
managed_by = "terraform"
project = var.project_name
environment = var.environment
},
{ for k, v in var.extra_tags : lower(k) => v }
)
# Build consistent naming prefix
name_prefix = "${var.project_name}-${var.environment}"
# Conditional feature flags based on environment
enable_monitoring = var.environment == "production" ? true : false
backup_retention = var.environment == "production" ? 30 : 7
}This pattern keeps resource blocks declarative. The complexity lives in one place where it can be tested and documented.
Complex lookups and transformations
When resource arguments require lookup(), merge(), list comprehensions, or conditional logic that spans multiple lines, extract to a local. Inline ternaries nested inside resource blocks become unreadable fast. A named local acts as documentation: the name explains what the value represents, not just how it is computed.
What locals cannot do
Locals cannot reference themselves cyclically. They cannot accept external overrides. They are re-evaluated on every plan (no memoization across runs). Do not use locals to store secrets — they appear in plan output unless marked sensitive at the variable level. Understanding these boundaries prevents subtle bugs in serverless infrastructure and similar architectures.
How do you design Terraform outputs for safe module composition?
Outputs are contracts. Design them with the same discipline you would apply to a REST API response schema.
| Criterion | Good Output | Bad Output |
|---|---|---|
| Specificity | db_endpoint, db_port | db_instance (entire object) |
| Stability | Attributes unlikely to change structure | Internal implementation details |
| Documentation | Description explains consumer use case | No description or generic label |
| Sensitivity | Passwords marked sensitive = true | Credentials exposed in plain output |
| Necessity | Consumed by at least one known caller | "Might be useful someday" |
Expose minimal, stable attributes
Return specific attributes rather than entire resource objects. When AWS adds a field to an RDS instance response, modules consuming output.db_instance may break if they iterate over all keys. Returning db_endpoint and db_port isolates consumers from provider drift.
output "database_endpoint" {
description = "Hostname and port for application connection strings"
value = aws_db_instance.main.endpoint
}
output "database_connection_string" {
description = "Full PostgreSQL connection URI for application config"
value = "postgresql://${var.db_username}:${var.db_password}@${aws_db_instance.main.endpoint}/${var.db_name}"
sensitive = true
}
output "security_group_id" {
description = "ID of database security group for additional ingress rules"
value = aws_security_group.db.id
}Output dependencies and implicit ordering
Terraform uses output references to infer resource dependencies between modules. If module B consumes module.a.database_endpoint, Terraform guarantees module A's database exists before module B plans. This implicit dependency is usually correct. When you need to enforce ordering without exposing a specific attribute, use depends_on at the module call site rather than creating dummy outputs.
Testing outputs in isolation
Write integration tests (using Terratest or similar) that assert output values match expected patterns. For a VPC module, verify that vpc_cidr output matches the input variable and that private_subnet_ids has the expected count. These tests catch regressions when refactoring internals. On projects where I manage multi-cloud hosting, output tests prevent environment-specific surprises during promotion.
What are the common anti-patterns in Terraform variables, locals, and outputs?
After reviewing dozens of Terraform codebases, these mistakes appear consistently. Avoiding them saves hours of debugging.
- Untyped variables: Omitting
typedefaults toany. Callers pass malformed structures that fail deep inside provider calls with cryptic errors. Always constrain. - Overloaded variables: A single
configmap holding unrelated settings. Split into focused variables with clear names. Autocomplete and documentation improve immediately. - Locals duplicating variables: Creating
local.region = var.regionadds indirection without value. Reference the variable directly unless transformation occurs. - Outputs exposing entire resources: As discussed above, this couples consumers to provider schema versions. Expose only what is needed.
- Missing descriptions: Future maintainers (including yourself) cannot infer intent from names alone. Write descriptions that explain why, not just what.
- Validation without error messages: Bare
condition = ...produces "Invalid value" errors. Always provideerror_messagethat tells the caller exactly how to fix the input. - Sensitive values in non-sensitive outputs: Accidentally leaking passwords through computed outputs. Audit every output for credential paths.
On a recent engagement modernizing a legacy infrastructure codebase, fixing anti-patterns #1 and #4 alone reduced plan-time errors by roughly 60% and made the module library actually reusable across staging and production. The investment in proper typing pays compounding returns.
Practical Checklist for Production Terraform Modules
Before merging any module change, verify:
- Every variable has an explicit
typeconstraint anddescription. - Variables accepting user-provided strings have
validationblocks where semantic rules exist. - Sensitive inputs and outputs are marked
sensitive = true. - Locals are used only for normalization, deduplication, or complex transformations — never as passthrough aliases.
- Outputs expose specific attributes, not whole resources, with descriptions explaining consumer use cases.
- No output references internal resource attributes likely to change with provider updates.
terraform validateandterraform fmt -checkpass cleanly.- Integration tests assert critical output values for at least one representative configuration.
This checklist takes five minutes per module and prevents weeks of downstream pain. Treat it like linting — automate where possible, enforce in CI, and never skip for speed.
Building Maintainable Infrastructure Contracts
Terraform variables, locals, and outputs are not just syntax — they are the interface design language of infrastructure as code. Getting them right separates modules that teams adopt willingly from modules that teams rewrite from scratch. Invest time upfront in type safety, validation, minimal outputs, and clear naming. The payoff is infrastructure that evolves with your business instead of anchoring it to past decisions. If you need help designing or auditing your Terraform module library, reach out to discuss your infrastructure needs.
Frequently Asked Questions
Variables accept external input at runtime via CLI, env vars, or tfvars files. Locals compute derived values internally within a module and cannot be overridden by users.
Use locals for computed transformations, conditional logic, or simplifying complex expressions reused multiple times. Reserve input variables for values that must change per environment or deployment context without modifying code.
Mark the variable with sensitive = true to prevent it from appearing in plan output or logs. Store actual secrets in a vault or encrypted backend, never in committed tfvars files or state.
Yes, but you must mark the output as sensitive = true. Without this flag, Terraform blocks the apply and shows an error to prevent accidental secret exposure in CLI output or remote state backends.
Terraform treats it as required and prompts interactively during plan/apply unless supplied via -var, .tfvars, or environment variable. In CI pipelines, missing required variables cause immediate failure, which is often desirable for enforcing explicit configuration.
Declare input variables inside the child module's main.tf, then assign them explicitly in the parent module block using key-value pairs. Child modules cannot access parent variables directly; all values must be passed through declared inputs to maintain encapsulation and reusability across environments.
Locals are scoped strictly to their defining module and exist only for internal computation. To expose derived values to parent modules or other configurations, declare an output block. This design enforces explicit interfaces and prevents hidden dependencies between infrastructure components.
Use snake_case consistently. Prefix variables by purpose like db_instance_class or vpc_cidr. Avoid generic names like name or id. Outputs should describe what they represent, such as primary_database_endpoint rather than just endpoint. Consistent naming improves readability across large teams and repositories.
Add validation blocks inside variable declarations with condition and error_message arguments. Conditions use built-in functions like can, regex, or contains to enforce rules. Validation runs during plan before any resources are created, catching misconfigurations early and providing clear feedback instead of cryptic provider errors during apply.
No. Default values must be literal constants known at parse time. You cannot call functions, reference other variables, or use data sources in defaults. Compute dynamic values using locals instead, referencing the variable as needed. This separation ensures predictable parsing and avoids circular dependency issues during initialization.
Create separate tfvars files like dev.tfvars and prod.tfvars, passing them via -var-file during execution. Alternatively, use workspace-specific auto.tfvars or environment variables prefixed with TF_VAR_. This keeps module code identical across environments while allowing safe, auditable configuration drift managed through version control.
This error occurs when code references var.name without a corresponding variable block declaration in the same module. Check spelling, ensure the variable block exists in the correct module scope, and verify you are not accidentally referencing a parent variable. Run terraform validate to catch these issues before planning.
Outputs persist in state until all dependent resources are destroyed. If an output references a resource being removed, Terraform updates or removes the output value accordingly. Cross-module references to destroyed outputs cause failures, so design dependencies carefully and consider using null resources or explicit lifecycle management for cleanup ordering.
No. Expose only values consumed by other modules, needed for documentation, or required for external integration. Over-exposing creates tight coupling and makes refactoring difficult. Treat outputs as a public API surface. Internal attributes should remain encapsulated unless there is a concrete consumer requiring access outside the module boundary.
Use the optional function with type constraints in variable definitions, available since Terraform 1.3. Combine with locals using coalesce or merge to build complete configuration objects from partial input. This pattern reduces boilerplate in tfvars files while maintaining type safety and clear documentation of which fields are truly required versus customizable.
