Remote State Configuration

Remote state tells Terraform where to read and write its canonical state file when working with shared environments. This article explains how to configure remote state using Terraform backends, what options you typically need to set, and best practices for collaboration and locking. Remote-state configuration is declared inside a top-level terraform block using a backend configuration. The structure is identical across backends (except for HCP Terraform, which uses a cloud block instead of backend). Key concepts:

Backend type — declares where state is stored (for example: s3, azurerm, gcs, remote).
Backend configuration — provider-specific options that tell Terraform how to access that backend (for example: bucket/container name, key/path, region).
State locking — prevents concurrent state writes and reduces the risk of corruption.

Example general structure:

terraform {
  backend "TYPE" {
    # Backend-specific configuration
  }
}

Always run terraform init after adding or changing a backend. Terraform must reinitialize the backend and may need to migrate existing state to the new location.

Important notes:

Put backend configuration only in the top-level terraform block — do not place it in provider blocks.
After adding or changing a backend, run terraform init so Terraform can configure and initialize the backend and (if necessary) migrate existing state.

Backend configuration components (at-a-glance)

Component	Purpose	Typical examples
Backend type	Selects where Terraform stores state	`s3`, `azurerm`, `gcs`, `remote`
Backend configuration	Backend-specific access and path settings	`bucket`, `key`, `region`, `storage_account_name`
Locking	Prevents concurrent modifications to state	`dynamodb_table` for S3, blob leases for Azure

Example: S3 backend (AWS)

The s3 backend stores Terraform state in an S3 bucket. Common attributes:

bucket — the S3 bucket name
key — object path within the bucket (for example, envs/prod/terraform.tfstate)
region — AWS region for the bucket
dynamodb_table — (optional but recommended) DynamoDB table name used to enable state locking
encrypt — whether to enable SSE for the stored object

Create the S3 bucket and DynamoDB table for locking before pointing Terraform at the backend (these resources are typically provisioned separately from the main infrastructure). This prevents bootstrap dependency problems and avoids committing credentials in code. Example S3 backend configuration:

terraform {
  backend "s3" {
    bucket         = "prd-terraform-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-lock"
    encrypt        = true
  }
}

Notes on S3 locking:

The dynamodb_table attribute enables robust locking using a DynamoDB table — a common, reliable pattern for multi-user collaboration.
For the latest backend behaviors and options, consult the official Terraform backend documentation.

Example: Azure Blob Storage backend

The azurerm backend stores state in an Azure Storage account blob container. Typical settings:

storage_account_name — the storage account
container_name — the blob container that holds the state
key — the blob name (path)
Authentication — supports managed identities, environment variables, Azure CLI, or service principal credentials

Example azurerm backend configuration (do not hard-code secrets in production):

terraform {
  backend "azurerm" {
    storage_account_name = "prod-terraform"
    container_name       = "tfstate"
    key                  = "prod.terraform.tfstate"
  }
}

Do not hard-code credentials (tenant IDs, client secrets, etc.) in backend configuration. Use managed identities, Azure roles, environment variables, or CLI authentication for secure access.

Note on locking:

The Azure backend uses blob leases for locking and manages this automatically; you typically do not need a separate locking resource.

Local vs Remote state — when to use which

Local state (default): Terraform stores terraform.tfstate in your working directory. It is convenient for single-developer workflows, learning, and quick experiments. Remote state: Store state in a centralized backend (S3, Azure Storage, GCS, Terraform Cloud, etc.) for team collaboration and reliability. Comparison

Aspect	Local state	Remote state
Team collaboration	Poor — file on one machine	Good — single source of truth
Locking	None	Supported (DynamoDB, blob leases, etc.)
Backups / versioning	Manual	Often automatic/versioned by provider
Security	File-level; must secure manually	Access controls, encryption supported
Use cases	Learning, prototypes, single-user tasks	Production, team workflows, CI/CD

Best practices:

Use local state only for learning, prototypes, or one-person projects.
Use remote state with locking for team and production workloads.
Never hard-code credentials in backend configurations — prefer IAM roles, managed identities, or environment-based authentication.
Plan and test state migration carefully before moving existing state to a new backend.
Always run terraform init after changing backend configuration.

Course Introduction

Preparing Your Environment

Terraform Foundations

The Core Terraform Workflow

Terraform CLI

Terraform File Structure and Organization

Terraform Configuration - Fundamentals

Understading and Managing Terraform State

Marking Code Reusable

Refactoring Terraform State

Terraform Modules

Managing Resource Behavior and Dependencies

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

Remote State Configuration

Example: S3 backend (AWS)

Example: Azure Blob Storage backend

Local vs Remote state — when to use which

Links and references

Watch Video

​Example: S3 backend (AWS)

​Example: Azure Blob Storage backend

​Local vs Remote state — when to use which

​Links and references

Watch Video

Example: S3 backend (AWS)

Example: Azure Blob Storage backend

Local vs Remote state — when to use which

Links and references