In Terraform projects, format and validation are your first line of defence against messy code and avoidable runtime errors. Think of them as “style checking” and “sanity checking” for infrastructure as code.

---

Why Format and Validate at All?

Terraform configurations tend to grow into large, multi‑module codebases, often edited by several engineers at once. Without conventions and guards:

• Small style differences accumulate into noisy diffs.
• Subtle typos, type mismatches, or broken references sneak into main.
• Misused modules cause surprises late in plan or even apply.

Formatting (terraform fmt) standardises how the code looks, while validation (terraform validate and variable validation) standardises what values are acceptable.

---

Formatting Terraform Code with terraform fmt

What terraform fmt Actually Does

terraform fmt rewrites your .tf files into Terraform’s canonical style.

It:

• Normalises indentation and alignment.
• Orders and spaces arguments consistently.
• Applies a single canonical style across the project.

Typical usage:

# Fix formatting in the current directory
terraform fmt

# Recurse through modules and subfolders (what you want in a real repo)
terraform fmt -recursive

For CI or pre‑commit hooks you almost always want:

terraform fmt -check -recursive

This checks formatting, returns a non‑zero exit code if anything is off, but does not modify files. That makes it safe for pipelines.

Why This Matters Architecturally

• Consistent formatting reduces cognitive load; you can scan resources quickly instead of re‑parsing everyone’s personal style.
• Diffs stay focused on behaviour instead of whitespace and alignment.
• A shared style is essential when modules are reused across teams and repos.

Treat terraform fmt like go fmt: it’s not a suggestion, it’s part of the toolchain.

---

Structural Validation with terraform validate

What terraform validate Checks

terraform validate performs a static analysis of your configuration for syntactic and internal consistency.

It verifies that:

• HCL syntax is valid.
• References to variables, locals, modules, resources, and data sources exist.
• Types are consistent (for example you’re not passing a map where a string is expected).
• Required attributes exist on resources and data blocks.

Basic usage:

terraform init     # required once before validate
terraform validate

If everything is fine you will see:

Success! The configuration is valid.

This does not contact cloud providers; it is a “compile‑time” check, not an integration test.terraformpilot+1

Why You Want It in Your Workflow

• Catches simple but common mistakes (typos in attribute names, missing variables, wrong types) before plan.
• Cheap enough to run on every commit and pull request.
• Combined with fmt, it gives you a fast gate that keeps obviously broken code out of main.

In CI, a very standard pattern is:

terraform fmt -check -recursive
terraform init -backend=false   # or with backend depending on your setup
terraform validate

You can choose whether init uses the real backend or a local one; the key is that validate runs automatically.

---

Input Variable Validation: Types and Rules

Terraform also validates values going into your modules via input variables. There are three important layers.

1. Type Constraints

Every variable can and should declare a type: string, number, bool, complex types such as list(string) or object({ ... }). Terraform will reject values that do not conform.

Example:

variable "tags" {
  type = map(string)
}

Passing a list here fails fast, long before any resource is created.

2. Required vs Optional

• Variables without a default are required; if the caller does not supply a value, Terraform fails at validation time.
• Variables with a default are optional; they still participate in type and custom validation.

This lets you express what callers must always provide versus what can be inferred or defaulted.

3. Custom validation Blocks

Inside each variable block you can define one or more validation blocks.

Each block has:

• condition: a boolean expression evaluated against the value.
• error_message: a human‑readable message if the condition is false.

Example patterns from common practice include:

• Membership checks with contains or regex.
• Ranges and integer checks for numbers.
• Multiple validation blocks to capture several independent rules.

The rationale here is strong: you make invalid states unrepresentable at the module boundary, rather than having to handle them deep inside resource logic.

---

Beyond Variables: Preconditions and Postconditions

Terraform also lets you validate assumptions around resources and data sources using precondition and postcondition blocks.

• A precondition asserts something must be true before Terraform creates or updates the object (for example, an input computed from multiple variables is within bounds).
• A postcondition asserts something must be true after the resource or data source is applied (for example, an attribute returned by the provider matches expectations).

Conceptually:

• Variable validation guards inputs to modules.
• Preconditions/postconditions guard behaviour of resources and data sources exposed by those modules.

