その不満は正当だ。Terraform 1.11.0でS3ネイティブロック(use_lockfile)が正式サポートとなり、DynamoDB依存なしにstateロックが実現できるようになった。同時にDynamoDBロック引数は非推奨(deprecated)となり、将来バージョンでの削除が予定されている。
この記事では、DynamoDBロックからS3ネイティブロックへの移行手順、安全な併用期間の設け方、そして移行後に発生しやすいロック競合の解消方法を実践的に解説する。
動作確認環境:Terraform 1.11.x / AWS provider 5.x / Ubuntu 24.04 LTS
この記事のポイント
・use_lockfileはTerraform v1.11でGA。.tflockファイルをS3条件付き書き込みで管理する
・dynamodb_table引数はdeprecated。移行期間中は両設定の同時有効化が可能
・移行はIAM権限追加→use_lockfile追加→動作確認→dynamodb_table削除の4段階で進める
・ロック競合はterraform force-unlockで解除できる。実行前にWho/Created/CI状態を必ず確認
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
なぜDynamoDB stateロックがS3ネイティブロックに置き換わるのか
Terraform S3バックエンドでDynamoDBを使ったstateロックは、2017年以降しばらくの間ベストプラクティスとされてきた。しかし実運用では常に2つの問題を抱えていた。1つ目は「S3とDynamoDBという異なるAWSサービスをセットで管理しなければならない」という複雑さだ。tfstateそのものはS3に置くのに、ロックのためだけにDynamoDBのプロビジョニング・IAM権限管理・コスト負担が発生する。
2つ目は「S3単体でロック相当の排他制御が技術的に実現できるはず」という長年の課題感だ。S3は2024年にConditional Writes(条件付き書き込み)機能をGAとしてリリースし、この課題解決の技術的基盤が整った。
Terraform 1.10でS3ネイティブロックが実験的に導入され、1.11.0(2025年2月リリース)でGA(一般提供)となった。これに伴い、S3バックエンドのDynamoDB関連引数(dynamodb_table・dynamodb_endpoint)は非推奨扱いとなっている。
DynamoDBロックとS3ネイティブロックの仕組みの違い
2つの方式はロック情報の格納先と競合検出の仕組みが根本的に異なる。DynamoDB方式
terraform applyが実行されると、指定したDynamoDBテーブルにロックアイテム(LockID = {バケット名}/{キー})をPutItemで書き込む。テーブルにすでにそのLockIDが存在する場合は、条件付き書き込みが失敗してロック競合エラーになる仕組みだ。
S3ネイティブ方式(use_lockfile = true)
terraform applyが実行されると、stateファイルのパスに.tflockを付加したファイル(例:path/to/terraform.tfstate.tflock)をS3に書き込む。このとき、HTTPリクエストヘッダーに
If-None-Match: * を付加することで「ファイルが存在しない場合のみ書き込む」という条件付き書き込みを実現している。すでに.tflockファイルが存在すると、S3から412 Precondition Failedが返り、ロック競合エラーになる。| 観点 | DynamoDB方式(旧) | S3ネイティブ(use_lockfile) |
|---|---|---|
| ロック格納場所 | DynamoDBテーブル | S3の.tflockファイル |
| 追加サービス | DynamoDB(別途必要) | 不要(S3のみ) |
| IAM権限(追加分) | dynamodb:GetItem/PutItem/DeleteItem | s3:GetObject/PutObject/DeleteObject(.tflock) |
| 競合検出方式 | DynamoDB条件付き書き込み | S3 If-None-Match ヘッダー |
| ステータス | 非推奨(deprecated) | GA(v1.11.0~) |
use_lockfileへの移行手順
移行は「IAM権限の追加」「use_lockfileの追加(dynamodb_tableとの併用)」「動作確認」「dynamodb_tableの削除」の4段階で進める。いきなりDynamoDB設定を削除するのではなく、併用期間を設けて安全に移行するのが重要だ。1. Terraformバージョンの確認とIAM権限の追加
まずTerraformが1.11以降であることを確認する。terraform version
Terraform v1.11.4 on linux_amd64
tfenv install 1.11.4 && tfenv use 1.11.4 で切り替えられる。次にIAMポリシーへ.tflockファイル操作の権限を追加する。use_lockfileを有効にすると、Terraformは.tflockファイルに対してGetObject・PutObject・DeleteObjectを実行する。既存のIAMポリシーに以下のStatementを追加する。
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::your-tfstate-bucket/path/to/terraform.tfstate.tflock" } ] }
arn:aws:s3:::your-tfstate-bucket/* のままでも動作するが、最小権限の原則から.tflockサフィックスまで絞ることを推奨する。2. use_lockfile追加とdynamodb_tableとの併用設定
既存のbackend "s3"ブロックにuse_lockfile = true を追加する。この段階ではまだdynamodb_tableを残したままにする。両設定は同時に有効化できるため、移行期間中の二重ロックが可能だ。terraform { backend "s3" { bucket = "your-tfstate-bucket" key = "path/to/terraform.tfstate" region = "ap-northeast-1" encrypt = true # S3ネイティブロックを有効化(v1.11.0以降) use_lockfile = true # 移行期間中は残す(deprecated警告が出るが動作する) dynamodb_table = "your-lock-table" } }
terraform init -reconfigure
path/to/terraform.tfstate.tflock ファイルが作成されることをAWSコンソールまたはCLIで確認する。# plan実行中に別ターミナルで.tflockファイルの存在を確認 aws s3 ls s3://your-tfstate-bucket/path/to/terraform.tfstate.tflock
3. DynamoDB依存の完全削除
動作確認が完了したら、dynamodb_table行を削除してDynamoDB依存をゼロにする。terraform { backend "s3" { bucket = "your-tfstate-bucket" key = "path/to/terraform.tfstate" region = "ap-northeast-1" encrypt = true use_lockfile = true } }
DynamoDBテーブル自体はしばらくの間残しておき、問題がなければ削除する。テーブルの中身(LockIDアイテム)が空であることをAWSコンソールで確認してから削除するのが安全だ。
>> Terraform実践セミナーの詳細はこちら
ロック競合が発生したときの解消手順
S3ネイティブロックへの移行後、apply中にプロセスがkillされたり、ネットワーク断が発生したりすると.tflockファイルが残留してロック競合エラーになることがある。ロックが残り続ける主な原因は次のとおりだ。・CI/CDパイプラインのタイムアウト:GitHub ActionsやGitLab CIのジョブが制限時間切れで強制終了し、クリーンアップが走らなかった
・ターミナルの強制終了:ローカルでapplyを実行中にCtrl+Cを押したか、SSH接続が切れた
・ネットワーク切断:Stateを書き込んでいる途中でインターネット接続が途絶えた
・OOM Kill:terraformプロセスがメモリ不足でOSにKillされた
これらの場合、Stateの内容は変わっていないのにロックだけが残る。次のterraform操作でロック競合エラーになる。
1. ロック競合エラーの確認
ロック競合時は以下のようなエラーが表示される。Error: Error acquiring the state lock Error message: ConditionalCheckFailedException: The conditional request failed Lock Info: ID: abc12345-6789-def0-1234-56789abcdef0 Path: path/to/terraform.tfstate Operation: OperationTypeApply Who: user@hostname Version: 1.11.4 Created: 2026-09-10 09:15:23.123456789 +0000 UTC
ID: 行の値がforce-unlockコマンドに必要なLOCK_IDだ。エラー出力をコピーしてIDを確保しておこう。Who: と Created: もあわせて控えておく。ロックを取得したユーザー・マシン名と取得時刻を把握しておくことが、後述の安全判断で役に立つ。2. ロックIDをDynamoDB・S3ネイティブロックから直接確認する方法
エラーメッセージを見失った場合や、バックエンドのロック状態を直接確認したい場合は、AWSコマンドで調べられる。DynamoDBバックエンドの場合
# DynamoDBのロックテーブルをスキャンしてロック情報を取得 # (テーブル名はbackend設定のdynamodb_tableに合わせる) aws dynamodb scan \ --table-name terraform-state-locks \ --query "Items[*].{LockID:LockID.S,Info:Info.S}" \ --output table # 出力例(環境により異なります) # ----------------------------------------------------------------- # | Scan | # +------------------------------------------+------------------+ # | Info | LockID | # +------------------------------------------+------------------+ # | {"ID":"abc12345-...","Operation":"Apply"}| s3://bucket/... | # +------------------------------------------+------------------+
Info フィールドのJSONの中にある "ID":"..." の値がforce-unlockに渡すロックIDだ。LockID フィールドはStateのパスを示しており、ロックIDとは別物なので混同しないこと。S3ネイティブロック(use_lockfile)の場合
# S3バケット上のロックファイルを一覧表示 aws s3 ls s3://your-tfstate-bucket/path/to/ | grep '.tflock' # ロックファイルの中身を標準出力に表示してIDを確認 aws s3 cp s3://your-tfstate-bucket/path/to/terraform.tfstate.tflock - # 出力例(環境により異なります) # {"ID":"abc12345-6789-def0-1234-56789abcdef0","Operation":"OperationTypeApply", # "Who":"ci-runner@github-actions","Version":"1.11.4", # "Created":"2026-09-10T09:15:23Z"}
"ID" の値をforce-unlockに渡す。3. force-unlockを実行する前の安全チェック
force-unlockは強力な操作だ。別の操作が本当に進行中でないとわかってから実行すること。実行中のapplyが別プロセスで走っている状態でforce-unlockするとstateが破損するリスクがある。次のチェックリストを順番に確認してから実行する。
・ロックの作成時刻(Created)を確認する:直近5分以内なら操作が続いている可能性がある。10分以上前なら異常終了の可能性が高い
・Who フィールドを確認する:エラーメッセージの
Who: 行にロックを取ったユーザーとホスト名が表示される。誰が実行したかを特定してから解除の判断をする・CI/CDのジョブ一覧を確認する:GitHub Actionsなら「Actions」タブ、GitLab CIなら「CI/CD → Pipelines」で実行中のジョブがないか確認する
・チームメンバーに確認する:Who フィールドのユーザーが特定できたら、そのメンバーにローカルからのapplyが継続中でないか確認する
次のケースではforce-unlockしてはいけない。
・CI/CDのジョブがまだ「running」または「pending」のまま残っている
・ターミナルのapplyが応答しないだけで、バックグラウンドでAPIコールが継続している可能性がある
・ロックの時刻が3~5分以内で、何かが動いている可能性が否定できない
4. terraform force-unlockコマンドによる解除
ロック競合を解除するにはterraform force-unlockコマンドを使う。terraform force-unlock abc12345-6789-def0-1234-56789abcdef0
yes を入力する。Do you really want to force-unlock? Terraform will remove the lock on the remote state. This will allow local Terraform commands to modify this state, even though it may be still be in use. Only 'yes' will be accepted to confirm. Enter a value: yes Terraform state has been successfully unlocked! The state has been unlocked, and Terraform commands should now be able to run successfully.
-force フラグを付けることで確認プロンプトをスキップできる。# 確認プロンプトをスキップして強制解除 terraform force-unlock -force abc12345-6789-def0-1234-56789abcdef0
5. .tflockファイルが残留した場合の手動削除
force-unlockが効かない場合や、何らかの理由で.tflockファイルが手動削除しか手段がない場合は、AWS CLIで直接削除できる。# .tflockファイルが存在するか確認 aws s3 ls s3://your-tfstate-bucket/path/to/terraform.tfstate.tflock # ファイルを削除 aws s3 rm s3://your-tfstate-bucket/path/to/terraform.tfstate.tflock
terraform plan でstateの整合性を確認するのが望ましい。force-unlockが解決しないときのトラブルシュート
force-unlockを実行しても次のapplyがロックエラーになる場合は、別の問題が潜んでいる。DynamoDBのアイテムが消えていないケース
DynamoDBのプロビジョニングスループットが不足していて、DeleteItemが失敗するケースがある。force-unlock後にDynamoDBを直接確認する。# force-unlock後にDynamoDBアイテムを直接確認 aws dynamodb get-item \ --table-name terraform-state-locks \ --key '{"LockID": {"S": "s3://your-tfstate-bucket/path/to/terraform.tfstate"}}' # 出力例(環境により異なります) # アイテムが返ってこなければ解除済み # アイテムが残っていれば以下の手動削除コマンドを実行する
aws dynamodb delete-item \ --table-name terraform-state-locks \ --key '{"LockID": {"S": "s3://your-tfstate-bucket/path/to/terraform.tfstate"}}'
S3ネイティブロックで.tflockオブジェクトが残るケース
S3ネイティブロックはバケットのバージョニングが有効であることを前提にしている。バージョニングが無効な場合、.tflockオブジェクトの削除が期待どおりに動かないことがある。# バケットのバージョニング状態を確認 aws s3api get-bucket-versioning --bucket your-tfstate-bucket # 出力例(環境により異なります) # {"Status": "Enabled"} → 有効(use_lockfileの前提を満たしている) # {} → 無効(use_lockfileの前提を満たしていない)
ワークスペース・パスが複数あり混在しているケース
複数のterraform workspaceや複数のディレクトリが同じバックエンドを使っている構成では、ロックのPath: フィールドを確認して、どのStateのロックなのかを特定する。force-unlockは必ず対象のStateが存在するディレクトリで実行すること。# ロックエラーのPath フィールドを確認して対象ディレクトリを特定する # Path: s3://example-bucket/env:/prod/terraform.tfstate ← workspaceのパス形式 # Path: s3://example-bucket/prod/vpc/terraform.tfstate ← ディレクトリ構成のパス形式 # 対象ディレクトリで実行する cd /path/to/terraform/prod/vpc terraform force-unlock abc12345-6789-def0-1234-56789abcdef0
バージョニング有効バケットでの.tflockファイル管理
tfstateバケットにS3バージョニングを有効にしている場合(推奨設定)、.tflockファイルが作成・削除されるたびに旧バージョンがS3上に蓄積する。apply頻度が高い環境では数百件のバージョンが溜まり、ストレージコストの増加と誤認識の原因になる。S3ライフサイクルポリシーで.tflockの旧バージョンを自動削除する設定をTerraformで管理する例を示す。
resource "aws_s3_bucket_lifecycle_configuration" "tfstate" { bucket = aws_s3_bucket.tfstate.id rule { id = "delete-old-lockfile-versions" status = "Enabled" filter { prefix = "" } noncurrent_version_expiration { noncurrent_days = 7 newer_noncurrent_versions = 5 } } }
noncurrent_days = 7 は7日経過した旧バージョンを削除する設定、newer_noncurrent_versions = 5 は常に最新5バージョンを保持する設定だ。stateファイル本体の旧バージョンも同じルールで削除されるため、バケット全体での設計が必要になる。.tflockファイルのみを対象にするには filter { prefix = ".tflock" } と書くこともできるが、S3のキー末尾一致ではなく前方一致のため、通常のtfstateキー構成では機能しない点に注意が必要だ。実用上はバケット全体にライフサイクルを設定しつつ、stateファイル本体の保持日数を長く設定する分離ルールで管理するのが現実的だ。本記事のまとめ
| やりたいこと | コマンド・設定 |
|---|---|
| S3ネイティブロックを有効化 | backend "s3" { use_lockfile = true } |
| Terraformバージョンを確認 | terraform version |
| バックエンド設定を再初期化 | terraform init -reconfigure |
| .tflockファイルの存在を確認 | aws s3 ls s3://bucket/path/to/key.tfstate.tflock |
| DynamoDBのロックIDを確認 | aws dynamodb scan --table-name <テーブル名> |
| S3ネイティブロックのIDを確認 | aws s3 cp s3://<bucket>/<path>.tflock - |
| ロック競合を解除(確認あり) | terraform force-unlock <LOCK_ID> |
| ロック競合を解除(確認なし) | terraform force-unlock -force <LOCK_ID> |
| .tflockファイルを手動削除 | aws s3 rm s3://bucket/path/to/key.tfstate.tflock |
| DynamoDBのロックアイテムを手動削除 | aws dynamodb delete-item --table-name <テーブル名> --key ... |
ロック競合が発生したときは、まずロックの
Who: と Created: を確認してCI/CDジョブの状態と照合し、本当に誰も操作していないことを確かめてからforce-unlockを実行するのが鉄則だ。stateロックの設計思想や、複数チームでtfstateを共有する際の設計については、Terraform実践セミナーでさらに詳しく解説している。
>> Terraform実践セミナーの詳細はこちら
3,100名以上が実践した「型」を無料で公開中
プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。
姓・名・メールの3つだけ/30秒/解除は3秒 / 詳細はこちら
- 次のページへ:Route 53のサブドメインをTerraformで別ゾーンに切り出す設計|NSレコード委任と環境ごとの権限分離
- 前のページへ:TerraformでVPCエンドポイントを一括定義する方法|インターフェース型のサブネット配置とプライベートDNS有効化の実装
- この記事の属するカテゴリ:Terraformへ戻る

無料メルマガで学習を続ける
Linuxの実践スキルをメールで毎週お届け。
登録は30秒、解除もいつでも可。
登録無料・いつでも解除できます