terraform state pull/push 徹底理解: 低レベルでの状態操作

Terraform の状態(state)は IaC 運用の中核です。ふだんは apply/plan とバックエンドが安全に扱いますが、障害対応や監査では低レベルの直接操作が必要になることがあります。本稿では terraform state pull/push を中心に、破壊的変更を避けるための手順と注意点を整理します。

HashiCorp 公式の基本仕様に沿い、バージョン依存となりやすい挙動には注意書きを添えています。試験対策(プロ/上級)の観点から、コマンド間の使い分けやロック、バックエンド差異も押さえます。

pull/push の成り立ちと前提知識

terraform state pull は現在の状態をバックエンドから取得して標準出力に JSON で出します。状態は読み取りのみで、インフラやバックエンドを変更しません。対して terraform state push はローカルの tfstate ファイルをバックエンドへ書き戻します。バックエンドやロックの制約に強く依存し、誤用は破壊的な差分や競合を招きます。

state は serial(世代番号)と lineage(系統 ID)を持ち、正しい後続世代のみが受理されます。push は通常 serial 不一致で拒否されますが、-force により強制上書きも可能です。強制上書きは最後の手段であり、同時実行の停止・ロック取得・直前バックアップ取得・直後の plan 検証が必須です。

• pull は安全な読み取り。通常ロックを奪わないが、実行中の apply と併走させない
• push は書き込み操作。バックエンドにより未対応/制限あり。実行中の他ジョブを必ず停止
• 状態は secrets を含み得る。取り扱い・保管・転送は厳重に
• バックエンドのロック機構(S3+DynamoDB、Azure Blob Lease、GCS preconditions など)を理解する

pull/push のデータフローとロック(概念図)

状態メタ情報の確認と比較

# 現在の状態を取得し、メタ情報を確認
terraform state pull > current.tfstate
jq '{serial, lineage, resources: (.resources|length)}' current.tfstate

# 直近バックアップとの差分を軽量比較(計数/メタ)
jq '{serial, lineage}' current.tfstate backup-20240115.tfstate

diff <(jq -S '.resources[].type+"."+.resources[].name? // empty' current.tfstate | sort) \
     <(jq -S '.resources[].type+"."+.resources[].name? // empty' backup-20240115.tfstate | sort)

terraform state pull の安全な使い方

pull は調査・監査・バックアップの起点として有用です。実行中の plan/apply がなければ基本的に安全です。取得した JSON は機密を含む可能性があるため、出力先とアクセス権に注意してください。

管理型バックエンドでは組織/ワークスペース権限により取得が制限される場合があります。実行前に認証状態(terraform login 等)と権限を確認し、長期保存は暗号化ストレージに限定します。

• 実行中の Terraform ジョブがないことを確認
• 取得前にバックアップの命名規則と保存先を決める
• JSON を jq で要約してレビュー(全体を広範に配布しない)
• 必要に応じて -no-color など出力整形と併用(標準出力を安全に扱う)

pull の実例と要約

# バックアップ取得(タイムスタンプ付)
ts=$(date +%Y%m%d-%H%M%S)
terraform state pull > backup-$ts.tfstate

# メタの健全性確認
jq '{serial, lineage, resCount: (.resources|length)}' backup-$ts.tfstate

# 秘匿情報がないか単純スキャン(過信は禁物)
egrep -in '(password|secret|token|apikey)' backup-$ts.tfstate || true

terraform state push のリスクと安全な復旧手順

push は状態の置換です。誤用は大規模な差分や破壊的変更を誘発します。通常運用では使わず、障害復旧や誤操作のロールバック等の最終手段として限定してください。サポートの有無・ロックの前提はバックエンドに依存します。

安全な復旧は「同時実行停止 → 事前バックアップ → 検証 → ロック取得(可能なら) → push → 直後に plan で二重検証」の順で行います。serial 不一致で拒否された場合、理由を調査しない強制上書きは避けます。

• CI/CD と手動実行を全停止し、ロックと変更凍結を宣言
• 現行 state の pull と、復旧候補の tfstate を比較
• バックエンドのロック/世代管理の動作を再確認
• push 後は terraform plan を行い、想定外の destroy/add がないか確認

push の手順(例: S3 バックエンド)

# 1) 現行を退避
terraform state pull > before-$ts.tfstate

