Hive 项目 Terraform Tool:基于 Terraform Cloud/Enterprise API 的工作区与 Run 管理 MCP 工具实战指南
Hive 项目 Terraform Tool:基于 Terraform Cloud/Enterprise API 的工作区与 Run 管理 MCP 工具实战指南
导读:本文围绕 Terraform Tool 展开,它是 Hive 项目 Aden Tools 工具集中用于通过 Terraform Cloud / HCP Terraform / Terraform Enterprise REST API v2 管理工作区(workspace)与运行(run)的 MCP 工具。读完本文,你将掌握 5 个核心工具的调用方式、
TFC_TOKEN与TFC_URL环境变量配置、参数与默认值细节、错误处理约定,并通过源码与测试理解其底层实现原理,能够直接在你的 AI Agent 工作流中编排 Terraform 基础设施的查询与部署触发。
一、工具定位与能力总览
Terraform Tool 是 Aden Tools(tools/src/aden_tools)中负责 Terraform Cloud/Enterprise 集成的一小组 MCP 工具,核心目标是把 Terraform Cloud 的工作区管理与Run 生命周期管理通过 REST API v2 暴露给 AI Agent 调用。它不执行本地的 terraform plan/apply,而是以远程方式驱动 Terraform Cloud 上的工作区,这与 Terraform Cloud 的 remote execution 模式天然契合。
工具注册入口为 tools/src/aden_tools/tools/init.py 中的 from .terraform_tool import register_tools as register_terraform,包结构如下:
- tools/src/aden_tools/tools/terraform_tool/terraform_tool.py:全部 5 个工具的实现;
- tools/src/aden_tools/tools/terraform_tool/init.py:导出
register_tools; - tools/src/aden_tools/credentials/terraform.py:
TFC_TOKEN凭据规范定义; - tools/tests/tools/test_terraform_tool.py:覆盖全部工具的成功与异常路径测试。
工具清单如下表(与 README 一致):
| Tool | Description |
|---|---|
terraform_list_workspaces |
List workspaces in an organization |
terraform_get_workspace |
Get details of a specific workspace |
terraform_list_runs |
List runs for a workspace |
terraform_get_run |
Get details of a specific run |
terraform_create_run |
Trigger a new plan/apply run |
二、环境配置:TFC_TOKEN 与 TFC_URL
工具通过环境变量完成认证与目标环境配置:
| Variable | Description |
|---|---|
TFC_TOKEN |
Terraform Cloud/Enterprise API token |
TFC_URL |
Terraform Enterprise URL (optional, defaults to Terraform Cloud) |
TFC_TOKEN为必需项:缺少时所有工具都会立即返回{"error": "TFC_TOKEN is required", "help": "Set TFC_TOKEN environment variable"};TFC_URL为可选项:默认指向 Terraform Cloud(https://app.terraform.io),自托管 Terraform Enterprise 时设置为你的实例地址;organization名称不是环境变量,而是作为terraform_list_workspaces的调用参数传入(README 特别强调的注意点)。
从源码看,配置解析集中在 _get_config()(terraform_tool.py):
DEFAULT_URL = "https://app.terraform.io"
def _get_config() -> tuple[str, dict] | dict:
token = os.getenv("TFC_TOKEN", "")
if not token:
return {"error": "TFC_TOKEN is required", "help": "Set TFC_TOKEN environment variable"}
url = os.getenv("TFC_URL", DEFAULT_URL).rstrip("/")
base_url = f"{url}/api/v2"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/vnd.api+json",
}
return base_url, headers
关键实现细节:
- API 版本路径:请求地址统一拼接为
{TFC_URL}/api/v2,对应 Terraform Cloud REST API v2; - 认证头:使用
Authorization: Bearer <token>,即标准的 Bearer Token 方式;Content-Type设为application/vnd.api+json,遵循 JSON:API 规范; - URL 尾部斜杠:
rstrip("/")防止用户配置TFC_URL时多带/导致路径拼接错误。
凭据侧的规范定义在 tools/src/aden_tools/credentials/terraform.py,它把 TFC_TOKEN 绑定到全部 5 个工具,声明为 required=True、startup_required=False(即不需要服务启动时强制就绪,属于按需校验的凭据),并给出获取指引:
TERRAFORM_CREDENTIALS = {
"tfc_token": CredentialSpec(
env_var="TFC_TOKEN",
tools=[
"terraform_list_workspaces",
"terraform_get_workspace",
"terraform_list_runs",
"terraform_get_run",
"terraform_create_run",
],
required=True,
startup_required=False,
direct_api_key_supported=True,
description="Terraform Cloud API token (User or Team token)",
credential_id="tfc_token",
credential_key="api_key",
),
}
在 Unix 环境设置变量并启动工具服务的典型做法:
export TFC_TOKEN=your-api-token
# 自托管 Terraform Enterprise 时才需要:
export TFC_URL=https://your-host.example.com
三、5 个工具的使用方法与参数详解
所有工具在调用前都会先执行 _get_config() 校验凭据,再执行参数校验;缺参时返回 {"error": "<param> is required"}。HTTP 层封装了 GET 与 POST 两个内部函数(terraform_tool.py),统一设置 30 秒超时,并约定:响应状态码 ≥ 400 时返回 {"error": f"HTTP {status_code}: {response_text[:500]}"},否则返回 JSON。
3.1 terraform_list_workspaces:列出组织下所有工作区
terraform_list_workspaces(organization="my-org")
完整签名与参数(来自 terraform_tool.py):
def terraform_list_workspaces(
organization: str,
search: str = "",
page_size: int = 20,
page_number: int = 1,
) -> dict:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
organization |
str | 必填 | 组织名称,缺省返回 {"error": "organization is required"} |
search |
str | "" |
按名称搜索工作区,非空时映射为 search[name] 查询参数 |
page_size |
int | 20 |
每页结果数,源码中通过 min(page_size, 100) 强制上限 100 |
page_number |
int | 1 |
页码 |
底层请求 GET {base_url}/organizations/{organization}/workspaces,携带 page[size]、page[number],可选的 search[name]。响应会从 JSON:API 的 data 与 meta.pagination 中抽取,返回结构化结果:
{
"count": len(workspaces),
"total_count": meta.get("total-count"),
"total_pages": meta.get("total-pages"),
"workspaces": [_extract_workspace(ws) for ws in workspaces],
}
3.2 terraform_get_workspace:查看单个工作区详情
terraform_get_workspace(workspace_id="ws-abc123")
对应 GET {base_url}/workspaces/{workspace_id}(terraform_tool.py)。相比列表,详情模式额外抽取 description、vcs_repo、working_directory 字段,适合排查工作区绑定仓库与目录等细粒度信息。
3.3 terraform_list_runs:列出工作区的运行记录
terraform_list_runs(workspace_id="ws-abc123")
完整签名:
def terraform_list_runs(
workspace_id: str,
status: str = "",
page_size: int = 20,
page_number: int = 1,
) -> dict:
status 非空时映射为 filter[status] 查询参数,可按状态过滤(如 applied、planned、errored)。请求 GET {base_url}/workspaces/{workspace_id}/runs,返回结构与列表工作区一致(count / total_count / total_pages / runs),每个 run 经过 _extract_run 归一化。
3.4 terraform_get_run:查看单个 Run 详情
terraform_get_run(run_id="run-abc123")
对应 GET {base_url}/runs/{run_id}(terraform_tool.py)。在 _extract_run 基础上额外补充 plan_and_apply(内含 plan-queued-at 时间戳)与 permissions(如 can-apply)字段,便于判断当前 Run 是否可继续操作。
3.5 terraform_create_run:触发新的 plan/apply 运行
terraform_create_run(workspace_id="ws-abc123", message="Deploy v2.1.0")
完整签名(terraform_tool.py):
def terraform_create_run(
workspace_id: str,
message: str = "Triggered via API",
auto_apply: bool = False,
is_destroy: bool = False,
plan_only: bool = False,
) -> dict:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
workspace_id |
str | 必填 | 目标工作区 ID |
message |
str | "Triggered via API" |
Run 的提交说明 |
auto_apply |
bool | False |
plan 成功后是否自动 apply |
is_destroy |
bool | False |
是否执行 destroy plan(销毁资源) |
plan_only |
bool | False |
是否仅执行 plan 不 apply |
该工具通过 POST {base_url}/runs 发送符合 JSON:API 规范的请求体,将 workspace_id 放入 relationships.workspace.data.id,把 message / auto-apply / is-destroy / plan-only 放入 attributes。成功返回 _extract_run 归一化后的新 Run 信息(典型状态为 pending)。这是唯一一个写操作工具,也是 Agent 实现「自动部署」闭环的关键入口。
四、返回字段归一化:JSON:API 响应如何被简化
Terraform Cloud API 返回的是 JSON:API 格式资源,字段带连字符且嵌套在 attributes 中,直接暴露给 LLM 会增加理解负担。因此源码通过两个抽取函数归一化为蛇形命名的扁平 dict:
_extract_workspace(terraform_tool.py)返回:id、name、terraform_version(terraform-version)、execution_mode(execution-mode)、auto_apply(auto-apply)、locked、resource_count(resource-count)、created_at、updated_at。
_extract_run(terraform_tool.py)返回:id、status、message、source、trigger_reason(trigger-reason)、is_destroy(is-destroy)、plan_only(plan-only)、has_changes(has-changes)、auto_apply、created_at。
这一设计让 Agent 拿到的字段名与 README 及 Python 工具接口保持一致,也便于后续在 prompt 中直接引用返回结构。
五、错误处理约定
README 明确「所有工具在失败时返回错误 dict」而非抛异常,这是 Aden Tools 面向 LLM 的统一约定——模型更容易从结构化返回值中判断失败原因并自我纠错。典型错误形态:
{"error": "TFC_TOKEN is required", "help": "Set TFC_TOKEN environment variable"}
{"error": "organization is required"}
{"error": "Request timed out"}
结合源码,错误返回共分四类:
- 凭据缺失:
TFC_TOKEN未设置,附带help字段提示如何修复; - 参数缺失:
organization/workspace_id/run_id为空字符串时返回对应error; - HTTP 错误:状态码 ≥ 400 时返回
HTTP {status_code}与响应正文前 500 字符,便于排查 401 鉴权失败、404 资源不存在、429 限流等问题; - 超时:
httpx的 30 秒超时触发网络层异常(README 示例中的Request timed out形态)。
Agent 侧的应对策略是:看到 error 键即视为失败;对凭据类错误提示用户补充环境变量;对参数类错误修正参数重试;对 4xx 检查 Token 权限与资源 ID 是否正确。
六、源码级验证:测试如何保障工具行为
tools/tests/tools/test_terraform_tool.py 为每个工具都编写了「缺参异常路径 + 成功路径」两类用例,可作为调用行为的权威参考:
- 凭据校验:
test_missing_credentials清空os.environ后断言结果含error; - 参数校验:
test_missing_organization、test_missing_id、test_missing_workspace分别覆盖空 organization / workspace_id / run_id; - 成功路径:通过
unittest.mock.patch拦截httpx.get/httpx.post,注入模拟的 JSON:API 响应,断言字段抽取正确——例如terraform_list_workspaces的成功用例验证了count == 1、workspaces<a href="https://link.gitcode.com/i/20bdacd12d3efa06b4658c43bc2cff2c" target="_blank">0]["name"] == "production"、resource_count == 42(对应 [test_terraform_tool.py); - Run 触发:
test_successful_create验证terraform_create_run返回run-new123与status == "pending"(test_terraform_tool.py)。
测试通过 register_tools(mcp, credentials=None) 把工具注册到 FastMCP 实例后从 mcp._tool_manager._tools 取回函数直接调用,证明该工具集遵循 Aden Tools 统一的「register_tools(mcp, credentials)」注册契约,可被 mcp_server.py 等入口加载。
七、适用前提与注意事项
- 适用范围:本工具面向 Terraform Cloud 与 Terraform Enterprise 的远程工作区管理,不包含本地执行 Terraform CLI 的能力;需要本地执行时可搭配 Aden Tools 的 terminal_tools(tools/src/terminal_tools)。
- 认证前提:必须先在 Terraform Cloud 用户设置中创建 User/Team API token 并配置
TFC_TOKEN;自托管企业版还需TFC_URL。 - 权限提示:
terraform_create_run是写操作,实际能否触发 Run 取决于 Token 对应账号在组织/工作区上的权限(可参考terraform_get_run返回的permissions字段判断),生产环境建议使用最小权限的 Team Token。 - 网络与超时:所有请求固定 30 秒超时;列表类工具支持分页(每页上限 100 条),处理大规模组织时请利用
page_number/total_pages翻页取全。
八、小结
Terraform Tool 以 5 个精炼的 MCP 工具覆盖了 Terraform Cloud/Enterprise 工作区查询与 Run 触发的完整闭环:terraform_list_workspaces 定位工作区 → terraform_get_workspace 查看细节 → terraform_list_runs / terraform_get_run 追踪运行状态 → terraform_create_run 触发部署或销毁。配合 Aden Tools 的凭据规范(tools/src/aden_tools/credentials/terraform.py)与完善的测试用例(tools/tests/tools/test_terraform_tool.py),开发者可以在 Hive 的多 Agent 工作流中安全地编排「基础设施即代码」的远程执行,把 Terraform 运维能力直接交到 AI Agent 手中。