Terraform Backends: Unpacking the Difference Between Default and Explicit Local State

Introduction

Terraform manages infrastructure through state files, which record the resources created and their configurations. How and where this state is stored is determined by the backend configuration. A common point of confusion arises regarding Terraform’s default behavior: is omitting a backend configuration truly the same as explicitly setting it to local? This post delves into the subtle yet significant differences and explains why understanding them is crucial, especially when using migration tools.

Understanding Terraform’s Default Behavior: No Backend Specified

When a Terraform configuration file lacks an explicit backend block, Terraform doesn’t simply fail; it falls back to a default setting.

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

In this scenario:

Implicit Local Backend: Terraform automatically uses the local backend type.
State File Location: The state file, named terraform.tfstate, is created and managed directly within your current working directory where you run Terraform commands.
Standard Initialization: Running terraform init initializes the providers but doesn’t specifically mention configuring a backend, as it’s using the implicit default.
State Content: After a terraform apply, the terraform.tfstate file in the root directory contains the details of the managed resources, versioning information, and a unique lineage identifier.

# Example terraform.tfstate content (no backend block specified)
{
  "version": 4,
  "terraform_version": "1.11.4",
  "serial": 1,
  "lineage": "aa6393bf-3f16-a14b-6d7b-2f120aa28239",
  "outputs": {},
  "resources": [
    {
      "mode": "managed",
      "type": "aws_s3_bucket",
      "name": "this",
      # ... resource details ...
    }
  ]
}

This default behavior is simple and suitable for single-developer projects or initial testing, but lacks features like remote storage, locking, and collaboration support.

Explicitly Configuring the Local Backend

Alternatively, the local backend can be explicitly defined within the terraform block.

terraform {
  backend "local" {
    path = "./terraform.tfstate" # Specifies the state file path
  }

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

When configured explicitly:

Explicit Local Backend: Terraform is clearly instructed to use the local backend.
Configurable State Path: The path argument allows specifying exactly where the state file should be stored relative to the working directory. Other options like workspace_dir can also be set.
Specific Initialization: Running terraform init will explicitly confirm that the local backend has been successfully configured.
State File Location: After terraform init, Terraform creates backend-specific metadata within the .terraform directory. A file named terraform.tfstate often appears inside .terraform containing metadata about the backend configuration itself.
State Content: After a terraform apply, the actual infrastructure state is written to the file specified by the path argument (e.g., ./terraform.tfstate in the root directory).

The state file inside the .terraform directory looks different; it records the backend configuration:

# Example .terraform/terraform.tfstate content (explicit local backend)
{
  "version": 3,
  "terraform_version": "1.11.4",
  "backend": {
    "type": "local",
    "config": {
      "path": "./terraform.tfstate",
      "workspace_dir": null
    },
    "hash": 2676510787
  }
}

The state file at the configured path (e.g., root directory) contains the resource information, similar to the implicit case:

# Example ./terraform.tfstate content (explicit local backend)
{
  "version": 4,
  "terraform_version": "1.11.4",
  "serial": 1,
  "lineage": "805a28e9-d69a-3fef-84ca-f96d1cb21b11",
  "outputs": {},
  "resources": [
    {
      "mode": "managed",
      "type": "aws_s3_bucket",
      "name": "this",
      # ... resource details ...
    }
  ]
}

Why This Distinction Matters: Impact on Tooling (like tfmigrate)

While the end result (a local terraform.tfstate file) might seem similar, the explicit configuration provides crucial metadata that some tools rely on. tfmigrate is a utility designed to assist in migrating Terraform state between different backend types, particularly to HashiCorp Cloud Platform (HCP) Terraform or Terraform Enterprise.

The Challenge with Implicit Backends:

When tfmigrate analyzes a Terraform configuration without an explicit backend block, it may struggle to determine the source backend type correctly. This often leads to failures during the migration preparation phase.

Example output when tfmigrate prepare is run on a configuration with no explicit backend:

tf-migrate prepare
✓ Current working directory: ####/tfmigrate
...
✓ Found 1 directories with Terraform files
┌────────────────────────────┐
│ Terraform File Directories │
├────────────────────────────┤
│ tfmigrate                  │
└────────────────────────────┘
The following 1 directories were skipped:
  •  .
as they either have no backend, no supported backend to migrate or were excluded based on user-specified skip-dir arguments.

All 1 directories either have errors or do not have a supported backend to migrate. No migration config will be generated

The Advantage of Explicit Backends:

By explicitly defining the local backend, tfmigrate can reliably identify the source configuration and proceed with generating the necessary migration plan.

terraform {
  backend "local" {
    path = "terraform.tfstate"
  }
  # ... rest of the configuration
}

Example output when tfmigrate prepare is run on a configuration with an explicit local backend:

tf-migrate prepare
✓ Current working directory: ####/tfmigrate
...
✓ Found 3 HCP Terraform organizations
...
Enter the name of the HCP Terraform organization to migrate to:  manu-org
✓ You have selected organization manu-org for migration
✓ Found 1 directories with Terraform files
┌────────────────────────────┐
│ Terraform File Directories │
├────────────────────────────┤
│ tfmigrate                  │
└────────────────────────────┘
✓ Migration config generation completed

Conclusion

While Terraform defaults to a local backend if none is specified, explicitly configuring backend "local" {} is not merely redundant. It provides clearer intent, allows for customization (like setting a specific path), and ensures compatibility with tools like tfmigrate that depend on explicit backend definitions for tasks such as state migration. Although one could argue that for simple local-to-remote migrations, directly changing the backend configuration block might suffice, understanding this difference is key for managing more complex scenarios and ensuring tooling works as expected.

How Innovative Software Technology Can Help

Navigating Terraform backend configurations and state management complexities is crucial for robust infrastructure-as-code practices. At Innovative Software Technology, we specialize in optimizing Terraform workflows for peak performance and reliability. Our seasoned experts can guide your team through best practices for backend selection, comparing local versus remote state trade-offs tailored to your needs. We ensure seamless state migrations, whether using tools like tfmigrate or native Terraform commands, and implement automation strategies for efficient cloud infrastructure management. Partner with Innovative Software Technology for expert Terraform consulting and managed services to enhance the scalability, security, and cost-effectiveness of your systems through superior infrastructure automation.