# 2) 復旧候補(backup-20240115.tfstate)のメタ確認
jq '{serial, lineage}' backup-20240115.tfstate

# 3) 可能ならロックが取れる時間帯に実施(S3+DynamoDB のテーブルでロック監視)
# 4) push を試行(まずは -force なし)
terraform state push backup-20240115.tfstate

# serial 不一致などで拒否された理由を調査。どうしても必要な場合のみ、業務停止下で強制上書き
# terraform state push -force backup-20240115.tfstate

# 5) 直後に差分確認
terraform plan -refresh=false   # まずは状態とコードの整合のみを確認
terraform plan                  # 続けて実環境も含めた差分を確認

バックエンドごとの注意点と制約

バックエンドはロック方式や API 制約が異なります。push/pull の可否と前提は各ドキュメントを確認してください。特に管理型バックエンドではサーバ側で世代と権限を厳密管理しており、push が未サポート/制限される場合があります。

バックエンド移行は terraform init -migrate-state を優先し、push での手動移送は避けます。HTTP バックエンドはサーバ実装が機能可否を決めるため、仕様整備がない環境では push は使わないのが無難です。

• S3: DynamoDB ロック推奨。SSE-KMS 等で暗号化。バージョニング有効化で復旧容易化
• GCS: 世代管理(Object Versioning)と条件付き書込で同時実行を防止
• AzureRM: Blob のリースでロック。SSE/ACL を適切に設定
• HTTP: サーバ実装次第。push/lock 未対応のことがある
• Terraform Cloud/Enterprise: サービス管理の state。CLI の一部サブコマンドは制限される場合がある。公式手順を参照

代表的な backend 設定例(HCL 抜粋)

# S3 バックエンド(例)
terraform {
  backend "s3" {
    bucket         = "tfstate-prod"
    key            = "network/terraform.tfstate"
    region         = "ap-northeast-1"
    dynamodb_table = "tfstate-lock"
    encrypt        = true
  }
}

# GCS バックエンド(例)
terraform {
  backend "gcs" {
    bucket = "tfstate-prod-gcs"
    prefix = "network"
  }
}

状態ファイルのセキュリティと監査

state はリソース属性を広範に含み、プロバイダが sensitive 属性で隠さない限り平文で格納されます。たとえバックエンドが暗号化していても、pull で出力したローカルファイルは平文 JSON です。アクセス制御と保管のガバナンスを設けてください。

監査は必要最小限のメタと件数要約から始め、全文配布は避けます。長期保存は鍵管理(KMS など)と監査証跡を備えたストレージに限定し、共有チャネル(メール/チャット)への貼付は厳禁です。

• バックエンドは必ず暗号化(SSE, CMEK)とバージョニングを有効化
• pull の出力は期限付保管とアクセス最小化
• jq で要約し、機微情報の拡散を抑制
• 不要になったバックアップの安全消去(シュレッド/安全削除)

監査用の安全な要約サンプル

# リソース件数と types の一覧を抽出
jq '{serial, lineage, count: (.resources|length), types: ([.resources[].type] | unique)}' backup.tfstate

# 明示的な機微候補属性をサーチ
jq '.. | objects | to_entries[] | select(.key|test("(?i)(password|secret|token|apikey)"))' backup.tfstate

試験対策: コマンドの使い分けと落とし穴

出題は「どのコマンドが適切か」「安全に実施する順序は何か」が中心です。pull/push は低レベル操作であり、通常は mv/rm/import や init -migrate-state、apply -refresh-only で目的を達します。push は災害復旧の最終手段である点を強調して覚えます。

また、状態と実リソースの関係を正しく言語化できることが重要です。state を書き換えても実リソースは変わりません。逆に import してもコードがないと管理できません。用語の混同を避けましょう。

• backend 移行は terraform init -migrate-state を選ぶ
• ドリフトの是正は apply -refresh-only を優先(従来の refresh は非推奨版で注意)
• リソースの移設は terraform state mv、除外は terraform state rm
• pull は読み取り、push は置換。push はロックと停止の下でのみ

よくある選択肢の見分け方(例)

# 既存 VPC を IaC 管理下に
# 誤: state push で VPC の状態を置換
# 正: terraform import aws_vpc.main vpc-xxxx && plan

# provider の命名変更
# 正: terraform state replace-provider 'hashicorp/aws' 'hashicorp/aws'  # アドレス修正の例

問題で確認

よくある質問