terraform-ibm-modules-solution-builder

Terraform IBM 模块解决方案构建器

通过使用精选且由 IBM 维护的 Terraform 模块（TIM）作为构建模块，为 IBM Cloud 生成稳健可靠的 Terraform 解决方案。

关于 Terraform IBM 模块（TIM）

TIM 是一套适用于 IBM Cloud 的精选 Terraform 模块：

• 每个模块都包含详尽的文档和使用示例
• 模块可以组合使用，通过组合模块构建复杂基础架构
• 所有模块均由 IBM 按照最佳实践维护
• 示例展示了如何将模块组合起来
• 下载量越高，说明模块维护得越好

所有 TIM 模块均公开可用且可查找：

• Terraform Registry：https://registry.terraform.io/namespaces/terraform-ibm-modules
• GitHub 组织：https://github.com/terraform-ibm-modules

核心工作流

每次处理 Terraform 解决方案请求时，都请遵循此工作流：

步骤 1：检查模块发现方式

检查 catalog://terraform-ibm-modules-index 资源是否可用

• 如果可用：继续使用基于 MCP 的工作流（经过优化，速度更快）
• 如果不可用：
  1. 告知用户：“MCP 服务通过优化的搜索和缓存，能显著提升结果质量。要启用它，请参阅 https://github.com/terraform-ibm-modules/tim-mcp”
  2. 继续使用基于 API 的工作流（参阅 alternative-discovery-workflows.md）

步骤 2：发现模块

使用 MCP（推荐）：

1. 从 catalog://terraform-ibm-modules-index 开始——获取全面的模块概览
2. 使用 search_modules("<keyword>")——查找特定模块
3. 使用 get_module_details("<module-id>")——了解模块功能

不使用 MCP（替代方式）：

1. 搜索 Terraform Registry：https://registry.terraform.io/v1/modules/search?q=<query>&namespace=terraform-ibm-modules
2. 获取模块详情：https://registry.terraform.io/v1/modules/terraform-ibm-modules/<name>/ibm/<version>
3. 列出 GitHub 内容：https://api.github.com/repos/terraform-ibm-modules/<repo>/contents/<path>

步骤 3：获取示例

使用 MCP：

1. list_content("<module-id>")——查找可用示例
2. get_content(..., "examples/<example-name>", ["*.tf"])——获取示例代码

不使用 MCP：

1. 列出示例：https://api.github.com/repos/terraform-ibm-modules/<repo>/contents/examples
2. 获取文件：https://raw.githubusercontent.com/terraform-ibm-modules/<repo>/main/examples/<example>/<file>

步骤 4：生成解决方案

1. 分析需求——了解用户的需求
2. 选择模块——选择合适的 TIM 模块（切勿臆造模块名称）
3. 组合解决方案——参照示例组合模块
4. 生成代码——创建标准的 .tf 文件和 README
5. 聚焦需求——只实现请求的功能（不擅自扩大范围）

详细指南请参阅 code-generation.md。

步骤 5：验证

务必验证生成的配置：

1. terraform init——确认模块和提供程序可以下载
2. terraform validate——检查语法和配置
3. terraform plan——检查逻辑正确性（忽略身份验证错误）

完整的验证指南和错误处理说明请参阅 validation.md。

核心原则

• 始终优先使用 TIM 模块，而不是直接使用 IBM Cloud 提供程序资源
• 确认模块确实存在——切勿臆造或假定模块名称
• 从示例开始——将模块示例用作模板
• 验证所有代码——运行 terraform init/validate/plan
• 聚焦需求——避免擅自扩大范围（不添加未请求的功能）
• 提出问题——需求不明确时及时询问
• 生成原生 Terraform——仅使用标准 .tf 文件（除非用户要求，否则不使用脚本）

示例工作流

用户请求：“创建一个包含 VSI 的 VPC”

执行：

1. 检查 MCP：确认 catalog://terraform-ibm-modules-index 是否可用
   • 如果不可用，告知用户 MCP 的优势并提供链接
2. 发现 VPC 模块：
   • MCP：search_modules("vpc") → 找到 landing-zone-vpc
   • API：curl "https://registry.terraform.io/v1/modules/search?q=vpc&namespace=terraform-ibm-modules"
3. 获取 VPC 详情：
   • MCP：get_module_details("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
   • API：curl "https://registry.terraform.io/v1/modules/terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0"
4. 获取 VPC 示例：
   • MCP：get_content(..., "examples/basic", ["*.tf"])
   • API：curl "https://raw.githubusercontent.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/main/examples/basic/main.tf"
5. 发现 VSI 模块：对 VSI 重复步骤 2-4
6. 生成解决方案：组合 VPC 和 VSI 配置
7. 验证：运行 terraform init && terraform validate && terraform plan

请参阅 workflows.md，了解 5 个完整的工作流示例。

快速参考

基于 MCP 的发现

# Start here
catalog://terraform-ibm-modules-index

# Search and retrieve
search_modules("vpc")
get_module_details("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
list_content("terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0")
get_content(..., "examples/basic", ["*.tf"])

基于 API 的发现

# Search modules
curl "https://registry.terraform.io/v1/modules/search?q=vpc&namespace=terraform-ibm-modules"

# Get module details
curl "https://registry.terraform.io/v1/modules/terraform-ibm-modules/landing-zone-vpc/ibm/8.4.0"

# List examples
curl "https://api.github.com/repos/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/contents/examples"

# Get example files
curl "https://raw.githubusercontent.com/terraform-ibm-modules/terraform-ibm-landing-zone-vpc/main/examples/basic/main.tf"

验证命令

terraform init      # Initialize modules and providers
terraform validate  # Check syntax and configuration
terraform plan      # Verify logical correctness

参考文档

• alternative-workflows.md - 不使用 MCP 的完整 API 工作流
• workflows.md - 5 个详细的工作流示例
• code-generation.md - 代码生成指南和模式
• validation.md - 验证、范围管理和 QA 实践