terraform

Terraform／OpenTofu の運用

このスキルは、Terraform と OpenTofu のインフラストラクチャを安全に実行、調査、修復するために使用します。モジュールグラフの把握、ステートバックエンドとロックの確認、適用前のプランのレビュー、ドリフトの検出と修正、リモートステートの操作、バージョンアップグレードとリファクタリングの計画、根拠に基づく障害の診断を行います。これは、名前付きツール 1 つ（Terraform と、その互換性のあるフォークである OpenTofu は同じエージェントワークフローとトリガーを共有します）を対象とするツールスキルです。設計上の判断と IaC の方法論については、platform-engineering とその references/infrastructure-as-code.md を参照してください。このスキルが担当するのは実行です。

運用上の取り決め

1. 思い込みを避け、まず調査します。 何かを実行する前に、モジュール構成、プロバイダー要件、バックエンドブロック、ワークスペース、terraform.lock.hcl、CI の実行方法を確認します。設定ファイルからステートを推測してはいけません。何が存在するかを示す情報源はステートファイルです。
2. 先にプランを作成し、レビュー後に適用します。 すべての変更操作は、確認可能なプラン（または tfops のドライラン）と明示的な確認を経て実行します。未レビューの変更を含む状態で apply を実行してはいけません。
3. ステートをロックし、操作範囲を限定します。 ステートを変更する前に、バックエンドがロックに対応していることと、オペレーターがロックを保持していることを確認します。ステートの直接操作（state mv、state rm、state push）は、バックアップを取ったうえでレビューし、範囲を限定して実施します。
4. 境界で検証します。 apply の成功だけでは、処理が成功した証拠にはなりません。リソースが満たすはずだった外部境界（DNS、ロードバランサー、API レスポンス）を検証し、次のプランでドリフトを確認します。
5. 証拠の出力範囲を限定します。 生のステートファイル、バックエンドの認証情報、プロバイダーのシークレットをチャットに出力してはいけません。tfops 自体は出力を秘匿化しませんが、すべての出力を要約に限定してください。

tfops スクリプト

scripts/tfops は、terraform／tofu CLI をエージェント向けにラップしたものです。--help、doctor、--state による直接分析は terraform バイナリがなくても実行できるため、エージェントはどこからでもステートファイルのインベントリを作成できます。

scripts/tfops doctor --json                 # binary, config, backend, state availability
scripts/tfops state --state state.json --json   # inspect a local state file directly
scripts/tfops plan --state state.json --json    # state-level plan summary (no binary needed)
scripts/tfops plan --json                   # full plan via terraform plan -json
scripts/tfops apply --dry-run --json        # preview only, never mutates
scripts/tfops plan --save-plan reviewed.tfplan --json
# Review reviewed.tfplan, then apply that same file
scripts/tfops apply --yes --plan reviewed.tfplan --json
scripts/tfops apply --yes --plan reviewed.tfplan --force --json  # bypass findings only after review
scripts/tfops import aws_instance.web i-0abc --dry-run

変更操作のゲート：apply と import は、--yes が指定されていない場合、実行を拒否します（終了コード 2）。また apply には、tfops plan --save-plan FILE を通じて作成されたプランが必要です。このコマンドはプロバイダーの更新を明示的に有効にし、SHA-256 のサイドカーファイルを書き込みます。tfops はサイドカーファイルを検証し、レビュー済みプランを非公開の一時スナップショットにコピーしたうえで、そのスナップショットに対して terraform show -json を実行し、フォーマットと成功の証拠を確認し、存在する場合は事前のステートを検証します。また、デフォルトでは tainted リソースと検出されたドリフトをブロックし、同じスナップショットを適用します。サポートされているプラン JSON 形式では、変更が空の場合にその変更情報が省略されることがあります。errored は false でなければならず、エンジンが applyable／complete を報告する場合は、それらが true でなければなりません。--force が回避できるのは、有効なプランの証拠から検出された問題だけです。証拠の欠落や無効、サイドカーファイルの不在、ハッシュの不一致、またはラッパーで明示的に更新を有効にせず作成されたプランは回避できません。サイドカーファイルは、誤操作による取り違えを防ぐためのローカルな来歴情報であり、暗号署名ではありません。--dry-run は変更せずにプレビューします。--state の要約は稼働中のドリフトの証拠ではなく、適用時のガード条件を満たせません。TERRAFORM 環境変数でバイナリの選択を上書きできます（それ以外の場合は terraform、次に tofu の順に自動検出します）。終了コード：0 は正常、1 は分析／実行時エラー、2 はゲートによる拒否、127 はバイナリが見つからない場合、124 はタイムアウトです。