For a team consuming your module, this is powerful: they get immediate, clear errors about violated invariants instead of mysterious provider failures later.

---

A Simple Example (Format + Validate + Variable Rules)

Below is a small, self‑contained configuration you can run locally to see formatting and validation in action.

Files

Create the files.

variables.tf:

variable "environment" {
  description = "Deployment environment."
     type        = string

  validation {
    condition     = contains(["dev", "test", "prod"], var.environment)
    error_message = "Environment must be one of: dev, test, prod."
  }
}

variable "app_name" {
  description = "Short application name used in resource naming."
  type        = string

  validation {
    condition     = can(regex("^[a-z0-9-]{3,20}$", var.app_name))
    error_message = "app_name must be 3-20 chars, lowercase letters, digits, and hyphens only."
  }
}

variable "instance_count" {
  description = "Number of instances to run."
  type        = number

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

  validation {
    condition     = !(var.environment == "prod" && var.instance_count < 3)
    error_message = "In prod, instance_count must be at least 3."
  }
}

This demonstrates:

• Type constraints on all inputs.
• A small “enumeration” for environment.
• A format rule enforced via regex on app_name.
• Multiple independent validation rules on instance_count, including one that depends on environment.

main.tf:

terraform {
  required_version = ">= 1.5.0"
}

locals {
  app_tag = "${var.app_name}-${var.environment}"
}

output "example_tags" {
  value = {
    Environment = var.environment
    App         = var.app_name
    Count       = var.instance_count
    AppTag      = local.app_tag
  }
}

Step 1 – Format the Code

From inside the folder:

terraform fmt -recursive

Observe that Terraform will adjust spacing/indentation if you intentionally misalign something and run it again. This confirms fmt is active and working.

Step 2 – Initialize

terraform init

No providers are actually used here, but validate requires initialization.

Step 3 – Structural Validation

Run:

terraform validate

This checks syntax, references, and type soundness of the configuration itself.

If you see:

Success! The configuration is valid.

you know the configuration is structurally sound.

Step 4 – Test Variable Validation with plan and -var

To exercise your variable validation logic with specific values, use terraform plan with -var flags.

1. Valid input:

   terraform plan -var="environment=dev" -var="app_name=demo-app" -var="instance_count=2"

   • Here -var is supported and your custom validation blocks are evaluated.
   • This should succeed, producing a plan (no resources, but the important part is that there are no validation errors).

2. Invalid environment:

   terraform plan -var="environment=stage" -var="app_name=demo-app" -var="instance_count=2"

   Expect Terraform to fail with the custom environment error message from the validation block.

3. Invalid app name:

   terraform plan -var="environment=dev" -var="app_name=Demo_App" -var="instance_count=2"

   You should see the regex‑based app_name error.

4. Invalid prod count:

   terraform plan -var="environment=prod" -var="app_name=demo-app" -var="instance_count=1"

   Here, the environment is valid and the type is correct, but the cross‑rule on instance_count fails with your custom prod message.

Optional – Use *.tfvars Instead of -var

If you prefer files over command‑line flags, create dev.auto.tfvars:

environment    = "dev"
app_name       = "demo-app"
instance_count = 2

Then just run:

terraform plan

Terraform will automatically load *.auto.tfvars files and apply the same variable validations.

---

Recommended Pattern for Teams

Updated to reflect current behaviour:

• Run terraform fmt -check -recursive and terraform validate in CI on every PR.
• Use terraform plan (with -var or *.tfvars) to exercise and gate variable validations for concrete environments (dev, test, prod).
• Enforce types and validation blocks on all externally visible variables, not just a handful.
• Use preconditions and postconditions where module consumers must rely on specific guarantees from your resources.

From an engineering‑lead perspective, this gives you a clear division of responsibilities:

• fmt → canonical style.
• validate → structural soundness of the configuration.
• plan (with variables) → semantic correctness of inputs and module contracts.

Terraform configurations are built out of blocks. Understanding block types is critical because they define how you declare infrastructure, wire modules together, and control Terraform’s behavior.

---

1. The Anatomy of a Block

Every Terraform block has the same basic shape:

