Infrastructure Automation with Terraform

**Terraform provides a declarative model for infrastructure automation. It matters when a team needs to treat infrastructure as code, enabling version-controlled, repeatable provisioning across cloud providers or on-prem environments. Unlike imperative tools that describe *how* to change a system, Terraform describes *what* the final state should be, calculating the steps required to reach it. This page covers the practical workflows, concrete commands, and sharp edges encountered when using Terraform for infrastructure automation.**

Bootstrapping and Validation

Every Terraform project begins with a working directory. The first concrete step is initializing the directory, which downloads provider plugins and configures the backend for state storage.

terraform init

terraform init also sets up the remote backend if configured. A common pattern includes backend configuration flags:

terraform init -backend-config="region=us-east-1" -backend-config="lock_table=terraform-locks"

After initialization, configuration files (typically main.tf, variables.tf, and outputs.tf) are written. Before attempting any changes, two validation commands are standard:

terraform fmt
terraform validate

terraform fmt rewrites configuration files to conform to canonical formatting. terraform validate checks that the configuration is syntactically correct and that referenced variables and data sources are valid. If validate returns errors, the configuration must be corrected before a plan or apply can succeed.

The State Machine

The most critical—and most frequently misunderstood—aspect of Terraform is the state file. The state is the single source of truth mapping real-world resources to configuration. It is not the configuration itself; it is the snapshot of *what* has been provisioned.

To inspect the current state:

terraform state list

This command outputs a list of resource addresses currently tracked. To see the details of a specific resource:

terraform state show aws_instance.web

Terraform uses state locking to prevent concurrent operations from corrupting the state. When a plan or apply runs, the backend acquires a lock. If another process attempts to modify state while the lock is held, the operation fails with an error. In backends like Consul or DynamoDB, this is implemented via a lease mechanism. If a process crashes without releasing the lock, subsequent runs will stall until the lock expires or is manually cleared.

A frequent sharp edge involves state drift. If resources are modified outside of Terraform (e.g., via the cloud console or a script), terraform plan will detect the difference and report it. However, if the state file itself is deleted or corrupted, Terraform no longer knows what resources exist. Recovery in this scenario typically requires terraform import to re-establish the mapping between resource addresses and real-world IDs, or in extreme cases, rebuilding the state from scratch using cloud provider APIs.

Planning and Applying Changes

The core workflow for infrastructure changes is the plan-apply cycle. terraform plan generates an execution plan, showing exactly what will be created, modified, or destroyed.

terraform plan -out=plan.out

The -out flag serializes the plan to a file, which can then be applied later with terraform apply plan.out. This is useful for change management processes where a plan must be reviewed and approved before execution.

To execute the changes:

terraform apply

Upon running terraform apply, Terraform will display the planned changes and prompt for confirmation unless -auto-approve is used.

terraform apply -auto-approve

A crucial flag for targeted operations is -target. This limits the scope of the plan or apply to a specific resource address.

terraform apply -target="aws_instance.web"

Using -target is powerful but dangerous. It bypasses the normal graph traversal, meaning dependencies of the targeted resource are ignored. If the targeted resource has prerequisites that are out of sync, apply may fail or produce unexpected results.

Handling Drift and Import

Infrastructure often exists before Terraform manages it. terraform import is the mechanism to bring existing resources under Terraform management.

terraform import aws_instance.web i-0123456789abcdef0

This command takes a resource address and an existing ID. It updates the state file to point to that ID but does not generate configuration. The user must then edit the configuration block to match the imported resource's attributes, or subsequent plans will show the resource as different.

A common failure mode occurs when the imported resource has attributes not captured in the configuration. terraform plan will then show "drift"—changes that must be made to align the configuration with the actual resource, or adjustments to the configuration to match the resource.

Modules and Composition

Reusability is achieved through modules. A module is a container for multiple resources used in many places.

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.3.0"

  name = "dev"
  cidr = "10.0.0.0/16"
}

The source argument points to a registry module or a path on the local filesystem. The version pinning is essential for reproducibility; without it, a future module version could change resource behavior unexpectedly.

Modules can output values that are consumed by other configurations.

module "network" {
  source = "./network"

  environment = "prod"
}

resource "aws_lb" "frontend" {
  vpc_id            = module.network.vpc_id
  subnets         = module.network.private_subnets
}

Sharp Edges and Common Pitfalls

Several operational gotchas are learned through production failures.

Parallelism and Resource Contention Terraform provisions resources in parallel, respecting dependencies. The -parallelism flag controls the maximum number of resources created or destroyed simultaneously.

terraform apply -parallelism=10

Setting this too high can hit API rate limits or cause resource contention errors from the provider. If errors appear such as "RequestLimitExceeded" or "Throttling," reducing parallelism is the immediate remediation.

The -target Trap As noted, -target is a sharp edge. A common pattern is using -target to fix a single broken resource, followed by a full apply. If the -target resource has upstream dependencies that are not also targeted, the plan may report that those dependencies must be updated or that the resource cannot be created because its inputs are missing. The safest practice is to avoid -target for production changes unless the full impact is understood.

State File Lock Staleness If a plan or apply fails mid-execution (e.g., due to a network blip), the state lock might not be released cleanly. The error message typically reads: Error acquiring the lock. Retrying the command usually resolves this, as Terraform will wait for or force-release the lock depending on the backend configuration.

Provider Version Skew Providers are updated frequently. If terraform init is run after a provider update but before terraform apply, and the configuration does not explicitly constrain the provider version, the new provider version is used. Providers sometimes change argument names or behavior between major versions. A silent failure mode occurs when a configuration works with provider v3.5 but breaks with v4.0 due to a renamed argument, and the only signal is a vague error during plan. Pinning provider versions in required_providers blocks within versions.tf is the preventive measure.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

This ensures that terraform init selects a compatible version, preventing silent breakage from provider updates.

This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.