はじめに
TerraformコードはGitで管理するのに、terraform.tfstate はS3などのBackendに置く。
最初は「StateにSecretが入っていなければ、Gitで管理してもよいのでは？」と疑問でした。
調べていくと、StateをGitに置かない理由は機密性だけではありません。
StateはTerraformが実行を続けるために、一貫した最新版を読み書きする管理データでした。
TL;DR
- Stateは、Terraform上のresourceと実物の対応関係などを保持する
- JSONを直接編集すると、AWSより先にTerraformの管理認識が変わる
- Stateは最新版共有と排他制御が必要なので、GitよりState管理向けのBackendと相性がよい
1. Stateは「AWSの現在状態を保存したファイル」だけではない
terraform.tfstate という名前を見ると、
「AWSの現在状態をJSONに保存しているファイル」と捉えたくなります。
実際、Stateにはresourceの属性値も保存されます。
ただ、Stateが必要な理由を理解するうえで先に知りたかったのは、
TerraformのConfigと実世界を結びつける役割でした。
1-1. aws_instance.web と i-0123... は別の名前
TerraformのConfigには、たとえば次のように書きます。
resource "aws_instance" "web" {
ami = "ami-xxxxxxxx"
instance_type = "t3.micro"
}
Terraform上では、このresourceを aws_instance.web として扱えます。
一方、AWS上にできるEC2には、
i-0123456789abcdef0
のようなinstance IDがあります。
AWS側に、
「このEC2はTerraformの aws_instance.web です」
という対応表が自動で存在するわけではありません。
そこでTerraformはStateに、
aws_instance.web
↕
i-0123456789abcdef0
というbindingを保持します。
HashiCorpもStateの目的を説明する中で、
Terraform configとreal worldを対応付けるために何らかのdatabaseが必要であり、
Stateがresourceとremote objectのmappingを持つと説明しています。
Purpose of Terraform State
1-2. mapping以外の情報も入っている
Stateにはbindingだけでなく、
resource dependencyなどのmetadataやresource attributeのcacheも保存されます。
たとえばConfigからresourceを削除した後でも、
TerraformはStateに残った情報を使って、
「どのremote objectを削除する必要があるか」
「どの順番で削除するか」
を判断できます。
なので、
State = AWSの現在状態を丸ごとコピーしたもの
と考えると少し狭いです。
自分の中では、
「Terraformが管理を継続するための運用DB」
と考えると一番整理しやすくなりました。
ここでいう「DB」は理解のための比喩です。RDBのようなデータベース製品という意味ではありません。
2. Stateを直接編集すると、先にTerraformの認識が変わる
StateがTerraformの管理情報なら、
「JSONファイルだからGitで編集してもよい」とは考えにくくなります。
ただし、Stateを書き換えた瞬間にEC2が消えるわけではありません。
ここは自分も最初に混乱したところでした。
2-1. Stateを書き換えても、AWSは即座には変わらない
たとえばStateに、
aws_instance.web ↔ i-0123456789abcdef0
というbindingがあるとします。
これを人間がJSONから手で消しても、
AWS上の i-0123456789abcdef0 はその場では残っています。
変わるのは、Terraform側が持っている管理情報です。
Configには aws_instance.web が存在する。
しかしStateには、それと結びつくremote objectがいない。
この状態で次に terraform plan を実行すると、
Terraformは変更後のStateを入力として判断します。
状況によっては、
+ aws_instance.web will be created
のように、新しいresourceを作るPlanが出ることもあります。
そのPlanを apply すれば、そこで初めて実インフラにも影響します。
つまり、
State手編集
↓
Terraformの管理認識が変わる
↓
planの判断が変わる
↓
applyで実物へ反映される
という順番です。
2-2. 直接JSONを編集せず、Terraformが用意した仕組みを使う
HashiCorpはStateについて、
JSON text fileではあるものの直接編集しないよう明記しています。
State | Terraform
Stateを変更する必要がある場合も、JSONを手で書き換えるのではなく、
Terraformが提供するCLIやconfiguration上の仕組みを使います。
確認だけなら、たとえば次のコマンドがあります。
terraform state list
terraform state show aws_instance.web
一方、resourceをTerraform管理から外したい場合、
現在のHashiCorpドキュメントでは terraform state rm より
removed blockを使う方法が推奨されています。
このときは、対象のresource blockを残したまま横に追加するのではなく、
既存のresource blockをremoved blockへ置き換えます。
removed {
from = aws_instance.web
lifecycle {
destroy = false
}
}
removed blockなら通常の plan / apply workflowの中で
「Stateから外す変更」を確認してから適用できます。
HashiCorpも、結果をpreviewできるため
terraform state rm より安全な方法として推奨しています。
Remove a resource from Terraform state
resourceやmoduleのaddressを変更するリファクタリングでも、
moved blockというconfiguration上の仕組みがあります。
Refactor modules
terraform state rm や terraform state mv 自体が間違いなわけではありません。
CLIが必要な場面もあります。
ここで持ち帰りたいのは、
Stateを変更する必要があっても、State JSONを直接編集するのではなく、
Terraformが提供する操作経路を使う
という境界です。
3. plan と apply の中でStateはどう扱われるのか
Stateを「Terraformが使う管理データ」と捉えると、
普段の plan と apply でいつ読まれ、いつ更新されるのかが気になります。
ここを時系列で見ると、
StateをGitの成果物として扱わない理由がさらに分かりやすくなりました。
3-1. plan はStateを手がかりに現在状態を確認する
通常の terraform plan では、
TerraformはStateにあるbindingを使って管理対象を特定します。
たとえばStateに、
aws_instance.web ↔ i-0123456789abcdef0
があれば、Provider経由でそのEC2のcurrent stateを読み取ります。
そのうえでConfigと照合し、
「変更なし」「update」「replace」「destroy」などの変更案を作ります。
Stateだけを見てPlanを決めるわけでも、
Configだけを見てPlanを決めるわけでもありません。
3-2. apply が終わるとStateも更新される
terraform apply はPlanに基づいてremote systemを変更します。
保存済みPlanを渡さない通常の terraform apply では、
Terraformはその場で新しいexecution planを作ってから実行します。
saved planを渡した場合は、そのPlanを実行します。
変更が完了すると、
Terraformはその結果をStateへ反映します。
prior State
↓
plan
↓
apply
↓
実インフラ変更
↓
new State
このStateが、また次回のTerraform実行で使われます。
なのでStateは、
「人間がレビューして完成させたらcommitするファイル」というより、
Terraformのrunとrunの間をつなぐ管理データ
と見る方が自然でした。
4. 2人が同時に apply したらどうなるのか
Stateをチームで共有するなら、
AさんとBさんが同時にTerraformを実行する可能性があります。
ここで必要になるのがState lockingです。
4-1. lockは「Stateを書き込む瞬間だけ」ではない
Backendがlockingをサポートしている場合、
TerraformはStateを書き得るoperationでlockを取得します。
HashiCorpの説明でも、
state lockingはstateへwriteし得るすべてのoperationで自動的に行われ、
lock取得に失敗した場合は処理を継続しません。
State: Locking
たとえばAさんが apply を開始してlockを取っている間に、
Bさんも同じStateへ apply しようとします。
Bさんはlockを取得できないため、
そのまま競合する処理を進められません。
-lock-timeout を指定すれば、
指定時間はlock取得をretryできます。
terraform apply -lock-timeout=30s
それでも取得できなければエラーになります。
Aさんの処理が終わった後に改めて実行すれば、
その時点の最新Stateから処理を始められます。
4-2. Git conflictで後から解決するのでは遅い
Gitなら、AさんとBさんが同じファイルを変更しても、
pushやmergeの段階でconflictを解消できます。
Stateは性質が違います。
| Gitで管理するコード | Terraform State |
|---|---|
| 複数branchで変更できる | 同じ管理対象では一貫した最新版が必要 |
| diffを見て人間がmergeする | Terraformの管理状態を人間がmergeするのは危険 |
| 変更後にconflictを解消できる | 競合するoperationを先に止めたい |
もしAさんとBさんがそれぞれ古いStateを持って、
両方ともAWSへ変更を加えた後に、
「StateのJSONがconflictしたのでmergeしよう」
となっても遅いです。
すでにremote system側の変更が走っているからです。
Terraform Stateでは、
競合した後にファイルをmergeすることより、
競合するwriterを同時に進めないこと
が必要になります。
4-3. 保存したPlanも永遠に使えるわけではない
terraform plan -out=tfplan で保存したPlanも、
Stateと無関係な静的ファイルではありません。
Planは作成時点のStateを前提にしています。
Aさんが別のrunを apply してStateが変わると、
それ以前のStateを前提にしたsaved planはstaleになり得ます。
ここでは内部の serial や lineage までは覚えなくても、
PlanとStateはセットで整合している必要がある
と分かれば十分だと思います。
5. GitとBackendの境界は「更新主体」だけでは決まらない
ここまでの話を、タイトルの言葉に戻して整理します。
Config側は「インフラをこうしたい」と人間が宣言し、
レビューや変更履歴を残す設計図に近いデータです。
一方のStateは、Terraformがrunをまたいで管理状態を引き継ぐ運用DBに近いデータです。
ただし、
「人間が編集するものはGit、Terraformが編集するものはBackend」
と覚えるだけでは .terraform.lock.hcl が説明できません。
.terraform.lock.hcl は terraform init などでTerraformが作成・更新しますが、
HashiCorpはGitへcommitすることを推奨しています。
一方、terraform.tfstate はcommitしないよう案内しています。
Terraform Style Guide
なので境界は、
「誰がファイルを書き換えるか」だけではありません。
自分は次の2つで考えると整理できました。
| 対象 | 欲しい管理特性 | 管理先 |
|---|---|---|
main.tf |
review・履歴・branchで変更したい | Git |
variables.tf |
review・履歴を残したい | Git |
| Backend設定 | 保存先設定を共有・reviewしたい | Git |
.terraform.lock.hcl |
Provider選択を再現・reviewしたい | Git |
terraform.tfstate |
一貫した最新版を共有したい | Backend |
terraform.tfstate |
競合する書き込みを排他したい | Backend |
| Secret実値 | アクセスを制御したい | Secret管理基盤 |
StateについてHashiCorpも、
lockingやsecure access controlを持たないversion control systemへ保存しないよう勧めています。
State | Terraform
そして、冒頭で触れたSecretもGitにStateを置かない理由の一つです。
Stateにはpasswordやprivate keyなどのsensitive dataが保存される場合があります。
sensitive = true にして画面表示を隠しても、
通常はその値がStateから消えるわけではありません。
HashiCorpのStyle Guideでも、
Stateにはsecretなどのsensitive informationが含まれ得ることと、
VCSにはState lockingがないことの両方を理由に
terraform.tfstate をcommit対象から外しています。
Terraform Style Guide
つまり、
Secretが入る可能性があるからGitを避ける
も正しいです。
ただしそれだけでは、
「SecretがないStateならGitでよいのか？」
「複数人が同時にapplyしたら？」
という問題までは説明できません。
この記事でStateを運用DBとして捉えてきたのは、
機密性に加えて、最新版共有と排他制御まで同じモデルで説明するためです。
5-1. 「StateはこのS3に置く」という設定はGitでよい
たとえば次のようなBackend設定です。
terraform {
backend "s3" {
bucket = "my-tfstate-bucket"
key = "production/terraform.tfstate"
region = "ap-northeast-1"
}
}
これはState本体ではありません。
「Stateをどこへ保存するか」というconfigurationなので、
変更履歴を残したりreviewしたりする性質を持っています。
そのためGit管理と相性があります。
一方、S3に保存される実際の terraform.tfstate は、
Terraformがrunごとに読み書きする管理データです。
5-2. S3 Backendにしただけではlockingは有効にならない
ここは2026年時点で気をつけたいところでした。
S3 BackendはState lockingをサポートしていますが、
lockingはopt-inです。
現在の公式ドキュメントでは、
S3 lockfileを使う場合は use_lockfile = true を設定します。
terraform {
backend "s3" {
bucket = "my-tfstate-bucket"
key = "production/terraform.tfstate"
region = "ap-northeast-1"
use_lockfile = true
}
}
use_lockfile のdefaultは false です。
また、以前よく使われていたDynamoDB-based lockingはdeprecatedになっています。
S3 backend
S3 Backendを使う理由を、
S3に置けば自動でlockingされる
と覚えるのは少し危ないです。
「共有Stateを置ける」ことと、
「lockingを有効にして競合を制御する」ことは分けて考える必要があります。
Backend configurationにaccess keyやsecret keyをハードコードする話は別です。
HashiCorpはBackendのcredentialsなどのsensitive dataを環境変数などから渡すことを推奨しています。
おわりに
StateをGitに置かない理由を、
「Secretが入る可能性があるから」だけで覚えると、
SecretがなければGitでもよさそうに見えました。
自分が一番納得できたのは、
StateをTerraformのrunとrunをつなぐ運用DBとして見ることでした。
だからStateには、
Gitのbranch・diff・mergeより、
最新版の共有・locking・アクセス制御
の方が必要になります。
「TerraformコードはGit、StateはBackend」という分け方も、
設計図はreview・履歴管理、運用DBは最新版共有・locking
と役割から見ると、ファイル名の暗記ではなく理由から理解できるようになりました。