huawei-cloud-terraform-generator

Huawei Cloud Terraform 生成器

1. 概述

此技能可将用户的基础设施目标转换为 Huawei Cloud 的 Terraform 配置。主要工作流如下：

1. 了解用户的实际部署意图
2. 确定应创建哪些资源
3. 确定是否应复用现有资源
4. 确认关键规格和依赖项
5. 根据目标区域的可用资源验证每项资源规格——先查询，再编写
6. 确保已安装 Terraform
7. 生成 Terraform 配置文件
8. 运行验证步骤并修复生成问题，直到 terraform plan 成功
9. 征求用户确认，并在获得批准后执行 terraform apply

此技能提供交互式工作流，由 Agent 引导用户配置凭据、验证计划，并在获得用户明确确认后执行 apply。

2. 先决条件

使用此技能前，请确保以下条件已满足：

1. Terraform — 已安装并位于 PATH 中，或可自动安装（参见 validation-workflow.md）
2. Provider 下载源 — 可访问 Huawei Cloud 镜像（参见 validation-workflow.md）
3. 目标区域 — 必须确定部署区域（例如 cn-north-4、cn-south-1）

3. 参数确认

生成 Terraform 前，先提出具体的资源计划供用户确认。计划应包括：

• 建议的资源规格
• 适用时可选的候选方案
• 创建新资源还是复用现有资源
• 仅在可靠来源中获取到价格信息时提供价格

有关不得捏造规格和价格的规则，请参见 reference/guardrails.md。

不要要求用户手动提供每个参数。相反：

1. 根据用户的目标推断可能的架构
2. 提出包含建议默认值的具体计划
3. 仅确认少数会实质影响正确性、成本或架构的决策

用户主要应确认建议方案，而不是自行构建完整的参数集。

4. 工作流

此技能分为九个阶段：

4.0 凭据处理（必须阅读）

AK/SK 凭据从环境变量 HW_ACCESS_KEY 和 HW_SECRET_KEY 中读取。对于临时/STS 凭据，Agent 必须从环境变量中读取 HW_SECURITY_TOKEN（或 HUAWEICLOUD_SECURITY_TOKEN），并将其作为 security_token 写入 terraform.tfvars。Provider 无法可靠地从环境变量中解析 security_token。如果未设置环境变量，则省略该项（永久 AK/SK 场景）。 执行任何依赖凭据的步骤（资源查询、terraform plan 等）之前，请阅读 reference/guardrails.md 中的完整规则。 如果 API 或 Terraform 调用因身份验证错误而失败：告知用户具体错误，并请用户在问题解决后确认，然后重试。不要指导用户如何配置凭据。

4.1 了解用户的真实目标

用户可能会直接描述某项资源，例如创建 ECS 实例；也可能会描述业务目标，例如部署网站或启动应用程序。
你必须首先根据用户的目标推断其预期的 Huawei Cloud 架构，而不能只看用户明确提到的资源名称。

4.2 确定资源集

根据用户的目标，确定：

• 需要创建哪些资源
• 可以复用哪些现有资源
• 资源之间存在哪些依赖关系

例如：

• 简单的公网网站可能需要 VPC、子网、安全组、ECS 和 EIP
• 托管数据库部署可能需要 VPC、子网、安全组和 RDS
• 可扩展的公网服务可能需要 VPC、子网、安全组、ECS 或 AS、ELB 以及公网访问

4.3 提出资源方案以供确认

生成 Terraform 之前，请按照“参数确认”部分中的规则，提出具体的资源方案供用户确认。

有关敏感信息处理规则，请参阅 reference/guardrails.md。

4.3.1 与用户确认安全组规则（关键）

必需的工作流程：

1. 根据用户的目标推断可能需要的端口（Web 服务器 → 80、443；SSH → 22；数据库 → 3306、5432）
2. 请用户确认端口：“需要开放哪些端口？推荐：80、443、22”
3. 根据用户确认的端口生成规则，而非使用默认规则

Terraform 生成：

# User confirmed: 80, 443, 22

resource "huaweicloud_networking_secgroup_rule" "http" {
  security_group_id = huaweicloud_networking_secgroup.main.id
  direction         = "ingress"
  ethertype         = "IPv4"
  port_range_min    = 80
  port_range_max    = 80
  protocol          = "tcp"
  remote_ip_prefix  = "0.0.0.0/0"
}

# ... similar for 443, 22 (always include ethertype = "IPv4")

# Always include egress
resource "huaweicloud_networking_secgroup_rule" "egress" {
  security_group_id = huaweicloud_networking_secgroup.main.id
  direction         = "egress"
  ethertype         = "IPv4"
  remote_ip_prefix  = "0.0.0.0/0"
}

禁止：