運用ループ

1. インベントリ作成：モジュールツリー、プロバイダー要件、バックエンド設定、ワークスペース、ロックファイル、ステートの serial／lineage を確認します。
2. 分析：terraform validate、tfops plan --json（またはバックエンドに接続できない場合はステートファイルの要約）を実行します。
3. レビュー：プランを大量のテキストではなく、リソースの差分として読みます。作成／更新／破棄の件数を数え、置換（破棄してから作成）を確認し、機密性の高い変更を抜き取り確認します。
4. 適用：対象範囲を限定し、確認を行い、バックエンドロックを保持した状態で適用します。その後、境界を検証します。
5. ドリフト確認：変更後および定期的にプランを再作成し、本来存在しないはずの差分を調査します。

モジュール構成

• 構成要素ごとにモジュールを分けます。入力（変数）、出力、単一の責務を持つリソースをまとめます。ルートモジュールからモジュールを呼び出し、ルートは薄く保ちます。
• プロバイダー（required_providers）とモジュールのバージョンを固定し、terraform.lock.hcl をコミットします。
• 繰り返しにはコード生成ではなく for_each／count を使用します。設定の注入には templatefile を使い、プロビジョナーは最後の手段として扱います。
• 構成の規約とコンポジションパターンについては、references/01-modules-and-structure.md を参照してください。

状態バックエンドとロック

• バックエンドが状態の保存とロックを管理します。デフォルトの local バックエンドは状態をディスクに保存します。リモートバックエンド（S3+DynamoDB、GCS、Azure Storage、Terraform Cloud/OpenTofu Cloud、Consul）は状態をディスク外に保管し、共同作業を可能にします。
• ロックは同時書き込みを防ぎます。適用や状態の直接操作の際は、必ずロックが保持されていることを確認してください。古いロックが残ると操作がブロックされます（force-unlock は、ほかに実行中の操作がないことを確認してから使用してください）。
• 状態にはシークレットが含まれます。バックエンドの保存データを暗号化し、読み取りアクセスを制限し、機密値には sensitive = true を設定します。
• バックエンドの選択、移行（terraform init -migrate-state／-reconfigure）、ロックのトラブルシューティングについては、references/02-state-and-backends.md を参照してください。

plan／apply ワークフロー

• plan は設定、状態、プロバイダーデータを読み取り、差分を提示します。apply はその差分を実現します。plan の出力は、apply が実行する内容を定めた契約として扱います。
• 削除と置き換えは最もリスクの高い変更として確認します。再作成が危険な場合は、prevent_destroy と create_before_destroy のライフサイクルルールを使用します。
• -target は緊急時にのみ使用し、常用しないでください。-auto-approve はレビュー済みの CI/CD ゲート内でのみ使用します。
• ワークフロー全体、JSON 形式の plan 出力（-json）、レビュー用チェックリストについては、references/03-plan-apply-workflow.md を参照してください。

ドリフト検出

• ドリフトとは、宣言された設定と実際のインフラストラクチャとの差です。差分のない plan はドリフトを調べる手段です。定期的に plan を実行し、予期しない差分はインシデントとして扱います。
• 意図されたドリフト（範囲外での手動変更、外部からの変更）と、意図しないドリフト（設定と状態の不整合、プロバイダーのバグ）を区別します。
• 修正には plan とレビュー済みの apply による調整を行うか、リソースが一度も管理されていなかった場合は import を使用します。安易に削除して再作成することは避けてください。
• tfops はレビュー済みの保存済み plan を調べ、汚染されたリソースとプロバイダーが検出したドリフトを確認します。検出事項がある場合、意図的に --force を指定しない限り処理を拒否し、その plan をそのまま適用します。状態を直接分析すれば汚染を検出できますが、実際のドリフトを確認することはできません。手法と実施頻度については、references/04-drift-detection.md を参照してください。

リモート状態

• リモートバックエンドを使うと、状態を共有でき、永続化し、ロック可能になります。ローカル状態は実験用に限って使用します。
• 別のスタックの出力を利用するには、data "terraform_remote_state" を使用します。ワークスペースまたは環境を指定して参照し、出力を手作業でコピーしないでください。
• 状態ファイルは納品物ではありません。リモート状態を保護し（暗号化、ACL、監査）、復旧できるようにします（バージョン管理、バックアップ、復元訓練）。実践方法については、references/05-remote-state-and-collaboration.md を参照してください。

