variable block reference for component configurations

Use the variable block to declare input variables for your component configuration, making your components dynamic and reusable.

If you are declaring a variable block in a traditional Terraform configuration file, ending in .tf, refer to the Terraform configuration variable block reference instead.

Background

Use the variable block in component configurations, <NAME>.tfcomponent.hcl files, to declare values that can change between deployments.

Deployments, in deployment configuration files, pass values to Stack variables through the inputs argument in the deployment configuration. The separation between component configuration and deployment configuration lets you maintain a single Stack definition while creating multiple deployments with different inputs.

Configuration model

The variable block supports the following arguments:

variable "<LABEL>" block
- type type constraint
- default expression
- description string
- sensitive boolean
- nullable boolean
- ephemeral boolean

Complete configuration

All available arguments are defined in the following variable block:

variable "<LABEL>" {
  type        = <TYPE>
  default     = <DEFAULT_VALUE>
  description = "<DESCRIPTION>"
  sensitive   = <true|false>
  nullable    = <true|false>
  ephemeral   = <true|false>
}

Specification

A variable block supports the following configuration.

`variable "<LABEL>"`

The label after the variable keyword is a name for the variable, which must be unique among all variables in the same component configuration. The name of a variable can be any valid identifier.

The variable block supports the following arguments:

Argument	Description	Type	Required?
`type`	The type constraint for the value of this variable.	Type constraint	Required
`default`	The default value for this variable. Variables without a default value require deployments to provide a value.	Expression	Optional
`description`	A description of the variable's purpose and the value it expects.	String	Optional
`sensitive`	Specifies if Terraform hides this value in UI and logs.	Boolean	Optional
`nullable`	Specifies if the value of a variable can be `null`.	Boolean	Optional
`ephemeral`	Specifies whether Terraform excludes this value from plans and state.	Boolean	Boolean	Optional

`type`

The type argument constrains the type of value that deployments can assign to this variable. component configurations require you to explicitly define the type for each variable.

variable "<LABEL>" {
  type = <TYPE_CONSTRAINT>
}

Defining type constraints helps deployment authors understand what values your variable accepts by providing error messages if they attempt to use an invalid type.

For details about types, constructors, and conversions, refer to Type constraints.

Summary

Data type: Type constraint
Default: None
Required: Yes

`default`

The default argument defines a default value for the variable, making it optional for deployments to provide a value.

variable "<LABEL>" {
  type    = <TYPE_CONSTRAINT>
  default = <DEFAULT_VALUE>
}

If you specify both the type and default arguments, the default value must match the specified type. The default argument requires a literal value and cannot reference other objects in your configuration.

Summary

Data type: Expression
Default: None (deployments must provide a value if no default exists)
Required: No

`description`

The description argument documents the purpose of the variable and the value it expects.

variable "<LABEL>" {
  type        = <TYPE_CONSTRAINT>
  description = "<DESCRIPTION>"
}

Write descriptions from the perspective of someone configuring deployments to help them understand how to use this variable.

Summary

Data type: String
Default: None
Required: No

`sensitive`

The sensitive argument prevents Terraform from showing the variable's value in the HCP Terraform UI and logs.

variable "<LABEL>" {
  type      = <TYPE_CONSTRAINT>
  sensitive = <BOOLEAN>
}

When you mark a variable as sensitive, Terraform redacts its value in plan and apply logs, displaying (sensitive value) instead. Terraform also treats any expressions that use a sensitive variable as sensitive.

Terraform still records sensitive values in state, so anyone who can access your state data can access your sensitive values. For more information about safely storing sensitive data, refer to Manage sensitive data.

Summary

Data type: Boolean
Default: false
Required: No

`nullable`

The nullable argument controls whether deployments can assign the value null to the variable.

variable "<LABEL>" {
  type     = <TYPE_CONSTRAINT>
  nullable = <BOOLEAN>
}

If nullable is false, the variable must have a non-null value. If nullable is true and the variable has a default argument, deployments can explicitly set the variable value to null, overriding the default.

Summary

Data type: Boolean
Default: true
Required: No

`ephemeral`

The ephemeral argument makes a variable available during runtime but prevents Terraform from storing its value in state and plan files.

variable "<LABEL>" {
  type      = <TYPE_CONSTRAINT>
  ephemeral = <BOOLEAN>
}

Ephemeral variables are useful for temporary values like session tokens or short-lived credentials that you don't want to persist in state.

You can only reference ephemeral variables from specific contexts or Terraform throws an error:

In a managed resource write-only argument
In an ephemeral block
In the locals block
In other variable blocks with the ephemeral argument set to true
In child module output blocks with the ephemeral argument set to true
Configuring providers in the provider block
In provisioner and connection blocks

Summary

Data type: Boolean
Default: false
Required: No

Examples

The following examples demonstrate common use cases for variable blocks in component configurations.

Using variables in component configurations

The following example declares aws_region and instance_count variables. The network component then uses the inputs argument to intake those variables:

variable "aws_region" {
  type        = string
  description = "The AWS region where resources will be deployed"
}

variable "instance_count" {
  type        = number
  description = "Number of instances to create"
  default     = 2
}

component "network" {
  source = "./modules/network"

  inputs = {
    region      = var.aws_region
    cidr_block  = var.instance_count
  }
}

The ./modules/network module can now reference var.aws_region and var.instance_count in its configuration.

Deployments provide values for variables through the inputs argument. In the following example, the production and staging deployments provide values for the aws_region and instance_count variables:

deployment "production" {
  inputs = {
    aws_region     = "us-west-2"
    instance_count = 5
  }
}

deployment "staging" {
  inputs = {
    aws_region     = "us-east-1"
    instance_count = 2
  }
}

The production and staging deployments can each input different values for aws_region and instance_count while building the same component configuration. The names of the variables in the deployment's inputs block must match the names declared in the component configuration variable blocks.