Terraform / OpenTofu efficient variables management

Splitting into multiple filesSection titled Splitting%20into%20multiple%20files

Rather than keeping all variables definitions in a single variables definitions file, you can split them into logical groups. This approach improves readability, simplifies maintenance, and makes it easier for teams to collaborate as changes can be more easily identified in CVS systems, ie. git.

A common pattern includes separating variables by resource type or functionality.

1
variable "vpc_cidr" {
2
  type        = string
3
  description = "CIDR block for the VPC"
4
  default     = "10.0.0.0/16"
5
}
6

7
# compute-vars.tf
8
variable "instance_type" {
9
  type        = string
10
  description = "EC2 instance type"
11
  default     = "t3.micro"
12
}
13

14
# storage-vars.tf
15
variable "storage_size" {
16
  type        = number
17
  description = "Size of storage in GB"
18
  default     = 50
19
}

And not only variables definitions can be split across files, but also breaking into smaller pieces the files that contain the variable’s values can help make any maintenance task more enjoyable.

This approach is very useful when managing different environments or configurations since any update to an environment is less error prone and easier to validate.

Let’s look at an example deploying to dev and prod environments:

1
variable "vpc_settings" {
2
  type = object({
3
    cidr_block = string
4
    name       = string
5
    subnets    = map(string)
6
  })
7
}
8

9
# dev.tfvars
10
vpc_settings = {
11
  cidr_block = "10.0.0.0/16"
12
  name       = "dev-vpc"
13
  subnets    = {
14
    public  = "10.0.1.0/24"
15
    private = "10.0.2.0/24"
16
  }
17
}
18

19
# prod.tfvars
20
vpc_settings = {
21
  cidr_block = "172.16.0.0/16"
22
  name       = "prod-vpc"
23
  subnets    = {
24
    public  = "172.16.1.0/24"
25
    private = "172.16.2.0/24"
26
  }
27
}

Using the -var-file flag, the appropriate environment variables can be passed to OpenTofu, like this:

1
$ tofu plan -o plan.out -var-file dev.tfvars   # for development env
2
$ tofu plan -o plan.out -var-file prod.tfvars  # for production env

When managing large variables sets, an useful option is to split them based on functionality as well, similar to this:

1
vpc_cidr = "10.0.0.0/16"
2
subnet_cidrs = {
3
  public  = "10.0.1.0/24"
4
  private = "10.0.2.0/24"
5
}
6
route_tables = {
7
  public  = "public-rt"
8
  private = "private-rt"
9
}
10

11
# security.tfvars
12
security_groups = {
13
  web = {
14
    name = "web-sg"
15
    ports = [80, 443]
16
  }
17
  database = {
18
    name = "db-sg"
19
    ports = [5432]
20
  }
21
}
22
ip_whitelist = ["10.20.0.0/16", "192.168.1.0/24"]
23

24
# application.tfvars
25
app_settings = {
26
  name = "myapp"
27
  environment = "production"
28
  instance_type = "t3.large"
29
}

Using the same -var-file flag multiple times, will merge together all the variables files to form a single set of variables that will be used by OpenTofu at runtime:

1
$ tofu plan \
2
  -var-file=env/dev/networking.tfvars \
3
  -var-file=env/dev/security.tfvars \
4
  -var-file=env/dev/application.tfvars"

The drawback to this approach is that when multiple files define the same variable, the value from the last file will overwrite all others. This applies even if the variable is a map and each file specifies a different set of keys for that map.

For example:

1
security_groups = {
2
  web = {
3
    name = "web-sg"
4
    ports = [80, 443]
5
  }
6
}
7

8
# security_db.tfvars
9
security_groups = {
10
  database = {
11
    name = "db-sg"
12
    ports = [5432]
13
  }
14
}

Issuing the following command:

1
$ tofu plan \
2
  -var-file=env/dev/security_web.tfvars \
3
  -var-file=env/dev/security_db.tfvars

will result in the following variable being used at runtime:

1
security_groups = {
2
  database = {
3
    name = "db-sg"
4
    ports = [5432]
5
  }
6
}

Merging variablesSection titled Merging%20variables

