Terraform Locals vs Variables

Last Updated on August 7, 2025 by Arnav Sharma

In Terraform, both locals and variables are used to define values, but they serve different purposes and have different behaviors. Understanding the distinction between them is crucial for effective Terraform configuration.

Variables

Purpose: Variables in Terraform are analogous to function arguments. They are used to customize Terraform modules with different values. This makes your Terraform configurations more dynamic and reusable.
Definition: Variables are defined in Terraform using the variable keyword. They can be set from outside the module (e.g., via command-line flags, environment variables, Terraform Cloud, or the terraform.tfvars file).
Usage: Variables are used to allow users to input custom values. They are often used for setting up resources that might need different configurations in different environments (like development, staging, production).
Scope: Variables can be accessed by any resource or module within the same module where they are declared.

Example 1: Defining and Using a Variable

variable “instance_type” {
description = “The type of EC2 instance to create.”
type = string
default = “t2.micro”
}

resource “aws_instance” “example” {
ami = “ami-0c55b159cbfafe1f0”
instance_type = var.instance_type
}

In this example, the instance_type variable allows users to specify the type of EC2 instance. If not specified, it defaults to t2.micro.

Example 2: Overriding Variable Values

You can override the default value of a variable in several ways, such as through command-line flags or a terraform.tfvars file.

Command-line:

terraform apply -var=”instance_type=t2.large”

terraform.tfvars file:

instance_type = “t2.large”

Locals

Purpose: Locals (short for “local values”) are used to simplify your Terraform code and reduce repetition. They are like constants or helper variables within a Terraform module.
Definition: Locals are defined using the locals block. They are only accessible within the module where they are defined.
Usage: Locals are useful for creating complex expressions that you need to reuse. For example, you might use a local to construct a naming convention that is used in several resources within a module.
Scope: Local values are module-scoped and can only be referenced within the module where they are defined. They cannot be set or overridden from outside the module.

Example 1: Defining and Using Locals

locals {
common_tags = {
Owner = “Team A”
Environment = “Prod”
}
}

resource “aws_instance” “example” {
ami = “ami-0c55b159cbfafe1f0”
instance_type = “t2.micro”
tags = local.common_tags
}

In this example, local.common_tags is used to apply the same set of tags to multiple resources within the module.

Example 2: Simplifying Expressions with Locals

locals {
subnet_prefix = “10.0.${var.environment_id}.0/24”
}

resource “aws_subnet” “example” {
vpc_id = aws_vpc.main.id
cidr_block = local.subnet_prefix
}

Here, local.subnet_prefix simplifies the creation of a subnet CIDR block based on an environment ID provided as a variable.

Key Differences Illustrated

Mutability: Variables can be changed externally (e.g., different instance types for different deployments), while locals are fixed once defined (e.g., common_tags used consistently across resources).
Scope: Variables can be passed into modules from parent modules or the Terraform command line. Locals are only accessible within the module where they are defined.
Purpose: Variables are for user inputs and external configuration. Locals are for internal organization, reducing repetition, and simplifying complex expressions.

When to Use Each

Use variables when you need to:
- Allow users to customize the configuration.
- Create modules that can be used in different environments with different settings.
Use locals when you need to:
- Simplify complex expressions that are used multiple times within a module.
- Create a fixed internal value that helps make your configuration more readable and maintainable.