tfc-run-status

Terraform Cloud 运行状态

快速检查 Terraform Cloud 运行状态，包括资源变更数量、时间戳和可用操作。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用同类技能……
检查已知运行 ID 是否成功、失败或正在进行	阅读完整的计划／应用日志文本（tfc-run-logs）
轮询运行状态，直到其达到最终状态	分析资源变更的结构化计划 JSON（tfc-plan-json）
检查运行可用的操作（确认／取消／丢弃）	列出或筛选多个运行以查找 ID（tfc-list-runs）
查看成本估算或资源新增／变更／销毁数量	浏览 FVH 工作区的最新运行（tfc-workspace-runs）

前提条件

export TFE_TOKEN="your-api-token"        # User or team token
export TFE_ADDRESS="app.terraform.io"    # Optional

核心命令

完整状态检查

#!/bin/bash
set -euo pipefail

TOKEN="${TFE_TOKEN:?TFE_TOKEN not set}"
BASE_URL="https://${TFE_ADDRESS:-app.terraform.io}/api/v2"
RUN_ID="${1:?Usage: $0 <run-id>}"

curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/runs/$RUN_ID?include=plan,apply,cost-estimate" | \
  jq -r '
    "Run ID:      " + .data.id,
    "Status:      " + .data.attributes.status,
    "Message:     " + (.data.attributes.message // "No message"),
    "Created:     " + .data.attributes."created-at",
    "Has Changes: " + (.data.attributes."has-changes" | tostring),
    "Auto-Apply:  " + (.data.attributes."auto-apply" | tostring),
    "",
    "Resource Changes:",
    "  Additions:    " + ((.included[] | select(.type == "plans") | .attributes."resource-additions") // 0 | tostring),
    "  Changes:      " + ((.included[] | select(.type == "plans") | .attributes."resource-changes") // 0 | tostring),
    "  Destructions: " + ((.included[] | select(.type == "plans") | .attributes."resource-destructions") // 0 | tostring),
    "",
    "Actions:",
    "  Confirmable:     " + (.data.attributes.actions."is-confirmable" | tostring),
    "  Cancelable:      " + (.data.attributes.actions."is-cancelable" | tostring),
    "  Discardable:     " + (.data.attributes.actions."is-discardable" | tostring),
    "  Force-Cancelable:" + (.data.attributes.actions."is-force-cancelable" | tostring)
  '

仅快速查看状态

TOKEN="${TFE_TOKEN:?TFE_TOKEN not set}"
RUN_ID="run-abc123"

curl -sf --header "Authorization: Bearer $TFE_TOKEN" \
  "https://app.terraform.io/api/v2/runs/$RUN_ID" | \
  jq -r '.data.attributes.status'

查看带时间戳的状态

curl -sf --header "Authorization: Bearer $TFE_TOKEN" \
  "https://app.terraform.io/api/v2/runs/$RUN_ID" | \
  jq -r '
    .data.attributes |
    "Status: " + .status,
    "Timestamps:",
    "  Created:   " + (."created-at" // "N/A"),
    "  Planned:   " + (."status-timestamps"."planned-at" // "N/A"),
    "  Applied:   " + (."status-timestamps"."applied-at" // "N/A")
  '

检查可用操作

curl -sf --header "Authorization: Bearer $TFE_TOKEN" \
  "https://app.terraform.io/api/v2/runs/$RUN_ID" | \
  jq '.data.attributes.actions'

检查权限

curl -sf --header "Authorization: Bearer $TFE_TOKEN" \
  "https://app.terraform.io/api/v2/runs/$RUN_ID" | \
  jq '.data.attributes.permissions'

轮询直到完成

#!/bin/bash
set -euo pipefail

TOKEN="${TFE_TOKEN:?TFE_TOKEN not set}"
RUN_ID="${1:?Usage: $0 <run-id>}"

FINAL_STATES="applied planned_and_finished planned_and_saved discarded errored canceled force_canceled policy_soft_failed"

while true; do
  STATUS=$(curl -sf --header "Authorization: Bearer $TOKEN" \
    "https://app.terraform.io/api/v2/runs/$RUN_ID" | \
    jq -r '.data.attributes.status')

  echo "$(date +%H:%M:%S) Status: $STATUS"

  if echo "$FINAL_STATES" | grep -qw "$STATUS"; then
    echo "Run completed with status: $STATUS"
    exit 0
  fi

  sleep 5
done

JSON 输出

完整运行详情

curl -sf --header "Authorization: Bearer $TFE_TOKEN" \
  "https://app.terraform.io/api/v2/runs/$RUN_ID" | \
  jq '{
    id: .data.id,
    status: .data.attributes.status,
    message: .data.attributes.message,
    created_at: .data.attributes."created-at",
    has_changes: .data.attributes."has-changes",
    auto_apply: .data.attributes."auto-apply",
    is_destroy: .data.attributes."is-destroy",
    actions: .data.attributes.actions,
    timestamps: .data.attributes."status-timestamps"
  }'

包含成本估算

curl -sf --header "Authorization: Bearer $TFE_TOKEN" \
  "https://app.terraform.io/api/v2/runs/$RUN_ID?include=cost-estimate" | \
  jq '
    if .included then
      (.included[] | select(.type == "cost-estimates")) as $ce |
      {
        status: .data.attributes.status,
        cost: {
          prior_monthly: $ce.attributes."prior-monthly-cost",
          proposed_monthly: $ce.attributes."proposed-monthly-cost",
          delta_monthly: $ce.attributes."delta-monthly-cost"
        }
      }
    else
      {status: .data.attributes.status, cost: "N/A"}
    end
  '

运行状态参考

最终状态（运行已完成）

• applied - 已成功应用
• planned_and_finished - 仅计划或无变更
• planned_and_saved - 计划已保存，可供确认
• discarded - 用户已丢弃此运行
• errored - 运行遇到错误
• canceled - 用户已取消此运行
• force_canceled - 已强制终止
• policy_soft_failed - Sentinel 软失败（仅计划）

非最终状态（进行中）

• pending - 初始状态
• fetching / fetching_completed - 正在检索配置
• queuing / plan_queued - 正在等待资源
• planning - 正在进行计划
• planned - 计划已完成，等待确认
• cost_estimating / cost_estimated - 正在估算成本
• policy_checking / policy_checked - Sentinel 评估
• policy_override - 软失败，可覆盖
• confirmed - 用户已确认计划
• apply_queued / applying - 正在进行应用

操作状态

操作	可用条件
is-confirmable	状态为 planned、cost_estimated、policy_checked 或 policy_override
is-cancelable	状态为 planning 或 applying
is-discardable	状态为 pending、planned、cost_estimated、policy_checked 或 policy_override
is-force-cancelable	已调用取消操作，且冷却期已过

另请参阅

• tfc-run-logs：获取运行的计划／应用日志
• tfc-list-runs：列出工作区中的近期运行
• tfc-plan-json：获取结构化计划 JSON 输出