![[小ネタ]HCP Terraform・Terraform EnterpriseでAPI経由でPlanの結果を確認する方法](https://images.ctfassets.net/ct0aopd36mqt/wp-thumbnail-4cb846fab131f32dfae750ca0329eed7/e12259af17223fd6dfb94f78098dc327/eyecatch_hcpterraform?w=3840&fm=webp)
[小ネタ]HCP Terraform・Terraform EnterpriseでAPI経由でPlanの結果を確認する方法
2025.11.25
HCP Terraformで実行したPlanの結果をAPIで取得したいことがありました。
可能でしたが、少し悩んだのでブログにまとめます。
結論: get_run_details APIにinclude=planをつける
Runの詳細を取得するAPIget_run_detailsが提供されています。
これにクエリパラメータとして?include=planを付けることで、Planの結果をダウンロードできるURLが表示されます。このURLにアクセスすることでPlanの内容を確認できます。
Run ID(リクエスト内のrun-から始まる文字列)は公式ドキュメントのサンプル値を使っています。各自の環境に合わせて置き換えてください。
サンプルリクエスト
curl \
--header "Authorization: Bearer $TOKEN" \
"https://app.terraform.io/api/v2/runs/run-bWSq4YeYpfrW4mx7?include=plan"
サンプルリクエスト log-read-urlのみ取得
curl \
--header "Authorization: Bearer $TOKEN" \
"https://app.terraform.io/api/v2/runs/run-zRHiQDTuJqFrmwBi?include=plan" \
| jq -r'.included[0].attributes."log-read-url"'
デフォルトではPlanの詳細は含まれない
デフォルトでは、Planの詳細はレスポンスとして返ってきません。
リクエスト
curl \
--header "Authorization: Bearer $TOKEN" \
"https://app.terraform.io/api/v2/runs/run-bWSq4YeYpfrW4mx7"
レスポンス
{
"data": {
"id": "run-CZcmD7eagjhyX0vN",
"type": "runs",
"attributes": {
"actions": {
"is-cancelable": true,
"is-confirmable": false,
"is-discardable": false,
"is-force-cancelable": false
},
"canceled-at": null,
"created-at": "2021-05-24T07:38:04.171Z",
"has-changes": false,
"auto-apply": false,
"allow-empty-apply": false,
"allow-config-generation": false,
"is-destroy": false,
"message": "Custom message",
"plan-only": false,
"source": "tfe-api",
"status-timestamps": {
"plan-queueable-at": "2021-05-24T07:38:04+00:00"
},
"status": "pending",
"trigger-reason": "manual",
"target-addrs": null,
"permissions": {
"can-apply": true,
"can-cancel": true,
"can-comment": true,
"can-discard": true,
"can-force-execute": true,
"can-force-cancel": true,
"can-override-policy-check": true
},
"refresh": false,
"refresh-only": false,
"replace-addrs": null,
"save-plan": false,
"variables": []
},
"relationships": {
"apply": {...},
"comments": {...},
"configuration-version": {...},
"cost-estimate": {...},
"created-by": {...},
"input-state-version": {...},
"plan": {...},
"run-events": {...},
"policy-checks": {...},
"task-stages": {...},
"workspace": {...},
"workspace-run-alerts": {...}
},
"links": {
"self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7"
}
}
}
Plan詳細を取得したい場合の方法を調べるため、ドキュメントを確認したところ、クエリパラメータの記述がありました。
The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:
plan - Additional information about plans.
クエリパラメータで?include=planを指定してあげると良さそうです。
リクエスト
curl \
--header "Authorization: Bearer $TOKEN" \
"https://app.terraform.io/api/v2/runs/run-bWSq4YeYpfrW4mx7?include=plan"
レスポンス
{
"data": {
"id": "run-bWSq4YeYpfrW4mx7",
"type": "runs"
},
# 省略
"included": [
{
"id": "plan-hoge",
"type": "plans",
"attributes": {
"has-changes": false,
"status": "errored",
"status-timestamps": {
"errored-at": "2025-11-21T08:01:45+00:00",
"started-at": "2025-11-21T08:01:27+00:00",
"agent-queued-at": "2025-11-21T08:01:24+00:00"
},
"log-read-url": "https://archivist.terraform.io/v1/object/hogehoge",
"resource-additions": null,
"resource-changes": null,
"resource-destructions": null,
"resource-imports": null,
"structured-run-output-enabled": true,
"generated-configuration": false,
"actions": {
"is-exportable": false
},
"execution-details": {
"mode": "remote"
},
"permissions": {
"can-export": true
},
"action-invocations": null
},
"relationships": {
"state-versions": {
"data": []
},
"exports": {
"data": []
}
},
"links": {
"self": "/api/v2/plans/plan-hogehoge",
"json-output": "/api/v2/plans/plan-hogehoge/json-output",
"json-output-redacted": "/api/v2/plans/plan-hogehoge/json-output-redacted",
"json-schema": "/api/v2/plans/plan-hogehoge/json-schema"
}
}
]
}
included部分のレスポンスが追加されたことを確認できました。
log-read-urlのURLにアクセスするとファイルがダウンロードされます。
ファイルを開くと、Plan詳細を確認できました。
Terraform v1.13.1
on linux_amd64
Initializing plugins and modules...
{"@level":"info","@message":"Terraform 1.13.1","@module":"terraform.ui","@timestamp":"2025-11-21T08:01:41.212289Z","terraform":"1.13.1","type":"version","ui":"1.2"}
{"@level":"error","@message":"Error: Reference to undeclared input variable","@module":"terraform.ui","@timestamp":"2025-11-21T08:01:45.038522Z","diagnostic":{"severity":"error","summary":"Reference to undeclared input variable","detail":"An input variable with the name \"non_existent_variable\" has not been declared. This variable can be declared with a variable \"non_existent_variable\" {} block.","range":{"filename":"main.tf","start":{"line":20,"column":19,"byte":543},"end":{"line":20,"column":44,"byte":568}},"snippet":{"context":"module \"vpc\"","code":" Environment = var.non_existent_variable","start_line":20,"highlight_start_offset":18,"highlight_end_offset":43,"values":[]}},"type":"diagnostic"}
Operation failed: failed running terraform plan (exit 1)
HCP Terraform上で以下の表示がされているRunで取得しました。どちらでも同様のエラーメッセージが確認できました。
おわりに
Plan結果を使って何かしたいときにHCP Terraform・Terraform Enterprise APIのクエリパラメータの存在をしっていると役立つかもです。
AIエージェントにPlanの結果を渡したくて調べてみました。
terraform cliでplanを実行させて上げれば、HCP Terraform上でRunを行いつつ標準出力に結果だけストリーミングできるため、直接terraform cliを実行したほうがシンプルそうですね。