• ❌ 仅使用出站规则，不设置入站规则
• ❌ 未询问用户便使用硬编码的默认端口
• ❌ 生成与用户确认内容不符的规则

4.4 生成任何代码之前，验证资源是否可用

此步骤为必需步骤，绝不能跳过。查询失败并不意味着可以继续操作，而是必须解决的阻塞问题。

在编写任何 Terraform 代码之前，必须根据目标区域验证已确认方案中的每项资源规格。目标区域已在步骤 4.3 的已确认方案中确定；如果缺少区域信息，说明步骤 4.3 未完成，必须重新执行。没有理由不知道要部署到哪个区域。

1. 步骤 1 — 首先读取目标技能的 SKILL.md（切勿跳过）： 调用该技能之前，必须先读取文件 ../huawei-cloud-computing-query/SKILL.md。此文件说明了准确的调用格式、必需参数、参数格式，以及如何传入目标区域。未读取技能定义，就无法正确调用该技能。
2. 步骤 2 — 使用已确认的参数调用技能： 只有在读取技能定义后，才能使用确切的必需参数调用 huawei-cloud-computing-query 技能，并传入步骤 4.3 的已确认方案中的目标区域。确认已确认方案中的每项资源规格确实存在且在目标区域可用。任何无法确认的规格都不得出现在任何 .tf 文件中。
3. 禁止跨区域推断 — 某资源在区域 A 可用，并不意味着它在区域 B 也可用。始终针对目标区域重新查询。

禁止：

• ❌ 未先读取其 SKILL.md 就调用 huawei-cloud-computing-query 技能
• ❌ 猜测或编造技能调用参数
• ❌ 无法确认资源规格可用时仍继续生成 Terraform
• ❌ 假设资源可用性适用于其他区域

如果查询失败（环境错误、网络问题、SDK 崩溃）：

• 绝不能继续生成 Terraform。立即停止。
• 诊断并修复问题：调用 huawei-cloud-computing-query 技能的环境检查，验证凭据并检查网络。
• 重试查询。如果再次失败，修复后再次重试。
• 不存在“平稳降级”——未经验证的规格可能导致部署失败。
• 此步骤唯一可接受的结果是：(a) 确认所有规格均可用；或 (b) 确认某项规格不可用，并请用户选择其他规格。

此步骤的重要性： 将不可用的规格写入 main.tf，会生成一份能够通过 terraform validate、却在 terraform apply 时失败的配置。这是最糟糕的一类错误，因为它要等数分钟后才会暴露。

修改现有 Terraform 时（用户要求更改规格、切换区域、使用其他实例类型等）：编辑任何 .tf 文件之前，必须针对新区域中的新规格重新运行可用性查询。不要假设先前查询的结果仍然适用。

4.5 确认后生成 Terraform

关键：生成前，必须先阅读第 8.1 节映射表中的相关参考文档。

用户确认资源方案后，按照规定的结构和样式规则生成 Terraform 文件。

有关详细的文件结构和内容规则，请参阅 reference/terraform-generation-guide.md。

**关键：**生成所有必需文件（providers.tf、variables.tf、main.tf、terraform.tfvars、README.md），并在继续之前确认这些文件均已存在。

4.6 验证凭证配置

继续验证之前，确认已通过环境变量配置华为云凭证。

有关 AK/SK 处理规则，请参阅 reference/guardrails.md。

4.6.1 配置用于下载 provider 的华为云镜像

运行 terraform init 之前，先配置华为云镜像，以避免从 Terraform 官方注册表下载缓慢。 请勿先尝试从官方注册表下载。始终使用华为云镜像。

步骤：

1. 检查本地是否存在 provider 缓存（位置请参阅 validation-workflow.md）
2. 如果缓存存在且版本 >= 1.90.0，则跳过下载
3. 如果需要下载，在项目目录中创建 .tfrc 文件：

   provider_installation {
     network_mirror {
       url = "https://mirrors.huaweicloud.com/terraform/"
       include = ["registry.terraform.io/huaweicloud/*"]
     }
   }
   

4. 将 TF_CLI_CONFIG_FILE 环境变量设为 .tfrc 文件路径
5. **每条 terraform init 命令都必须在同一命令行中包含 TF_CLI_CONFIG_FILE。严禁在未设置此环境变量的情况下直接运行 terraform init。**示例：

   export TF_CLI_CONFIG_FILE="/path/to/project/.tfrc" && terraform init -upgrade
   

4.7 验证并修复生成的配置

按顺序运行验证：terraform fmt -recursive → terraform init → terraform validate → terraform plan

如果任何步骤失败，请检查错误、修复配置并重试，直到 terraform plan 成功。

有关详细的验证步骤，请参阅 reference/validation-workflow.md。

