Check blocks for assertions in Terraform - Commands & Configuration

Introduction

Sometimes you want to make sure your infrastructure settings meet certain rules before creating resources. Check blocks in Terraform help you do this by stopping the process if conditions are not met.

When you want to ensure a variable value is within a safe range before applying changes.

When you need to prevent deployment if a required input is missing or incorrect.

When you want to enforce naming conventions for resources automatically.

When you want to avoid creating resources in unsupported regions.

When you want to catch configuration mistakes early to save time and avoid errors.

Config File - main.tf

main.tf

terraform {
  required_version = ">= 1.2.0"
}

variable "environment" {
  type    = string
  default = "dev"
}

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

check "valid_environment" {
  condition     = contains(["dev", "staging", "prod"], var.environment)
  error_message = "The environment must be one of: dev, staging, prod."
}

check "valid_instance_count" {
  condition     = var.instance_count > 0 && var.instance_count <= 5
  error_message = "Instance count must be between 1 and 5."
}

resource "null_resource" "example" {
  count = var.instance_count
}

terraform block: Specifies the required Terraform version.

variable blocks: Define inputs for environment and instance count.

check blocks: These are assertions that stop deployment if conditions are false. They include a condition and an error message.

resource block: Creates a number of dummy resources based on instance_count.

Commands

Initializes the Terraform working directory and downloads necessary providers.

Terminal

terraform init

Expected Output

Initializing the backend...



Initializing provider plugins...

- Finding latest version of hashicorp/null...

- Installing hashicorp/null v3.1.0...

- Installed hashicorp/null v3.1.0 (signed by HashiCorp)



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see any changes that are required for your infrastructure.

Checks the configuration files for syntax errors and validates check blocks conditions.

Terminal

terraform validate

Expected Output

Success! The configuration is valid.

Applies the configuration to create resources. It will stop if any check block condition fails.

Terminal

terraform apply -auto-approve

Expected Output

null_resource.example[0]: Creating...

null_resource.example[0]: Creation complete after 0s [id=123456]

null_resource.example[1]: Creating...

null_resource.example[1]: Creation complete after 0s [id=789012]



Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

→

-auto-approve - Skips interactive approval before applying changes

Attempts to apply with an invalid environment variable, triggering a check block error.

Terminal

terraform apply -auto-approve -var='environment=invalid'

Expected Output

╷

│ Error: Check failed: valid_environment

│ 

│   with check.valid_environment,

│   on main.tf line 13:

│   13: check "valid_environment" {

│ 

│ The environment must be one of: dev, staging, prod.

╵

→

-var - Overrides variable values from the command line

→

-auto-approve - Skips interactive approval before applying changes

Key Concept

If you remember nothing else from this pattern, remember: check blocks stop Terraform from applying changes when important conditions are not met.

Common Mistakes

Writing check conditions that always evaluate to true or false without testing.

This defeats the purpose of validation and can cause unexpected failures or no validation at all.

Test your check conditions with different variable values to ensure they behave as expected.

Not providing clear error_message in check blocks.

Users won't understand why the deployment failed, making troubleshooting harder.

Write simple, clear error messages that explain what is wrong and how to fix it.

Using check blocks in Terraform versions older than 1.2.0.

Check blocks are supported starting from Terraform 1.2.0, so older versions will fail to parse them.

Ensure your Terraform version is 1.2.0 or newer before using check blocks.

Summary

Use check blocks in Terraform to enforce rules before creating resources.

Run 'terraform validate' to check configuration syntax and conditions.

If a check condition fails, Terraform stops and shows your error message.