Terraform Local State: Local Operations and Caveats (Associate Guide)

Terraform keeps the metadata and dependencies of real resources in tfstate. When no backend is specified, the local state file (terraform.tfstate) is used by default.

Local operation is great for quick experiments, but you need to watch out for team use, confidentiality, and availability requirements. The Associate exam tests whether you understand the nature, limits, and safe migration paths of local state.

Local state basics

When you don't explicitly declare a backend, Terraform creates terraform.tfstate (JSON) in the working directory and stores the IDs, attributes, and dependencies of managed resources there. This is essential for computing diffs against the real world and for references (data sources, outputs).

The local backend does not provide state locking. In other words, there is no protection when multiple processes update the same state at the same time. It does not fit team workflows or automated concurrent runs.

tfstate can contain secret-equivalent values. With the local backend nothing is encrypted, so you depend on OS file permissions and disk encryption. A .gitignore entry is mandatory to avoid accidentally committing it to VCS.

• Default location: ./terraform.tfstate (working directory)
• Locking: none (no concurrency protection)
• Encryption: none (relies on OS / disk encryption)
• Use cases: solo development, PoCs, throwaway environments
• Caveats: never commit to VCS, minimize file permissions

Local state flow

Minimal setup (no backend declared = local) and basic commands

# main.tf（例）
resource "null_resource" "example" {}

# 初期化と差分
terraform init
terraform plan
terraform apply

# ステートの確認
terraform state list
terraform state show null_resource.example

Operational patterns: single developer and small teams

Local state fits personal experiments, short-lived sandboxes, and ephemeral CI runs (build clean and tear down every time). As long as you don't share the state, the simple setup lets you move fast.

On the other hand, when a team operates on the same environment (the same state), the constraints around locking, auditing, and backup are heavy. Remote backends (S3+DynamoDB, Terraform Cloud/Enterprise, etc.) are the standard choice in production.

• PoCs and learning: quick to set up
• Throwaway environments: low management cost if you tear down after the run
• Team workflows: avoid local state when sharing or concurrent runs are required

Prevent accidental VCS commits (recommended .gitignore)

# .gitignore
terraform.tfstate
terraform.tfstate.backup
.crash.log
.terraform/
*.tfplan
# ステートに派生する一時ファイルも除外

Risks and failure modes of running locally

The biggest risk is concurrent execution. Because the local backend has no lock, two terraform apply runs updating the same tfstate at once can overwrite each other or produce inconsistencies. That leads to duplicated resources or mistaken deletions.

tfstate is also plain JSON and may contain confidential data. Tight access permissions (e.g. chmod 600), disk encryption, and proper management of backup files are mandatory. And once you accidentally commit it to VCS, there is no going back.

When you change resource addresses during refactoring (extracting into modules, introducing for_each, etc.), the safe approach is to reconcile state with commands like terraform state mv / rm / import, not by editing tfstate directly.

• Concurrent-execution conflicts (no locking)
• Leakage of confidential data (plain JSON)
• Accidental commits to VCS
• Corruption from manual edits (broken JSON, address mismatches)
• Unrecoverable state due to inadequate backups

Minimum file protection and safe refactoring

# ファイル権限の強化（Unix系）
chmod 600 terraform.tfstate terraform.tfstate.backup || true

# リソースアドレス変更時の安全な移動
terraform state mv aws_instance.web module.app.aws_instance.web

# 不要エントリの削除（実体リソースは消さない）
terraform state rm aws_security_group.legacy

# 既存リソースの取り込み
terraform import aws_s3_bucket.logs my-logs-bucket

Backup and restore (local)

Taking backups of the state before and after apply makes recovery from corruption straightforward. In addition to cp-based copies, terraform state pull gives you a safe snapshot of the current state.

To restore, use terraform state push to apply the backup. Sticking to state commands for minimal changes is safer than editing JSON directly. Run the restore from a single process on a single machine to avoid version drift and conflicts.

• Back up with pull, restore with push
• Saving the plan file (-out) before apply makes change tracking easy
• Store backups in encrypted storage

Backup and restore in practice

# バックアップの取得（ローカル/リモート双方で有効）
terraform state pull > backup-$(date +%Y%m%d%H%M%S).tfstate

# ローカルバックエンドへの復旧
terraform state push backup-20240101090000.tfstate

# ファイルコピーによる簡易バックアップ
cp terraform.tfstate terraform.tfstate.backup

# 計画ファイルの保存
terraform plan -out=tfplan
# 内容確認
terraform show -json tfplan > tfplan.json

Migrating from local to a remote backend

For team workflows and production, move to a remote backend that gives you locking, sharing, and auditing. S3+DynamoDB offers object versioning plus table-level locking; Terraform Cloud gives you built-in locking and history.

To migrate, add a backend block and run terraform init -migrate-state. Prepare the right credentials (IAM for S3/DynamoDB, a token for Terraform Cloud) and verify consistency afterwards with terraform state list.

• Add a backend block, then migrate via init
• Enable versioning on S3 and prepare a DynamoDB lock table
• Note that state is separated per workspace

Example migration to S3+DynamoDB

# backend設定（versions等は省略）
terraform {
  backend "s3" {
    bucket         = "my-tfstate-bucket"
    key            = "envs/prod/terraform.tfstate"
    region         = "ap-northeast-1"
    dynamodb_table = "my-tf-locks"
    encrypt        = true
  }
}

# 事前準備（例）
# - S3: バージョニング有効、暗号化
# - DynamoDB: パーティションキー=LockID のテーブル
# - IAM: S3/DynamoDBへの適切な権限

# マイグレーション
terraform init -migrate-state

# 検証
terraform state list
terraform plan

Associate exam perspective: key takeaways

The exam tends to ask about the purpose of state, the default local behavior, whether locking exists, how to handle confidential data, backup and restore, and the benefits of remote backends and the migration process. Be sure you can pick the right CLI command for each task.

• No backend declared = local, no locking
• tfstate may contain confidential data; encryption depends on the backend
• Never commit tfstate to VCS; .terraform.lock.hcl serves a different purpose
• Safe changes: terraform state mv/rm/import; direct editing is the last resort
• Backup: terraform state pull; restore: state push (local)
• Team use: remote (S3+DynamoDB or Terraform Cloud) plus locking

Refresher on the commands you'll see most

# ステート操作
terraform state list
terraform state show <address>
terraform state mv <from> <to>
terraform state rm <address>
terraform state pull > backup.tfstate

# 計画と適用
terraform plan -out=planfile
terraform apply planfile

Check yourself with a question

Frequently asked questions