アップグレードとリファクタリングの流れ

• アップグレード：対象となるバージョン範囲のアップグレードガイドを読み、terraform validate／tofu validate で検証し、plan を実行します。まず本番以外の環境で適用し、プロバイダーのバージョンやアドレスを変更する場合は terraform state replace-provider／state mv を使用します。
• リファクタリング：moved ブロックを使ってリソースの名前変更や再構成を行います（plan に安全で、状態の直接操作は不要です）。moved が適さない場合は、レビュー済みの state mv を使用します。再作成を強制するために状態を削除してはいけません。
• バージョンとサポートに関する所見、および手順については、references/06-upgrades-and-refactors.md を参照してください。

診断

証拠の順序に沿って診断します：バイナリ／バージョン → 設定の検証 → バックエンドとロックの状態 → 状態のシリアル番号／リネージ → プランの差分 → 適用エラー → 境界チェック。

• ロックエラー：force-unlock を実行する前に、ロック保持者を特定します（バックエンド固有の方法を使用）。
• 状態のシリアル番号／リネージの不一致：古い状態または別の状態です。バックアップを取り、対象範囲を確認した場合に限り、state pull／state push を使用してください。
• tfops doctor は最初の層の証拠を収集します。障害パターンとその調査方法は references/07-diagnostics.md に記載されています。

リファレンスの参照先

参照する場面	リファレンス
モジュールの設計、構成、または構造上の規約	references/01-modules-and-structure.md
バックエンドの選択、移行、またはロックの問題	references/02-state-and-backends.md
変更の計画、適用、またはレビュー	references/03-plan-apply-workflow.md
設定と実際の環境との予期しない差異	references/04-drift-detection.md
共有状態または複数スタック間の状態	references/05-remote-state-and-collaboration.md
バージョンの更新、プロバイダーの移行、またはモジュールのリファクタリング	references/06-upgrades-and-refactors.md
apply、ロック、または状態のエラー	references/07-diagnostics.md
ソース、バージョンに関する情報、および更新手順	references/00-source-index.md

含まれる成果物

• scripts/tfops：エージェント優先のラッパー（状態分析、plan/apply、ゲート付き変更、JSON 出力）。
• tests/test_tfops.py + tests/fixtures/fixture-state.json：バンドルされた状態フィクスチャーを使った決定論的なテスト。
• references/：上記の運用トピックを扱う、日付とソースの索引が付いた8つのリファレンス。

検証の境界

主張	最低限必要な証拠
設定が有効である	terraform validate（または tofu validate）の終了コードが0
状態を読み取れる	tfops state --state FILE --json が状態を解析し、インベントリーを作成する
プランが安全である	create/update/destroy/replace の件数を含むプラン差分をレビューし、tainted リソースを未確認のまま適用していない
apply が成功した	apply の終了コードが0 かつ、リソースが提供する外部境界が正しく応答する
ドリフトがない	apply 直後と定められた頻度で再プランを行い、差分がない

厳守すべき境界

• 状態ファイル、バックエンドの認証情報、プロバイダーのシークレット、または sensitive な出力値を決して公開しないでください。
• 変更ゲート（レビュー済みプランの後に --yes を指定するか、人間から明示的な指示を受けること）なしに、apply、import、state push、force-unlock を決して実行しないでください。
• ドリフトを「修正」するためだけに、状態またはリソースを決して削除しないでください。整合させるか、インポートしてください。
• モジュールの required_providers とバージョンの固定を確認せずに、プロバイダー固有の手順を決して実行しないでください。

使用しない場合

• IaC の方法論、ツールの選定、またはクラウド設計の判断 — platform-engineering にエスカレーションしてください。
• クラウドプロバイダーの詳細（AWS/GCP/Azure のサービスごとの運用）— プロバイダーのリファレンスとプラットフォームのパターンは platform-engineering にあります。このスキルが扱うのは Terraform/OpenTofu ツール自体です。
• Ansible、Pulumi、CloudFormation、または CDK — それぞれ独自の運用上の契約を持つ別のツールです。ここで扱うのは Terraform/OpenTofu のみです。
• 新しいモジュールを一から設計する場合（構成、インターフェース、バージョニング方針）— まず platform-engineering の方法論を参考にし、その後、このスキルで実行してください。