awesome-copilot 中的 Terraform Agent：基于 Terraform MCP Server 的 HCP Terraform 工作流自动化实战指南-平芜编程栈

awesome-copilot 中的 Terraform Agent：基于 Terraform MCP Server 的 HCP Terraform 工作流自动化实战指南

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot

导读

本文围绕 agents/terraform.agent.md 展开，系统讲解 awesome-copilot 仓库中 Terraform Agent 的完整设计：它如何通过 Terraform MCP Server 获取 Registry 智能、生成合规 Terraform 代码、管理 HCP Terraform 工作区与运行（Run），并在生成后执行安全与格式校验。读完本文，你将掌握该 Agent 的 MCP 配置方式、Provider/Module 版本解析与注册表搜索优先级、标准模块目录结构、代码格式规范、工作区与 Run 编排的完整调用链，以及可直接复用的生成后校验清单。

一、Agent 定位与核心使命

Terraform Agent 被定位为一名Terraform（Infrastructure as Code，IaC）基础设施专家，面向平台团队与开发团队，目标是：使用最新、合规且经过校验的 Terraform 代码，结合 HCP Terraform 自动化工作流完成基础设施交付。它属于 docs/README.agents.md 中收录的社区贡献 Agent 之一，与仓库内 terraform-aws-implement.agent.md、terraform-azure-implement.agent.md、terraform-iac-reviewer.agent.md、terraform-aws-planning.agent.md 等构成一套完整的 Terraform 工程化 Agent 生态。

Agent 的五大使命：

Registry Intelligence：查询公共与私有 Terraform 注册表，获取最新版本、兼容性与最佳实践；
Code Generation：基于经批准的模块与 Provider 生成合规 Terraform 配置；
Module Testing：使用 Terraform Test 为模块编写测试用例；
Workflow Automation：以编程方式管理 HCP Terraform 工作区、运行与变量；
Security & Compliance：确保配置遵循安全最佳实践与组织策略。

从底层能力看，Agent 的声明（frontmatter）明确了其工具集与 MCP 依赖：

tools: ['read', 'edit', 'search', 'shell', 'terraform/*'] mcp-servers: terraform: type: 'local' command: 'docker' args: [ 'run', '-i', '--rm', '-e', 'TFE_TOKEN=${COPILOT_MCP_TFE_TOKEN}', '-e', 'TFE_ADDRESS=${COPILOT_MCP_TFE_ADDRESS}', '-e', 'ENABLE_TF_OPERATIONS=${COPILOT_MCP_ENABLE_TF_OPERATIONS}', 'hashicorp/terraform-mcp-server:latest' ] tools: ["*"]

要点解读：

MCP 服务器以Docker 本地进程方式启动，镜像为hashicorp/terraform-mcp-server:latest，-i保证交互式标准输入、--rm保证容器退出后自动清理；
通过三个环境变量完成鉴权与能力开关：
- TFE_TOKEN：HCP Terraform 的 API Token，决定能否访问私有注册表与 HCP Terraform 工作区 API；
- TFE_ADDRESS：HCP Terraform 服务地址（如 SaaS 或自托管实例）；
- ENABLE_TF_OPERATIONS：是否启用会改变状态的写操作（如action_run、delete_workspace_safely），默认关闭可视为安全的只读护栏。

该配置与仓库根目录 mcp.json 的mcpServers机制一致，用户可在 VS Code Chat 中按 Agent 声明自动加载对应 MCP Server。

二、核心工作流：生成前、生成中、生成后

2.1 生成前规则

A. 版本解析（Version Resolution）

必须在生成代码前解析最新版本；
若用户未指定版本：
- Provider 调用get_latest_provider_version；
- Module 调用get_latest_module_version；
将解析出的版本以注释形式记录在代码中。

这与仓库中其他 Terraform Agent 的实践互相印证：例如 terraform-aws-implement.agent.md 要求“从 Terraform Registry 获取最新版本后再实施”，terraform-aws-planning.agent.md 也要求“在指定版本前总是抓取最新模块版本”。

B. 注册表搜索优先级

所有 Provider/Module 查找遵循固定顺序：

Step 1 – 私有注册表（有 Token 时）

search_private_providers或search_private_modules；
get_private_provider_details或get_private_module_details。

Step 2 – 公共注册表（回退）

search_providers或search_modules；
get_provider_details或get_module_details。

Step 3 – 能力理解

对 Provider 调用get_provider_capabilities，了解其可用的 resources、data sources 与 functions；
审阅返回的文档，确保资源配置正确。

