Hive 项目 Terraform Tool:基于 Terraform Cloud/Enterprise API 的工作区与 Run 管理 MCP 工具实战指南

原创2026-09-23 14:43:011,734 阅读
文章标签:人工智能AI AgentAgent 框架多智能体大模型Agent 编排工具调用Agent 记忆

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,包结构如下:

工具清单如下表(与 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

关键实现细节:

  1. API 版本路径:请求地址统一拼接为 {TFC_URL}/api/v2,对应 Terraform Cloud REST API v2;
  2. 认证头:使用 Authorization: Bearer <token>,即标准的 Bearer Token 方式;Content-Type 设为 application/vnd.api+json,遵循 JSON:API 规范;
  3. 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"}

结合源码,错误返回共分四类:

  1. 凭据缺失:TFC_TOKEN 未设置,附带 help 字段提示如何修复;
  2. 参数缺失:organization / workspace_id / run_id 为空字符串时返回对应 error;
  3. HTTP 错误:状态码 ≥ 400 时返回 HTTP {status_code} 与响应正文前 500 字符,便于排查 401 鉴权失败、404 资源不存在、429 限流等问题;
  4. 超时: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 手中。

登录后查看全文
hive