4.8 显示成本估算（关键——不得跳过）

此步骤为强制要求，必须在 terraform plan 成功后立即执行，并且必须在任何确认对话框或 terraform apply 之前完成。跳过此步骤属于严重违规。

成本显示格式（填写计划中的实际资源）：

💰 费用预估

即将创建的资源：
- [资源类型] ([规格]): [预估费用]
- [资源类型] ([规格]): [预估费用]
- ...

预估合计: [总费用]

📌 华为云价格计算器: https://www.huaweicloud.com/pricing.html#/calculator

必需内容（必须全部包含）：

• 资源列表及规格（来自已确认的方案）
• 每项资源的月度预估费用（可使用范围）
• 预估总费用
• 华为云价格计算器链接（固定 URL）

**如果无法估算费用：**仍须列出该资源，并标注“费用请参考价格计算器”——不得从列表中省略该资源。

**验证：**继续执行第 4.9 步之前，确认已输出上述所有必需内容。若有任何内容缺失，请暂停并补充。

4.9 经用户确认后执行 terraform apply

显示成本估算后，弹出确认对话框，请用户确认后再执行 apply。

有关用户确认工作流的规则，请参阅 reference/guardrails.md。

4.10 apply 错误修复循环

如果 terraform apply 失败，请检查错误、修复配置、重新运行 terraform plan，然后再次执行 terraform apply。重复此过程，直到成功。

4.11 apply 后验证资源

terraform apply 成功后，验证已部署资源是否与已确认的方案一致。如果发现差异，请报告并修复。

5. 防护规则

有关详细的防护规则，请参阅 reference/guardrails.md。

关键原则：

• 不得编造规格、价格或资源信息
• 执行 terraform apply 前必须获得用户明确确认
• 不得索取敏感信息
• 未先阅读所引用技能的 SKILL.md 文件，不得调用该技能

6. Terraform 生成规则

用户确认资源计划后，生成精简、有效且符合已确认方案的 Terraform。

有关文件结构、内容规则、数据源用法和变量设计的详细指导，请参阅 reference/terraform-generation-guide.md。

核心原则：

1. 从已确认的资源计划着手
2. 遵循最小可行配置原则
3. 优先确保 Terraform 有效，避免不必要的灵活性
4. 相关时优先使用现有程序包引用

7. 环境准备与验证

有关确保 Terraform 可用、下载 provider （通过华为云镜像）、验证顺序、身份验证和修复流程的详细指导，请参阅 reference/validation-workflow.md。

8. 参考资料用法与模板指导

相关时，请使用技能程序包中的参考资料、模板、示例和辅助工具。

8.1 相关时使用现有参考资料

生成前必须查阅以下参考资料：

资源	参考文档	关键模式
通用规则	reference/guardrails.md + reference/terraform-generation-guide.md	自动生成密码，不向用户索要敏感信息
安全组	reference/VPC-best-practices/VPC-best-practices.md →“部署安全组”	ethertype 为必填项
使用 EIP 的 ECS	reference/ECS-best-practices/Deploy-Instance-with-EIP-best-practices.md	使用 huaweicloud_compute_eip_associate，public_ip = .address
VPC/子网	reference/VPC-best-practices/VPC-best-practices.md →“部署基础网络”	VPC/子网结构
RDS	reference/RDS-best-practices/RDS-best-practices.md	数据库 + 网络配置

8.2 以现有示例和模板为起点

如果程序包中包含与目标场景接近的示例，请以此为起点。保留有用的结构，根据已确认的计划进行调整，并移除不需要的资源。

8.3 将用户目标与相关参考资料对应起来

将业务目标映射到服务参考资料（例如，“部署网站” → VPC + ECS + EIP，“托管数据库” → RDS + 网络）。

8.4 利用参考资料改进方案，而不是过度构建

最终 Terraform 应符合用户确认的计划，并遵循最小可行配置原则。

8.5 不要盲目依赖模板

务必确认模板符合已确认的计划，并通过常规验证流程进行验证。

9. 质量检查清单

定稿前，请确保：

• 生成的 Terraform 符合已确认的资源计划
• 已生成并验证所有 5 个必需文件（providers.tf、variables.tf、main.tf、terraform.tfvars、README.md）
• 未向用户索要任何敏感信息
• 验证已进行到 terraform plan 阶段，或已清楚说明阻碍
• 已在用户确认之前显示成本估算（步骤 4.8 — 不得跳过）
• 成本估算包含所有必需内容：资源列表、规格、各资源的预估费用、总费用、定价计算器链接
• 已通过确认对话框征求用户同意，然后再执行 terraform apply
• 仅在用户明确确认后才执行了 terraform apply（或用户拒绝执行）