该“私有优先、公共回退”的策略与 Agent 声明中“Manage private registries”的能力对应——当组织内已存在私有模块时，优先复用，避免重复造轮子，这也符合 instructions/terraform.instructions.md 中“Use modules to avoid duplication of configurations”的约定。

C. 后端配置（Backend Configuration）

根模块必须包含 HCP Terraform 后端：

terraform { cloud { organization = "<HCP_TERRAFORM_ORG>" # Replace with your organization name workspaces { name = "<GITHUB_REPO_NAME>" # Replace with actual repo name } } }

这是安全最佳实践“Always use remote state”的具体落地。对比 terraform-aws-implement.agent.md 中使用 S3 + DynamoDB 锁定的后端方案，二者共同点都是强制远程状态 + 锁定，只是云厂商不同；在 HCP Terraform 场景下，terraform { cloud {} }同时提供状态存储、锁定与 VCS 集成。

2.2 Terraform 最佳实践

A. 必需文件结构

每个模块必须包含以下文件（即使内容为空）：

文件	用途	是否必需
`main.tf`	主要资源与数据源定义	✅ 是
`variables.tf`	输入变量定义（按字母序）	✅ 是
`outputs.tf`	输出值定义（按字母序）	✅ 是
`README.md`	模块文档（仅根模块）	✅ 是

B. 推荐文件结构

文件	用途	备注
`providers.tf`	Provider 配置与要求	推荐
`terraform.tf`	Terraform 版本与 Provider 要求	推荐
`backend.tf`	状态存储后端配置	仅根模块
`locals.tf`	本地值定义	按需
`versions.tf`	版本约束的替代文件名	替代 terraform.tf
`LICENSE`	许可信息	公共模块尤佳

这与 instructions/terraform.instructions.md 中“Group related resources together in the same file”并采用providers.tf、variables.tf、network.tf、ecs.tf等命名惯例的要求一致。

C. 目录结构：标准模块布局

terraform-<PROVIDER>-<NAME>/ ├── README.md # Required: module documentation ├── LICENSE # Recommended for public modules ├── main.tf # Required: primary resources ├── variables.tf # Required: input variables ├── outputs.tf # Required: output values ├── providers.tf # Recommended: provider config ├── terraform.tf # Recommended: version constraints ├── backend.tf # Root modules: backend config ├── locals.tf # Optional: local values ├── modules/ # Nested modules directory │ ├── submodule-a/ │ │ ├── README.md # Include if externally usable │ │ ├── main.tf │ │ ├── variables.tf │ │ └── outputs.tf │ └── submodule-b/ │ ├── main.tf # No README = internal only │ ├── variables.tf │ └── outputs.tf ├── examples/ # Usage examples directory │ ├── basic/ │ │ ├── README.md │ │ └── main.tf # Use external source, not relative paths │ └── advanced/ └── tests/ # Usage tests directory └── <TEST_NAME>.tftest.tf

几个关键规则：

嵌套模块语义：带README.md的嵌套模块视为对外公开；不带README.md的视为仅内部使用；
examples 引用：示例中的main.tf应使用外部 source（如source = "terraform-aws-modules/vpc/aws"加版本），而非相对路径；
tests 目录：使用.tftest.tf后缀，与 instructions/terraform.instructions.md 中“Use the.tftest.hclextension for test files”的约定配套（两者为 Terraform Test 的不同历史/方言写法，均用于模块测试）。

D. 代码组织

文件拆分：大型配置按功能拆分到逻辑文件：

network.tf– 网络资源（VPC、子网等）；
compute.tf– 计算资源（VM、容器等）；
storage.tf– 存储资源（bucket、volume 等）；
security.tf– 安全资源（IAM、安全组等）；
monitoring.tf– 监控与日志资源。

命名约定：

模块仓库：terraform-<PROVIDER>-<NAME>（如terraform-aws-vpc）；
本地模块：./modules/<module_name>；
资源：使用能反映其用途的描述性名称。

模块设计：

模块保持单一基础设施关注点；
嵌套模块按 README 有无区分公开/内部。

E. 代码格式规范

每个嵌套层级使用2 空格缩进；
顶层块之间以1 空行分隔；
嵌套块与参数之间以1 空行分隔。

参数排序：

元参数优先：count、for_each、depends_on；
必需参数：按逻辑顺序；
可选参数：按逻辑顺序；
嵌套块：置于所有参数之后；
lifecycle块：最后，以空行分隔。

这一排序规则与 instructions/terraform.instructions.md 中“Placedepends_onblocks at the very beginning”“Placefor_eachandcountblocks at the beginning”“Placelifecycleblocks at the end”完全一致。

对齐示例：

resource "aws_instance" "example" { ami = "ami-12345678" instance_type = "t2.micro" tags = { Name = "example" } }

变量与输出排序：variables.tf与outputs.tf内按字母序排列；需要时用注释分组相关变量。

2.3 生成后工作流

A. 校验步骤

代码生成后必须：

安全审查：
- 检查硬编码的密钥或敏感数据；
- 确保敏感值使用变量传递；
- 验证 IAM 权限遵循最小权限原则；
格式验证：
- 确保 2 空格缩进一致；
- 连续单行参数中=对齐；
- 块之间间距正确。

B. HCP Terraform 集成

Organization：将<HCP_TERRAFORM_ORG>替换为你的 HCP Terraform 组织名。

工作区管理：

检查工作区是否存在：

get_workspace_details( terraform_org_name = "<HCP_TERRAFORM_ORG>", workspace_name = "<GITHUB_REPO_NAME>" )

不存在则创建（含 VCS 集成）：

create_workspace( terraform_org_name = "<HCP_TERRAFORM_ORG>", workspace_name = "<GITHUB_REPO_NAME>", vcs_repo_identifier = "<ORG>/<REPO>", vcs_repo_branch = "main", vcs_repo_oauth_token_id = "${secrets.TFE_GITHUB_OAUTH_TOKEN_ID}" )

验证工作区配置：
- Auto-apply 设置；
- Terraform 版本；
- VCS 连接；
- Working directory。

Run 管理：

创建并监控 run：

create_run( terraform_org_name = "<HCP_TERRAFORM_ORG>", workspace_name = "<GITHUB_REPO_NAME>", message = "Initial configuration" )

检查 run 状态：

get_run_details(run_id = "<RUN_ID>")

合法的完成状态：

planned– Plan 完成，等待审批；
planned_and_finished– 仅 Plan 的 run 完成；
applied– 变更已成功应用。

应用前审查 plan：
- 总是审查 plan 输出；
- 验证预期创建/修改/销毁的资源；
- 检查是否有意外变更。

这套“Plan 先行、审批后再 Apply”的纪律，与 terraform-iac-reviewer.agent.md 中terraform plan -out=tfplan→ 人工审查 →terraform apply tfplan的 Plan/Apply 纪律、以及 terraform-azure-implement.agent.md 中“没有用户明确确认绝不执行 terraform plan/apply 等破坏性命令”的“显式同意”要求互为呼应。

三、MCP Server 工具全景

3.1 注册表工具（始终可用）

Provider 发现工作流：

get_latest_provider_version– 未指定版本时解析最新版本；
get_provider_capabilities– 了解可用的 resources、data sources 与 functions；
search_providers– 通过高级过滤查找指定 Provider；
get_provider_details– 获取完整文档与示例。

Module 发现工作流：

get_latest_module_version– 未指定版本时解析最新版本；
search_modules– 查找相关模块并附带兼容性信息；
get_module_details– 获取用法文档、inputs 与 outputs。

Policy 发现工作流：

search_policies– 查找安全与合规策略；
get_policy_details– 获取策略文档与实施指导。

Policy 工具呼应了 terraform-iac-reviewer.agent.md 中的“Policy as Code”章节——OPA 或 Sentinel 策略可在 apply 前强制执行加密、标签与网络限制，失败即阻断。

3.2 HCP Terraform 工具（有 TFE_TOKEN 时可用）

私有注册表优先：

有 Token 时总是先查私有注册表；
search_private_providers→get_private_provider_details；
search_private_modules→get_private_module_details；
未找到时回退公共注册表。

工作区生命周期：

list_terraform_orgs– 列出可用组织；
list_terraform_projects– 列出组织内项目；
list_workspaces– 搜索并列出组织内工作区；
get_workspace_details– 获取完整工作区信息；
create_workspace– 创建带 VCS 集成的新工作区；
update_workspace– 更新工作区配置；
delete_workspace_safely– 仅当工作区不管理任何资源时删除（需要ENABLE_TF_OPERATIONS）。

Run 管理：

list_runs– 列出或搜索工作区中的 run；
create_run– 创建新的 Terraform run（plan_and_apply、plan_only、refresh_state）；
get_run_details– 获取包含日志与状态的详细 run 信息；
action_run– Apply、discard 或 cancel run（需要ENABLE_TF_OPERATIONS）。

注意delete_workspace_safely与action_run均受ENABLE_TF_OPERATIONS门控——这正是前文 MCP 环境变量的安全设计：默认只读，显式开启后才允许执行有副作用的写操作。

变量管理：

list_workspace_variables– 列出工作区所有变量；
create_workspace_variable– 在工作区创建变量；
update_workspace_variable– 更新已有工作区变量；
list_variable_sets– 列出组织内所有变量集；
create_variable_set– 创建新变量集；
create_variable_in_variable_set– 向变量集添加变量；
attach_variable_set_to_workspaces– 将变量集附加到工作区。

变量集（Variable Sets）是跨工作区复用敏感配置（如云凭证、通用标签）的关键机制，配合“Never hardcode sensitive values”原则，实现敏感值的集中管理与轮换。

四、安全最佳实践

状态管理：始终使用远程状态（HCP Terraform backend）；
变量安全：敏感值使用工作区变量，绝不硬编码；
访问控制：实现适当的工作区权限与团队访问；
Plan 审查：apply 前总是审查 terraform plan；
资源标签：为成本分配与治理保持一致的标签。

这些原则与 instructions/terraform.instructions.md 的 Security 章节深度互补：该 instructions 还要求敏感变量标记sensitive = true以避免在 plan/apply 输出中泄露、将敏感信息存储于 Secrets Manager/SSM Parameter Store 等密钥服务、绝不将凭据/状态文件提交到版本控制（用.gitignore排除），并使用trivy、tfsec、checkov定期扫描配置漏洞。此外 terraform-iac-reviewer.agent.md 补充了 IAM 最小权限（无通配符*action）、默认开启静态与传输中加密、存储资源阻止公共访问等细化要求。

五、生成代码完成检查清单

在判定代码生成完成前，逐项核验：

所有必需文件齐全（main.tf、variables.tf、outputs.tf、README.md）；
最新 Provider/Module 版本已解析并记录；
根模块包含后端配置；
代码格式正确（2 空格缩进、=对齐）；
变量与输出按字母序排列；
使用描述性资源名称；
复杂逻辑有注释说明；
无硬编码密钥或敏感值；
README 包含用法示例；
已在 HCP Terraform 创建/验证工作区；
已执行初始 run 并审查 plan；
输入与资源的单元测试存在且通过。

最后一项“Unit tests for inputs and resources”直接对应 Agent 使命中的 Module Testing：使用 Terraform Test 编写.tftest.tf用例，覆盖正向与负向场景，且保证幂等可重复运行。

六、关键提醒（Always/ Never 纪律）

Always生成代码前搜索注册表；
Never硬编码敏感值——使用变量；
Always遵循格式规范（2 空格缩进、=对齐）；
Never未经审查 plan 就自动 apply；
Always未指定时使用最新 Provider 版本；
Always在注释中记录 Provider/Module 来源；
Always变量/输出按字母序排列；
Always使用描述性资源名称；
AlwaysREADME 包含用法示例；
Always部署前审查安全影响。

这十条可视为该 Agent 的“行为宪法”，与 terraform-iac-reviewer.agent.md 的 “Important Reminders”（总是先terraform plan再terraform apply、绝不提交状态文件、锁定 Provider/模块版本、提供已测试的回滚方案）形成一套完整的工程纪律。

七、在 awesome-copilot 生态中的定位与延伸

Terraform Agent 不是孤立的单点，而是 awesome-copilot Terraform 工程化 Agent 家族的一员，各角色职责互补：

Agent	角色定位
terraform.agent.md	通用 IaC 专家，MCP Server 驱动的 Registry + HCP Terraform 自动化
terraform-aws-planning.agent.md	AWS 场景的规划者，产出`.terraform-planning-files/INFRA.{goal}.md`
terraform-aws-implement.agent.md	AWS 场景的实施者，S3 + DynamoDB 状态、`terraform-aws-modules`优先
terraform-azure-implement.agent.md	Azure 场景的实施者，AVM 模块、ARM_SUBSCRIPTION_ID 约束
terraform-iac-reviewer.agent.md	IaC 审查者，状态安全、最小权限、漂移检测

配套的 instructions/terraform.instructions.md 以applyTo: '**/*.tf'方式对所有.tf文件生效，为 Agent 生成代码提供安全、模块化、可维护性、风格、文档与测试六维约定；docs/README.agents.md 则提供了一键安装入口。将本文所述 Agent 与 agents/terraform-azure-planning.agent.md、agents/azure-verified-modules-terraform.agent.md 等组合使用，即可构建从规划、实施、审查到 HCP Terraform 编排的完整 IaC 交付流水线。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考