TYPE "label1" "label2" {
  argument_name = expression

  nested_block_type {
    # ...
  }
}

Key parts:

• Type: The keyword at the start (resource, provider, variable, etc.). This tells Terraform what kind of thing you are defining.
• Labels: Extra identifiers whose meaning depends on the block type.
  • Example: resource "aws_instance" "web"
  • Type: resource
  • Labels: "aws_instance" (resource type), "web" (local name)
• Body: The { ... } section, which can contain:
  • Arguments: name = expression
  • Nested blocks: block_type { ... }

Rationale: The consistent shape makes the language predictable. Block type + labels define what the block is; the body defines how it behaves or is configured.

---

2. Core Top-Level Block Types

These blocks usually appear at the top level of your .tf files and together they define a module: its inputs, logic, and outputs.

2.1 terraform block

Configures Terraform itself:

• Required providers and their versions.
• Required Terraform version.
• Backend configuration (usually via a nested backend block in terraform).

Example:

terraform {
  required_version = ">= 1.6.0"

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

Rationale: Keeps tooling constraints explicit and version-pinned, so behavior is deterministic across environments and team members.

---

2.2 provider block

Configures how Terraform talks to an external API (AWS, Azure, GCP, Kubernetes, etc.):

provider "aws" {
  region = var.aws_region
}

Typical aspects:

• Credentials and regions.
• Aliases for multiple configurations (e.g., provider "aws" { alias = "eu" ... }).

Rationale: Providers are the “drivers” Terraform uses to translate configuration into real infrastructure; separating them lets you re-use the same module with different provider settings.

---

2.3 resource block

Declares infrastructure objects Terraform will create and manage.

resource "aws_s3_bucket" "this" {
  bucket = "${local.name}-bucket"
}

Structure:

• Type label: the provider-specific resource type ("aws_s3_bucket").
• Name label: a local identifier ("this", "web", "db", etc.).
• Body: arguments and nested blocks that define the resource’s configuration.

Rationale: The resource block is the heart of Terraform; it expresses desired state. Every apply tries to reconcile actual infrastructure with what these blocks declare.

---

2.4 data block

Reads information about existing objects without creating anything.

data "aws_ami" "latest_amazon_linux" {
  most_recent = true

  filter {
    name   = "name"
    values = ["amazon-linux-2-*"]
  }

  owners = ["amazon"]
}

You reference it as data.aws_ami.latest_amazon_linux.id.

Rationale: Data sources decouple “lookup” from “creation”. You avoid hardcoding IDs/ARNs and can dynamically discover things like AMIs, VPC IDs, or roles.

---

2.5 variable block

Defines inputs to a module:

variable "aws_region" {
  type        = string
  description = "AWS region to deploy into"
  default     = "us-west-2"
}

Key fields:

• type: basic or complex types (string, number, list, map, object, etc.).
• default: makes a variable optional.
• description: documentation for humans.

Rationale: Explicit inputs make modules reusable, testable, and self-documenting. They are your module’s API.

---

2.6 output block

Exposes values from a module:

output "bucket_name" {
  value       = aws_s3_bucket.this.bucket
  description = "Name of the S3 bucket created by this module."
}

Rationale: Outputs are your module’s return values, allowing composition: root modules can print values, and child modules can feed outputs into other modules or systems (e.g., CI/CD).

---

2.7 locals block

Defines computed values for use within a module:

locals {
  name_prefix = "demo"
  bucket_name = "${local.name_prefix}-bucket"
}

Notes:

• You can have multiple locals blocks; Terraform merges them.
• Access them via local.<name>.

Rationale: Locals centralize derived values and remove duplication. That keeps your configuration DRY and easier to refactor.

---

3. Nested Blocks vs Arguments

Within a block body you use two constructs:

• Arguments: key = expression
  Example: bucket = "demo-bucket".

• Nested blocks: block_type { ... }
  Example:

  resource "aws_instance" "web" {
  ami           = data.aws_ami.latest_amazon_linux.id
  instance_type = "t3.micro"
  
  network_interface {
    device_index = 0
    network_interface_id = aws_network_interface.web.id
  }
  }

Why have both?

• Arguments are single values; they are the usual “settings”.
• Nested blocks model structured, often repeatable configuration sections (e.g., ingress rules in security groups, network_interface, lifecycle, tag blocks in some providers).

Rationale: Using nested blocks for structured/repeated sections keeps complex resources readable and makes it clear which values logically belong together.

---

4. Meta-Arguments and Lifecycle Blocks

Some names inside a resource are meta-arguments understood by Terraform itself rather than by the provider:

Common meta-arguments:

• depends_on: Add explicit dependencies when Terraform’s graph inference isn’t enough.
• count: Create multiple instances of a resource using integer indexing.
• for_each: Create multiple instances keyed by a map or set.
• provider: Pin a resource to a specific provider configuration (e.g., aws.eu).
• lifecycle: Special nested block that controls create/update/destroy behavior.

Example lifecycle:

resource "aws_s3_bucket" "this" {
  bucket = "${local.name}-bucket"

  lifecycle {
    prevent_destroy       = true
    ignore_changes        = [tags]
    create_before_destroy = true
  }
}

Rationale: Meta-arguments give you control over resource orchestration rather than definition. They let you express cardinality, ordering, and safety rules without resorting to hacks or external tooling.

---

5. Putting It All Together

Below is a small but coherent configuration that demonstrates the main block types and how they interact. You can drop this into an empty directory as main.tf.

terraform {
  required_version = ">= 1.6.0"

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

variable "aws_region" {
  type        = string
  description = "AWS region to deploy into (used by LocalStack as well)"
  default     = "us-east-1"
}

locals {
  project = "block-types-localstack-demo"
  bucket  = "${local.project}-bucket"
}

provider "aws" {
  region  = var.aws_region

  # Dummy credentials – LocalStack doesn’t actually validate them.
  access_key = "test"
  secret_key = "test"

  # Talk to LocalStack instead of AWS.
  s3_use_path_style           = true
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    s3 = "http://localhost:4566"
    sts = "http://localhost:4566"
  }
}

# This data source will return the LocalStack “test” account (000000000000).
data "aws_caller_identity" "current" {}

resource "aws_s3_bucket" "this" {
  bucket = local.bucket

  tags = {
    Project = local.project
    Owner   = data.aws_caller_identity.current.account_id
  }

  lifecycle {
    prevent_destroy = true
  }
}

output "bucket_name" {
  value       = aws_s3_bucket.this.bucket
  description = "The name of the created S3 bucket."
}

output "account_id" {
  value       = data.aws_caller_identity.current.account_id
  description = "AWS (LocalStack) account ID used for this deployment."
}

What this example shows

• terraform block: pins Terraform and the AWS provider.
• variable: input for region.
• locals: internal naming logic.
• provider: AWS configuration.
• data: a data source reading your current AWS identity.
• resource: S3 bucket, including nested lifecycle and tags.
• output: exposes bucket name and account ID.

How to Run and Validate with LocalStack

1. Start LocalStack (for example, via Docker):

   docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack

   This exposes the LocalStack APIs on http://localhost:4566 as expected by the provider config.

2. Initialize Terraform:

   terraform init

3. Format and validate:

   terraform fmt -check
   terraform validate

4. Plan and apply against LocalStack:

   terraform plan
   terraform apply

   Confirm with yes when prompted. Terraform will create the S3 bucket in LocalStack rather than AWS; the dummy credentials and endpoint mapping make this safe for local experimentation.

5. Check outputs:

   terraform output
   terraform output bucket_name
   terraform output account_id

6. Configure profile

   aws configure --profile localstack

7. Verify in LocalStack (using AWS CLI configured to point to LocalStack):

   aws --endpoint-url http://localhost:4566 s3 ls --profile localstack

   You should see the bucket named in bucket_name. LocalStack typically uses test credentials and a default account ID of 000000000000.

8. Destroy (noting prevent_destroy)

   Because of prevent_destroy = true, terraform destroy will refuse to delete the bucket. That’s intentional, to illustrate the lifecycle block. Remove prevent_destroy, run terraform apply again, then:

   terraform destroy

---

6. A Quick Comparison Table

To solidify the concepts, here is a concise comparison of key block types:

Block type	Purpose	Typical labels	Commonly uses nested blocks
terraform	Configure Terraform itself	None	required_providers, backend
provider	Configure connection to an API	Provider name (e.g., "aws")	Occasionally provider-specific blocks
resource	Declare managed infrastructure	Resource type, local name	lifecycle, provisioner, provider-specific
data	Read existing infrastructure	Data source type, local name	Provider-specific nested blocks
variable	Define module inputs	Variable name	None (just arguments)
output	Expose module outputs	Output name	None (just arguments)
locals	Define internal computed values	None	None (just arguments)

Terraform sits at the center of modern Infrastructure as Code (IaC) practice: we describe infrastructure in text, keep it in Git, and let an engine reconcile desired state with real-world cloud APIs.

---

Infrastructure as Code (IaC)

Infrastructure as Code is the practice of managing and provisioning infrastructure through machine‑readable configuration files rather than interactive configuration tools or consoles. The crucial mental shift is to treat infrastructure the same way you treat application code: versioned, reviewed, and automated.

Key characteristics:

• Declarative definitions
  You describe what infrastructure you want (VPCs, subnets, instances, load balancers) instead of scripting how to create it step by step.
• Version controlled
  Configurations live in Git (or similar), so you get history, diffs, branching, and pull requests for infra changes.
• Repeatable and consistent
  The same configuration, with different inputs (variables, workspaces), can stand up dev, test, and prod environments that are structurally identical.
• Testable and reviewable
  Changes are peer‑reviewed, validated via plans, policy checks, and possibly automated tests in CI/CD, instead of ad‑hoc console clicks.

The rationale is straightforward: we already know how to manage complexity in software systems with code and discipline; IaC applies those same practices to infrastructure.

---

What is Terraform?

Terraform is a declarative Infrastructure as Code tool created by HashiCorp that provisions and manages infrastructure across many platforms (AWS, Azure, GCP, Kubernetes, on‑prem, and various SaaS APIs). You express your desired infrastructure using HashiCorp Configuration Language (HCL), and Terraform figures out the necessary operations to reach that state.

Conceptually, Terraform:

1. Reads your configuration, which represents the desired state.
2. Compares it to its state plus the actual infrastructure.
3. Constructs an execution plan describing the required changes.
4. Applies the plan by calling provider APIs in the correct dependency order.

Why this model is powerful:

• Multi‑cloud, single workflow
  The same CLI, syntax, and mental model work across different clouds and services.
• State‑aware
  Terraform tracks what it has created, so it can safely update or destroy resources without guesswork.
• Ecosystem and reuse
  A rich registry of modules and providers enables you to stand on others’ shoulders instead of rebuilding common patterns.

In essence, Terraform acts as a reconciliation engine: it continuously aligns reality with the infrastructure state you declare in code.

---

Core Components of Terraform

While Terraform’s architecture is modular, you mainly interact with a small set of core concepts.

CLI and Core Engine

The CLI (terraform) is your main interface. Terraform Core:

• Parses HCL configuration files.
• Builds a dependency graph of resources and data sources.
• Compares configuration and state to determine what must change.
• Produces an execution plan and applies it while respecting dependencies.

The dependency graph is central: it ensures, for example, that networks exist before instances are created, and databases exist before applications that depend on them.

Providers

Providers are plugins that encapsulate the logic for talking to external APIs such as AWS, Azure, GCP, Kubernetes, GitHub, Datadog, and many others. Each provider:

• Defines available resource types and data sources.
• Implements create, read, update, and delete semantics for those resources.
• Handles authentication and low‑level API interactions.

The rationale is separation of concerns: Terraform Core stays generic, while providers handle domain‑specific details of each platform.

Resources

Resources are the primitive units of infrastructure in Terraform. Each resource represents a managed object, such as:

• A virtual machine or container cluster.
• A network component (VPC, subnet, load balancer).
• A managed service instance (database, cache, queue).

Terraform manages the full lifecycle of resources: creation, in‑place update when possible, replacement when required, and destruction when no longer desired.

Data Sources

Data sources allow configurations to read information from providers without managing the lifecycle of those objects. They are typically used to:

• Look up existing infrastructure (e.g., a VPC or subnet created outside the current configuration).
• Retrieve dynamic values (e.g., the latest AMI matching a filter).
• Integrate with pre‑existing environments instead of forcing everything to be created by the same codebase.

They keep configurations flexible and reduce hard‑coded values, which improves reuse and maintainability.

State and Backends

Terraform uses a state file to map resources in your configuration to real-world objects in the target platforms. This state:

• Stores resource identifiers and metadata.
• Enables Terraform to understand what already exists and what needs to change.
• Is updated after each successful apply.

Backends determine where this state is stored:

• Local backend: state in a file on your machine; fine for experiments and learning.
• Remote backends (e.g., S3, GCS, Terraform Cloud): better for teams, as they support centralized storage, locking, and collaboration.

The rationale is that state is a single source of truth about managed infrastructure, and treating it carefully (remote, locked, backed up) is critical for safe operations.

Modules

Modules are reusable, composable units of Terraform configuration. A module can contain:

• Resources and data sources.
• Variables, outputs, locals, and even submodules.

Reasons to structure code into modules:

• Encapsulation
  Hide low‑level details behind a stable interface of inputs and outputs.
• Reuse
  Apply the same pattern (e.g., a VPC, a Kubernetes cluster, a standard microservice stack) in multiple environments or projects.
• Governance
  Centralize best practices and security controls in shared modules, reducing drift and inconsistent patterns across teams.

Variables, Outputs, and Locals

These language constructs support configurability and clarity:

• Variables
  Declare the inputs your configuration expects (e.g., region, instance type, environment name). They enable per‑environment customization without forking the code.
• Outputs
  Expose selected values after apply (e.g., IP addresses, ARNs, URLs). Outputs are often consumed by other systems or simply used for manual checks.
• Locals
  Store computed values or shared expressions to avoid duplication and encode small bits of logic directly in the configuration.

The rationale is to keep your Terraform code DRY, expressive, and easy to reason about as configurations grow.

---

Typical Terraform Workflow

Terraform promotes a structured workflow that aligns naturally with Git‑based development and CI/CD pipelines. This workflow is crucial to reducing risk and improving predictability.

1. Write Configuration

You start by writing .tf files using HCL:

• Declare providers and their configuration.
• Define resources, data sources, modules, variables, locals, and outputs.
• Organize files logically (root module, submodules, environment dirs).

The focus is on describing the target state of the infrastructure rather than prescribing a sequence of imperative steps.

2. Initialize (terraform init)

You run:

terraform init

This command:

• Downloads required providers and modules.
• Sets up the backend for state (local by default, or remote if configured).
• Prepares the working directory so subsequent commands can function correctly.

Rationale: separating initialization from planning/applying makes dependencies explicit and reproducible, especially across machines or CI runners.

3. Plan (terraform plan)

You run:

terraform plan

Terraform then:

• Reads configuration and current state.
• Queries providers for the real infrastructure state.
• Computes and displays the execution plan, indicating which resources will be created, changed, or destroyed.

The plan serves as your infrastructure “diff,” analogous to git diff for code. In a mature setup, this plan is typically generated as part of a pull request, allowing reviewers to reason about the exact infra impact of a code change before approval.

4. Apply (terraform apply)

You run:

terraform apply

Terraform:

• Either recomputes or uses a previously saved plan.
• Executes the required operations in dependency order.
• Handles partial failures and retries where possible.
• Updates the state file upon successful completion.

The key practice is discipline: operators avoid ad‑hoc console changes, and instead always modify the .tf files, inspect the plan, and then apply. This ensures the code and reality remain aligned.

5. Destroy (terraform destroy)

When you need to decommission an environment, you run:

terraform destroy

Terraform:

• Plans the removal of managed resources.
• Executes deletions in an order that respects dependencies.
• Updates the state so it no longer references removed resources.

This is especially valuable for ephemeral or per‑branch environments and is a powerful tool for cost control and cleanup.

1. Overview and rationale

• LocalStack emulates EC2/VPC APIs locally, so Terraform can create VPCs, subnets, route tables, and gateways just like on AWS.
• The AWS CLI can talk to LocalStack by using --endpoint-url http://localhost:4566, letting you validate resources with the exact same commands you’d run against real AWS.
• This keeps your workflow close to production: same Terraform provider, same CLI, different endpoint.

---

2. Run LocalStack with Docker Compose

Create docker-compose.yml:

version: "3.8"

services:
  localstack:
    image: localstack/localstack:latest
    container_name: localstack
    ports:
      - "4566:4566"              # Edge port: all AWS APIs
      - "4510-4559:4510-4559"    # Optional service ports
    environment:
      - SERVICES=ec2             # Add more: ec2,lambda,rds,ecs,...
      - AWS_DEFAULT_REGION=us-east-1
      - DEBUG=1
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"

Start LocalStack:

docker compose up -d

LocalStack now exposes EC2/VPC on http://localhost:4566 (the edge endpoint).

---

3. Terraform VPC configuration

Keep Terraform AWS‑idiomatic and only change the endpoint.

providers.tf

terraform {
  required_version = ">= 1.6.0"

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

provider "aws" {
  region                      = "us-east-1"
  access_key                  = "test"
  secret_key                  = "test"
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true
  s3_use_path_style           = true

  endpoints {
    ec2 = "http://localhost:4566"
  }
}

main.tf

resource "aws_vpc" "demo" {
  cidr_block           = "10.0.0.0/16"
  enable_dns_support   = true
  enable_dns_hostnames = true

  tags = {
    Name = "localstack-demo-vpc"
  }
}

resource "aws_subnet" "public_az1" {
  vpc_id                  = aws_vpc.demo.id
  cidr_block              = "10.0.1.0/24"
  availability_zone       = "us-east-1a"
  map_public_ip_on_launch = true

  tags = {
    Name = "localstack-demo-public-az1"
  }
}

resource "aws_internet_gateway" "igw" {
  vpc_id = aws_vpc.demo.id

  tags = {
    Name = "localstack-demo-igw"
  }
}

resource "aws_route_table" "public" {
  vpc_id = aws_vpc.demo.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.igw.id
  }

  tags = {
    Name = "localstack-demo-public-rt"
  }
}

resource "aws_route_table_association" "public_az1_assoc" {
  subnet_id      = aws_subnet.public_az1.id
  route_table_id = aws_route_table.public.id
}

output "vpc_id" {
  value = aws_vpc.demo.id
}

output "public_subnet_id" {
  value = aws_subnet.public_az1.id
}

Apply:

terraform init
terraform apply

This models the classic “public subnet” layout so the same module can later be pointed at real AWS with only a provider change.

4. Configure AWS CLI for LocalStack

You can use the stock AWS CLI v2 and override the endpoint.

1. Configure a local profile (optional but tidy):

aws configure --profile localstack
# AWS Access Key ID: test
# AWS Secret Access Key: test
# Default region name: us-east-1
# Default output format: json

2. For each command, add:

--endpoint-url http://localhost:4566 --profile localstack

This tells the CLI to send EC2 API calls to LocalStack instead of AWS.

If you prefer less typing, you can define an alias (e.g. in your shell):

alias awslocal='aws --endpoint-url http://localhost:4566 --profile localstack'

This is conceptually the same as the awslocal wrapper LocalStack provides, but you stay completely within standard AWS CLI semantics.

---

5. Validating the VPC with AWS CLI

After terraform apply, use the CLI to verify each piece of the VPC.

5.1 List VPCs

aws ec2 describe-vpcs --endpoint-url http://localhost:4566 --profile localstack

or with the alias:

awslocal ec2 describe-vpcs

Check for a VPC with:

• CidrBlock = 10.0.0.0/16
• Tag Name = localstack-demo-vpc

The shape of the output is identical to real AWS describe-vpcs.

5.2 List subnets

awslocal ec2 describe-subnets

Confirm a subnet exists with:

• CidrBlock = 10.0.1.0/24
• AvailabilityZone = us-east-1a
• Tag Name = localstack-demo-public-az1

5.3 List Internet Gateways

awslocal ec2 describe-internet-gateways

You should see an IGW whose Attachments includes your VPC ID and has tag localstack-demo-igw.

5.4 List route tables

awslocal ec2 describe-route-tables

Verify:

• A route table tagged localstack-demo-public-rt.
• A route with DestinationCidrBlock 0.0.0.0/0 and GatewayId set to your IGW ID.
• An association to your public subnet ID.

These commands mirror the official AWS CLI usage for EC2, just with the endpoint overridden.

6. Why this testing approach scales

• Uses only Terraform + AWS CLI, tools you already depend on in real environments.
• Easy to script: you can wrap the CLI checks into bash scripts or CI jobs to assert your VPC configuration in LocalStack before promoting to AWS.
• Mental model stays aligned with production AWS: same commands, same JSON structures, just a different base URL.

This article shows how to run a local AWS‑like S3 environment with LocalStack in Docker, manage buckets with Terraform, and inspect everything visually using an S3 GUI client such as S3 Browser (or any S3‑compatible desktop app).

---

1. Overview of the setup

You will end up with:

• LocalStack running via docker-compose.yml, exposing S3 on http://localhost:4566.
• Terraform creating an S3 bucket, enabling versioning, and adding a lifecycle rule.
• S3 Browser (or a similar S3 GUI) connected to LocalStack so you can see buckets and object versions visually.

Rationale: this mirrors a real AWS workflow (Infra as Code + GUI) while remaining entirely local and safe to experiment with.

---

2. LocalStack with docker-compose.yml

Create a working directory, e.g. localstack-s3-terraform, and add docker-compose.yml:

version: "3.8"

services:
  localstack:
    image: localstack/localstack:latest
    container_name: localstack
    ports:
      - "4566:4566"          # Edge port: all services, including S3
      - "4510-4559:4510-4559"
    environment:
      - SERVICES=s3          # Only start S3 for this demo
      - DEBUG=1
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - "./localstack-data:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

Key aspects:

• Port 4566 is the single “edge” endpoint for S3 and other services in current LocalStack.
• SERVICES=s3 keeps the environment focused and startup fast.
• ./localstack-data persists LocalStack state (buckets and objects) between restarts.

Start LocalStack:

docker compose up -d

---

3. Terraform config with versioning and lifecycle

In the same directory, create main.tf containing the AWS provider configured for LocalStack and S3 with versioning + lifecycle policy:

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

provider "aws" {
  region                      = "ap-southeast-2"
  access_key                  = "test"
  secret_key                  = "test"
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true
  s3_use_path_style           = true

  endpoints {
    s3 = "http://localhost:4566"
  }
}

resource "aws_s3_bucket" "demo" {
  bucket = "demo-bucket-localstack"
}

resource "aws_s3_bucket_versioning" "demo_versioning" {
  bucket = aws_s3_bucket.demo.id

  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_lifecycle_configuration" "demo_lifecycle" {
  bucket = aws_s3_bucket.demo.id

  rule {
    id     = "expire-noncurrent-30-days"
    status = "Enabled"

    filter {
      prefix = "" # apply to all objects
    }

    noncurrent_version_expiration {
      noncurrent_days = 30
    }
  }
}

Important Terraform points:

• Provider: points to http://localhost:4566 so all S3 calls go to LocalStack, not AWS.
• Dummy credentials (test / test) are sufficient; LocalStack doesn’t validate real AWS keys.
• Versioning is modeled as a separate resource to clearly express bucket behavior.
• Lifecycle configuration is modeled explicitly as well, aligning with AWS best practices and lifecycle examples.

Initialize and apply:

terraform init
terraform apply

Confirm when prompted; Terraform will create the bucket, enable versioning, and attach the lifecycle rule.

---

4. Configuring S3 Browser (or similar GUI) for LocalStack

Now that LocalStack is running and Terraform has created your bucket, you connect S3 Browser (or any S3 GUI) to LocalStack instead of AWS.

In S3 Browser, create a new account/profile with something like:

• Account name: LocalStack (any label you like).
• S3 endpoint / server: http://localhost:4566
• Access key: test
• Secret key: test
• Region: ap-southeast-2

Make sure your client is configured to use the custom endpoint instead of the standard AWS endpoints (this is usually done in an “S3 Compatible Storage” as the Account Type).

Once saved and connected:

• You should see the bucket demo-bucket-localstack in the bucket list.
• Opening the bucket lets you upload, delete, and browse objects, just as if you were talking to real S3.