Building on the previous example of splitting variables across files, a solution that can address the potential issue of variable overrides is to use OpenTofu’s built-in functions merge() and concat() to combine multiple variables into a single variable.

Here’s one example:

1
web_security_groups = {
2
  web = {
3
    name = "web-sg"
4
    ports = [80, 443]
5
  }
6
}
7

8
# db-security.tfvars
9
db_security_groups = {
10
  database = {
11
    name = "db-sg"
12
    ports = [5432]
13
  }
14
}
15

16
# main.tf
17
locals {
18
  # Merge multiple security group configurations
19
  security_groups = merge(
20
    {
21
      # Default values that can be overridden
22
      monitoring = {
23
        name = "monitoring-sg"
24
        ports = [9090]
25
      }
26
    },
27
    var.web_security_groups,
28
    var.db_security_groups,
29
  )
30
}

This method prevents accidental overwrites, allows for layered configurations, maintains default values as fallbacks and makes it easier to extend configurations without modifying existing files.

Dependencies between variablesSection titled Dependencies%20between%20variables

Often times systems require specific values to be set based on the values of another configuration option. To achieve this level of flexibility, an OpenTofu’s variable value can be made dependent on another variable’s value. This is possible because OpenTofu processes the variables at runtime before passing them to the code.

Let’s see a few examples:

1
variable "environment" {
2
  type    = string
3
  default = "dev"
4
}
5

6
locals {
7
  # Instance type depends on environment
8
  instance_type = {
9
    dev  = "t3.micro"
10
    test = "t3.small"
11
    prod = "t3.large"
12
  }[var.environment]
13

14
  # Storage configuration based on environment
15
  storage_config = {
16
    size = var.environment == "prod" ? 1000 : 100
17
    type = var.environment == "prod" ? "io1" : "gp2"
18
  }
19

20
  # Compute capacity based on multiple variables
21
  autoscaling_config = {
22
    min = var.environment == "prod" ? 3 : 1
23
    max = var.high_availability ? 10 : 3
24
    desired = var.environment == "prod" ? 5 : 1
25
  }
26
}

Here, the instance_type variable’s value is actualy a string based on the value of the environment variable which is used as a key to search in a map of possible values.

In the case of the storage_config and autoscaling_config the code uses other variables to set hard values using conditionals. This is useful when there is a need to very tightly constrain certain parameters of the infrastructure - due to compliance or costs for example.

Using this approach can be applied to variable validations to create a more robust documentation and user experience.

1
variable "environment_config" {
2
  type = object({
3
    name = string      # e.g., "dev", "prod"
4
    tier = string      # e.g., "free", "premium"
5
  })
6

7
  validation {
8
    condition     = contains(["dev", "prod"], var.environment_config.name)
9
    error_message = "Environment name must be either 'dev' or 'prod'"
10
  }
11

12
  validation {
13
    condition     = contains(
14
      var.environment_config.name == "dev"
15
        ? ["free"]
16
        : ["free", "premium"],
17
      var.environment_config.tier
18
    )
19
    error_message = "Dev environment can only use 'free' tier. Prod can use 'free' or 'premium'"
20
  }
21
}

1
# This is a valid
2
environment_config = {
3
  name = "prod"
4
  tier = "premium"
5
}
6

7
# Invalid - will fail validation
8
environment_config = {
9
  name = "dev"
10
  tier = "premium"  # Error: dev environment can only use 'free' tier
11
}

Restructuring dataSection titled Restructuring%20data

As the OpenTofu project evolves the need may arise to “transform” variables into new formats to match new project code or a third-party module’s requirements. This might involve string manipulation, type conversion, or creating completely new variables which combine values from multiple other variables.

Let’s take a look at a few examples:

1
variable "environment" {
2
  type    = string
3
  default = "dev"
4
}
5

6
variable "project" {
7
  type    = string
8
  default = "myapp"
9
}
10

11
locals {
12
  # Convert to lowercase and add prefix combining multiple vars values
13
  resource_prefix = lower("${var.environment}-${var.project}")
14

15
  # Create standardized name format
16
  resource_name = format("%s-%s-%s",
17
    local.resource_prefix,
18
    var.project,
19
    formatdate("YYYY", timestamp())    # resulting in string 2025
20
  )
21
}