Use input variables to add module arguments

Hands-on: Try theCustomize Terraform Configuration with Variables tutorial.

You can addvariable blocks to your configuration to define input interface for your module. This lets users pass custom values to your module at runtime.

Terraform sets up resources with hardcoded values the same way every time, making your module inflexible and potentially hard to reuse. If you know a value in your configuration changes between Terraform operations, you can replace that value with avariable block. Avariable block lets module consumers customize module behavior without altering the module's source code.

Define variables

Addvariables blocks to your root module to let consumers pass values into the module at run time. Defining avariable block in a child module lets a parent module pass values into the child module at run time. Learn more aboutpassing values to child modules.

For example, if your root module has a resource with hardcoded values:

resource "aws_instance" "web" {  ami= data.aws_ami.ubuntu.id  instance_type= "t2.micro"  subnet_id= "subnet-12345"  tags= {    Environment= "dev"    Name= "dev-web-server"  }}

Terraform sets up resources with hardcoded values the same way every time, making your module inflexible and potentially hard to reuse. If you know a value in your configuration changes between Terraform operations, you can replace that value with avariable block.

Defining variables gives your module consumer the flexibility to change values at run time. Add avariable block for each input you want to define for your module.

The following example definesinstance_type,subnet_id, andenvironment input variables. These variables lets module consumers specify custom values for customize the instance type, subnet, and deployment environment of your web server at run time:

variable "instance_type" {  type= string  description= "EC2 instance type for the web server"  default= "t2.micro"}variable "subnet_id" {  type= string  description= "Subnet ID where the web server will be deployed"}variable "environment" {  type= string  description= "Deployment environment name"  default= "dev"  validation {    condition= contains(["dev", "staging", "prod"], var.environment)    error_message= "Environment must be dev, staging, or prod."  }}

Theenvironment variable also contains an optionalvalidation block to ensure the value a consumer specifies as the input value meets module requirements. Learn more aboutvalidating variable values in your configuration.

Reference variable values

To reference avariable in other parts of your configuration, usevar.<NAME> syntax. For example, to make your web server use the new variables, replace the hardcoded values with references tovar.instance_type,var.subnet_id, andvar.environment:

# ...resource "aws_instance" "web" {  ami= data.aws_ami.ubuntu.id  instance_type= var.instance_type  subnet_id= var.subnet_id  tags= {    Environment= var.environment    Name= "${var.environment}-web-server"  }}

Module consumers can use the default values for theenvironment,subnet_id, andinstance_type variables in theweb configuration or input custom values when they run the configuration. If a variable does not have a default value, such as thesubnet_id variable, then Terraform prompts the user to assign a value before it generates a plan.

Sensitive values in variables

If you are defining avariable for sensitive data such as an API key or password, use thesensitive argument to prevent Terraform from displaying the value in CLI output:

variable "database_password" {  type= string  description= "Password for the RDS database instance"  sensitive= true}

Terraform still stores the values of sensitive variables in your state. You can add theephemeral argument to yourvariable configuration to omit the variable from state and plan files. Adding theephemeral argument does add restrictions to the values you can assign that variable. To learn more about handling sensitive data in your configuration, refer toManage sensitive data.

To learn more about the best practices of defining variables, refer to theTerraform style guide. To learn more about thevariable block, refer to thevariable block reference.

Assign values to variables

You can assign values to root module variables through multiple methods, each with different precedence levels. Child modules receive their inputs from a parent module as arguments. To learn more about calling child modules, refer toModules.

If a module defines a variable without adefault argument, Terraform prompts the user to supply a value for that variable before it generates a plan. You can assign variable values in the root module using the following methods:

• HCP Terraform variables and variable sets
• The-var and-var-file options on theCLI
• Variable definition files
• Environment variables

Once you assign a value to a variable, you cannot reassign that variable within the same file. However, if the root module receives multiple values for the same variable name from different sources, Terraform uses the following order of precedence:

1. Any-var and-var-file options on thecommand line in the order provided and variables from HCP Terraform
2. Any*.auto.tfvars or*.auto.tfvars.json files in lexical order
3. Theterraform.tfvars.json file
4. Theterraform.tfvars file
5. Environment variables
6. Thedefault argument of thevariable block

Values defined in HCP Terraform and on the command line take precedence over other ways of assigning variable values. The variable'sdefault argument is at the lowest level of precedence.

Manage variables in HCP Terraform

HCP Terraform provides the following variable management capabilities:

• Assign values to variables in your configuration through workspaces.
• Group variables into sets that you can apply to multiple workspaces.
• Use access control settings to limit who can view and create new variables.

To learn more about variables in HCP Terraform, refer to theVariables overview.

Command-line variables

Inputting variable values with Terraform CLI commands is useful for one-off deployments or when you need to override specific values without creating new files. You can assign variable values with the Terraform CLI using the-var=<VAR_NAME>=<VALUE> flag:

terraform apply -var="instance_type=t3.medium" -var="environment=prod"terraform apply -var='subnet_ids=["subnet-12345","subnet-67890"]'

If you are passing complex types through environment variables or command line flags, use proper JSON syntax to comply with the string escaping rules in your shell:

export TF_VAR_complex_config='{"key": "value", "list": ["a", "b"]}'

For readability, and to avoid shell escaping, we recommend setting complex variable values withvariable definition files. For more details on shell quoting and the Windows command prompt, refer toInput variables on the command line.

Variable definition files

Variable definition files are ideal for managing different environment configurations and for managing variable values in your version control system. Create a variable definition file to assign multiple variable values in one file.

You can assign values directly to variable names in files with a.tfvars or.auto.tfvars extension. For example, the following file assigns variable values for a production environment:

instance_type= "t3.large"environment= "prod"subnet_ids= ["subnet-12345", "subnet-67890", "subnet-abcdef"]enable_monitoring= true

Terraform automatically loads variable definition files if it detects any of the following:

• File names ending in.auto.tfvars or.auto.tfvars.json
• A file namedterraform.tfvars.json
• A file namedterraform.tfvars

Terraform loads different variable definition files at different times, and uses the following precedence order for the values assigned in variable definition files:

1. Any*.auto.tfvars or*.auto.tfvars.json files in lexical order
2. Theterraform.tfvars.json file
3. Theterraform.tfvars file

If a file name ends with.json, then Terraform parses that file as a JSON object, using variable names as the root object keys:

{  "image_id": "ami-abc123",  "availability_zone_names": ["us-west-1a", "us-west-1c"]}

You can also apply a.tfvars variable file directly to the CLI using the-var-file flag:

terraform apply -var-file="production.auto.tfvars"

If your variable definition files contains any sensitive values, ensure youignore those files in your VCS provider.

Environment variables

Environment variables are useful in CI/CD pipelines when you want to inject configuration values without creating additional files. You can set environment variables using theTF_VAR_ prefix to a variable name:

export TF_VAR_instance_type=t3.mediumexport TF_VAR_environment=stagingterraform apply

If you are passing complex types through environment variables or command line flags, use proper JSON syntax to comply with the string escaping rules in your shell:

export TF_VAR_complex_config='{"key": "value", "list": ["a", "b"]}'

For readability, and to avoid shell escaping, we recommend setting complex variable values withvariable definition files.

Undeclared variables

Terraform handles setting values for undeclared variables differently depending on how you assign that value:

• Terraform ignores any assignedenvironment variables that do not have a matchingvariable block.
• Terraform warns you if you assign an undeclared variable in avariable definition file, letting you catch accidental misspellings in your configuration or definition files.
• Terraform errors if you attempt to assign a value for an undeclared variable with-var on the command line.