Terraform Variable Types and Validation

A variable without rules accepts anything. Someone types "banana" where a server count belongs, and the mistake surfaces halfway through a deployment. Type constraints and validation rules act like a security guard at the door. They check every value before Terraform starts any work. Bad input stops early with a clear message.

Why Type Constraints Matter

A type constraint tells Terraform what shape a value must have. Without one, Terraform guesses. Guesses cause surprises. A declared type turns a vague error deep inside a cloud API call into a friendly error at the start of the run.

Primitive Types

variable "region" {
  type    = string
  default = "us-east-1"
}

variable "server_count" {
  type    = number
  default = 2
}

variable "enable_backup" {
  type    = bool
  default = true
}

Collection Types

Collections hold several values together.

TypeMeaningLayman Picture
list(string)Ordered values of one typeA numbered shopping list
set(string)Unique values with no orderA bag of distinct marbles
map(string)Keys paired with values of one typeA phone book
variable "availability_zones" {
  type    = list(string)
  default = ["us-east-1a", "us-east-1b"]
}

variable "tags" {
  type = map(string)
  default = {
    owner = "platform"
    env   = "dev"
  }
}

Structural Types

Structural types mix different kinds of values inside one variable.

Object Type

An object works like a form with named fields. Each field has its own type.

variable "database" {
  type = object({
    engine         = string
    storage_gb     = number
    multi_az       = bool
  })

  default = {
    engine     = "postgres"
    storage_gb = 20
    multi_az   = false
  }
}

Read a field with var.database.engine.

Optional Fields

Mark a field optional and give it a fallback.

type = object({
  engine     = string
  storage_gb = optional(number, 20)
})

Validation Blocks

A type says what shape a value has. A validation block says which values are acceptable. Each block holds a condition that must evaluate to true and an error_message shown when the condition fails.

Diagram: The Validation Gate

  User supplies a value
          |
          v
  +------------------+
  |  Type check      |---- wrong type ----> Error: stop
  +------------------+
          | passes
          v
  +------------------+
  | Validation rule  |---- condition false --> Error message: stop
  +------------------+
          | condition true
          v
   Terraform plans and builds

Example: Limit Allowed Choices

variable "environment" {
  type = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be dev, staging, or prod."
  }
}

Example: Check a Number Range

variable "server_count" {
  type = number

  validation {
    condition     = var.server_count >= 1 && var.server_count <= 10
    error_message = "Server count must be between 1 and 10."
  }
}

Example: Check a Text Pattern

variable "bucket_name" {
  type = string

  validation {
    condition     = can(regex("^[a-z0-9-]{3,63}$", var.bucket_name))
    error_message = "Use 3 to 63 lowercase letters, numbers, or hyphens."
  }
}

The can() function returns true when the inner expression works and false when it fails. It pairs well with regex().

Multiple Rules on One Variable

A variable accepts several validation blocks. Terraform reports every failed rule, so the user fixes all problems in one pass.

Passing Values

MethodExample
Command lineterraform plan -var="environment=dev"
Variable fileterraform plan -var-file="dev.tfvars"
Environment variableexport TF_VAR_environment=dev

Key Points

  • A type constraint checks the shape of a value before any work begins.
  • Primitive types are string, number, and bool.
  • Collections are list, set, and map. Structural types are object and tuple.
  • An object groups named fields, and optional() supplies fallbacks.
  • A validation block holds a condition and an error_message.
  • Use contains() for allowed lists and can(regex()) for text patterns.
  • Early validation turns confusing cloud errors into clear messages.