Terraform を 1 人で試しているうちは、作業フォルダにできる terraform.tfstate というファイルを気にしなくても困りません。
ところが、同じ構成をチームで触り始めると、このファイルをどこに置き、どう共有するかが急に問題になります。
「state を Git に入れてよいのか」「S3 に置くならロック用の DynamoDB テーブルも作るのか」は、Terraform を共有し始めた人が最初に迷いやすいところです。
state が何のためにあるのかが分かると、リモートに置く理由も、ロックが要る理由も、機密に気をつける理由も一続きで説明がつきます。
私も DevOps を学んでいる途中で、Terraform をチームで運用した経験はありません。
HashiCorp の公式ドキュメントと Terraform の CHANGELOG を読んで整理したノートです。
IaC そのものの考え方は、次の記事で整理しています。
state はコードと実物をつなぐ対応表
Terraform の state は、設定ファイルに書いたリソースと、クラウド上に実際にある物を結びつけておく記録です。
既定では作業ディレクトリの terraform.tfstate に保存され、1 つ前の内容は terraform.tfstate.backup に残ります。
公式ドキュメントは、state が要る理由を次の 3 つで説明しています。
| 役割 | state に入っているもの | 無いと困ること |
|---|---|---|
| 実物との対応 | aws_instance.foo が ID i-abcd1234 のインスタンスだという結びつき | どの設定がどの実物を指すのか分からない |
| メタデータ | リソース同士の依存関係など | 設定から消したリソースを、どの順番で削除するか決められない |
| 性能 | 全リソースの属性値のキャッシュ | 大きな構成で、API への問い合わせを省けない |
1 つ目の対応づけは、クラウドのタグで代わりにできそうに見えます。
公式の説明によると、初期の Terraform は state を持たずタグで対応づける試作をしていましたが、タグを付けられないリソースやタグの無いクラウドがあって行き詰まりました。
2 つ目の依存関係は、設定からリソースを消したときに効いてきます。
設定に無いものは設定から順番を読み取れないので、Terraform は state に残した直近の依存関係を見て、削除の順番を決めます。
3 つ目のキャッシュは、性能のための仕組みです。
大きな構成では -refresh=false で問い合わせを省き、キャッシュした値を正として扱う使い方が紹介されています。
state の中身は JSON ですが、公式ドキュメントはこのファイルを直接編集しないように求めていて、変更には terraform state 系のコマンドを使うよう案内しています。
3 つの理由は、公式ドキュメントの Purpose of Terraform State に詳しく書かれています。
ローカルの state をチームで回すと壊れる理由
state がローカルのファイルのままだと、チームの全員が「手元の state は最新か」と「いま誰も Terraform を実行していないか」を毎回確かめなければなりません。
公式ドキュメントがリモートの state を勧める理由として挙げているのも、この 2 つの確認の手間です。
1 つ目が崩れて古い state のまま作業すると、その state にはほかの人があとから作ったリソースの記録がありません。
記録の無いリソースは、Terraform から見ると管理していない物と同じです。
terraform state rm の説明でも、記録を消したリソースは次の plan で新しく作る対象になるとされています。
同じ名前の物がすでにあると、その作成は失敗することがあるとも書かれています。
2 つ目が崩れて 2 人が同時に state を書き込むと、state そのものが壊れるおそれがあり、これを防ぐのが次の節のロックです。
state を Git に入れて共有する方法も思いつきますが、公式ドキュメントはロックと安全なアクセス制御を持たない置き場所を避けるように書いています。
理由として挙げられているのは、データの消失と、state に含まれる機密の露出です。
リモートバックエンドとロックで同時実行を防ぐ
チームで state を共有する仕組みが、リモートバックエンドです。
terraform ブロックの中に backend ブロックを書くと、Terraform は state をローカルではなく指定した保存先に読み書きします。
保存先の候補は Amazon S3、Azure Blob Storage、Google Cloud Storage、HashiCorp Consul などで、HashiCorp のサービスである HCP Terraform も選択肢の 1 つです。
ロックに対応したバックエンドでは、state を書き換える可能性のある操作のたびに、Terraform が自動でロックを取ります。
ロックが取れなければ Terraform は先へ進まないので、後から実行した側はそこで止まります。
-lock-timeout を付けると、指定した時間だけロックの取得をやり直してから失敗するようになります。
-lock=false でロックを外すこともできますが、公式ドキュメントは勧めていません。
ロックが外れずに残ったときは、terraform force-unlock で外せます。
ただし、ほかの人が持っているロックを外すと書き込みが重なるので、自分のロックが自動で外れなかったときだけに使うよう公式ドキュメントは注意しています。
S3 のロックは use_lockfile が現行
S3 バックエンドのロックは、2024 年の終わりから仕組みが変わりました。
以前の Terraform は DynamoDB でしかロックできず、ロック用のテーブルを用意して dynamodb_table で指定する必要がありました。
| 版 | 変わったこと |
|---|---|
| 1.10.0(2024 年 11 月 27 日) | S3 そのものでロックする仕組みが入り、DynamoDB と併用すると両方からロックを取るようになった |
| 1.11.0(2025 年 2 月 27 日) | S3 のロックが一般提供になり、DynamoDB 関連の引数が非推奨になった |
| 現在の公式ドキュメント | DynamoDB のロックは非推奨で、将来のマイナー版で削除予定と明記されている |
2026 年 11 月 3 日時点の最新の安定版は 1.17.1 です。
1.12 から 1.17 までの CHANGELOG に、DynamoDB のロックを削除したという記載はありません。
それでも公式ドキュメントがDynamoDB のロックを将来のマイナー版で削除すると書いている以上、新しく組むなら S3 のロックを選ぶことになります。
use_lockfile = true にすると、Terraform は state と同じ場所に <key>.tflock というロックファイルを置いて排他をとります。
そのため IAM の権限には、state 本体の読み書きに加えて、ロックファイルへの s3:GetObject・s3:PutObject・s3:DeleteObject が必要です。
公式ドキュメントは、誤って消したときに戻せるよう、バケットのバージョニングを有効にすることも強く勧めています。
次の例は書式を示すためのもので、Docker の hashicorp/terraform イメージ(Terraform v1.16.6)で terraform fmt と terraform validate だけを通しています。
バックエンドには接続せず(terraform init -backend=false)、S3 側で設定が通るかまでは確かめていません。
# backend.tf(書式の例)
terraform {
backend "s3" {
bucket = "example-tfstate-bucket"
key = "network/terraform.tfstate"
region = "ap-northeast-1"
use_lockfile = true # S3 のロックファイルで排他をとる
encrypt = true # state とロックファイルをサーバー側で暗号化する
}
}
DynamoDB から移る間は、use_lockfile と dynamodb_table を同時に設定できます。
新しい版は両方からロックを取るので、DynamoDB しか見ない古い版の Terraform とも DynamoDB の側でぶつかり、同時には走れません。
引数の一覧と必要な権限は、Backend Type: s3 にまとまっています。
非推奨になったときの記載は、Terraform v1.11.0 のリリースノートにあります。
backend ブロックには変数を書けない
backend ブロックには、入力変数やローカル値を書けないという制約があります。
環境ごとにバケットやキーを変えたいときは、backend ブロックを空けておき、terraform init の -backend-config で残りを渡す「部分設定」を使います。
# backend.tf(書式の例)
terraform {
backend "s3" {}
}
# prod.s3.tfbackend(init のときに渡す残りの設定)
bucket = "example-tfstate-bucket"
key = "prod/terraform.tfstate"
region = "ap-northeast-1"
use_lockfile = true
terraform init -backend-config=prod.s3.tfbackend
ただし、認証情報はこの設定に書かず、環境変数などで渡すように勧められています。
-backend-config や設定ファイルに直接書いた値は、.terraform ディレクトリと plan ファイルの両方に平文で残るからです。
同じ理由で、.terraform ディレクトリは Git に入れないよう書かれています。
HCP Terraform に任せる選択肢
自前でバケットを用意しない方法として、HashiCorp の HCP Terraform があります。
2024 年 4 月 22 日に Terraform Cloud から名前が変わったサービスで、機能はそのまま引き継がれました。
HCP Terraform ではワークスペースごとに state が保存され、過去の state のバージョンも残るので、変更の履歴をさかのぼれます。
公式ドキュメントによると、実行を中央で順番待ちにするので、承認待ちの plan があるときに別の plan を作ろうとする動きまで検知できます。
使うときは backend ブロックの代わりに cloud ブロックを書き、両方を同じ構成に書くことはできません。
機密・分割・付け替えで気をつけること
リモートに置いてロックを付けたあとも、state の扱いで気をつけたい点は、機密・分割・付け替えの 3 つです。
state には機密が平文で入る
state には、データベースの初期パスワードや API トークンのような機密の値が入ることがあります。
変数や出力に sensitive = true を付けても、隠れるのは CLI と HCP Terraform の画面の表示だけで、値そのものは state と plan ファイルに保存されたままです。
ローカルの state は平文のファイルなので、公式ドキュメントは state を機密データとして扱い、Git の外に置くよう求めています。
リモートでの保存時の暗号化はバックエンドによって方法が違い、S3 では encrypt や kms_key_id で指定します。
HCP Terraform では、保存時の暗号化と通信の TLS が自動でかかります。
Terraform 1.10 以降の ephemeral な値と、1.11 以降の write-only の引数は、値を state と plan に残さないための仕組みです。
ただし、write-only の引数が使えるかどうかは、プロバイダーがその引数を用意しているかで決まります。
読める人を絞ることも同じくらい大切で、S3 ではオブジェクトのパスごとに IAM ポリシーで権限を分けられ、ロックファイルもその対象に含める必要があります。
Terraform からの移行手順を公式に案内している OpenTofu には、1.7 で state と plan を保存時に暗号化する機能が入りました。
設定の方法は、OpenTofu の State and Plan Encryption にまとまっています。
機密の値の扱い方をまとめた Terraform の公式ページが、Manage sensitive data in your configuration です。
認証情報をコードに書かない工夫そのものは、次の記事で扱っています。
state を分ける単位を決める
ロックは state ごとにかかるので、1 つの state に全部を入れると、関係の薄い変更どうしでもロックがぶつかります。
同じ設定のまま state だけを切り替える仕組みが、Terraform のワークスペースです。
S3 バックエンドでは、default 以外のワークスペースの state は env:/<ワークスペース名>/<key> のパスに保存されます。
ただし公式ドキュメントは、ワークスペースは同じバックエンドを使うため、認証情報やアクセス制御を分けたい環境の分離には向かないと明記しています。
代わりに勧められているのは、共通部分をモジュールにまとめ、環境ごとに別の設定とバックエンドを持たせる形です。
ワークスペースの使いどころとして挙げられているのは、本番を変える前に、同じ構成の一時的なコピーを作って試すような場面です。
使い分けの説明は、Manage workspaces の「When Not to Use Multiple Workspaces」にあります。
付け替えは moved・import・removed ブロックで
リソースの名前を変えたりモジュールへ移したりすると、Terraform は既定で「古い物を消して新しい物を作る」と解釈します。
これを避ける昔からの方法が terraform state mv で、記録だけを新しいアドレスへ付け替えるコマンドです。
公式ドキュメントは、チームで state mv を使うときは、設定の変更からコマンドの実行までの間にほかの人が変更を入れないよう、よく連絡を取るように注意しています。
その間に別の人が plan を作ると、古い物を消して新しい物を作る plan になりかねないからです。
今は、同じことを設定ファイルに書いて済ませるブロックがそろっています。
| ブロック | 使える版 | 用途 | 対応するコマンド |
|---|---|---|---|
moved | 1.1 以降 | リソースやモジュールのアドレスを変える | terraform state mv |
import | 1.5 以降 | 既存のリソースを state に取り込む | terraform import |
removed | 1.7 以降 | destroy = false なら実物を残して state から外す | terraform state rm |
ブロックで書くと、変更がいつもの plan に出てくるので、レビューを通してから反映できます。
# リソース名を a から b に変える(書式の例)
moved {
from = aws_instance.a
to = aws_instance.b
}
それでも state をコマンドで直接いじるなら、公式ドキュメントが求めているとおり、事前にバックアップを取っておいてください。
moved ブロックの使い方は、Refactor modules に例つきで載っています。
最後に
state は、Terraform が「設定のどのリソースが、クラウドのどの物か」を覚えておくための対応表です。
チームで使うなら、ロックできるリモートバックエンドに置き、S3 なら use_lockfile = true で組むのが今の公式ドキュメントの書き方になります。
IaC の全体像は冒頭の記事、認証情報の置き場所はシークレット管理の記事とあわせて読むと、state の扱いがどこにつながるのかが見えてきます。
そのうえで、state には機密が入るものとして読める人を絞り、環境ごとに設定とバックエンドを分けておくと、1 つのミスが全体に広がりにくくなります。
以上です。











コメントを残す