terraform-infra

Terraform 基础设施技能

安装

该技能会调用 Terraform CLI。请安装：

• macOS：brew tap hashicorp/tap && brew install hashicorp/tap/terraform
• Windows：choco install terraform 或从 HashiCorp 下载
• Linux (apt)：添加 HashiCorp 软件源，然后运行 sudo apt update && sudo apt install terraform（参见 HashiCorp 安装说明）

验证：terraform --version

速查表与最佳实践

工作流： terraform init → terraform fmt → terraform validate → terraform plan -out=tfplan → 审查 → terraform apply tfplan。使用 terraform show tfplan 进行检查。

技巧： 务必先运行 plan，再运行 apply；切勿盲目执行 apply。团队协作时使用远程状态（例如 S3 + 锁）。只有在 CI 中且计划已审核时，才优先使用 -auto-approve。使用 terraform state list 和 terraform state show <resource> 进行调试。在流水线中使用服务账户 / 工作负载身份；避免使用静态密钥。

认证与培训

HashiCorp Terraform Associate (004)： IaC 概念、Terraform 基础知识、状态、模块、Terraform Cloud。学习路径。技能数据： init → fmt → validate → plan -out → apply；远程状态；禁止盲目执行 apply。

钩子与工作流

建议的钩子： Apply 前：运行 terraform plan -out=tfplan，并设置审核门禁。CI：仅在计划获批后执行 apply。主要与 devops 搭配使用。

工作流： 主要与 devops 搭配使用。流程：init → plan → 审查 → apply；使用状态命令进行调试。流水线集成请参见 ci-cd-implementation-rule。

概述

与原始 Terraform MCP 服务相比，可节省 90% 以上的上下文。包含基础设施操作所需的关键安全控制。

要求

• Terraform CLI（v1.0+）
• 已配置云服务提供商凭据
• 包含 .tf 文件的工作目录

工具（渐进式披露）

规划与验证

工具	描述	确认
plan	生成 terraform 计划	否
validate	验证配置	否
fmt	格式化 terraform 文件	否

状态操作

工具	描述	确认
show	显示当前状态	否
list	列出状态资源	否
state-mv	移动状态中的资源	是

工作区操作

工具	描述	确认
workspace-list	列出工作区	否
workspace-select	选择工作区	否
workspace-new	创建工作区	是

执行（⚠️ 危险）

工具	描述	确认
apply	应用更改	必需

禁用的操作

工具	状态
destroy	已禁用
state-rm	已禁用

快速参考

# Initialize
terraform init

# Plan changes
terraform plan -out=tfplan

# Validate
terraform validate

# Apply (requires -auto-approve for automation)
terraform apply tfplan

配置

• 工作目录：必须包含 terraform 文件
• TFVAR*：通过环境变量设置变量值
• TF_WORKSPACE：当前工作区

安全控制

⚠️ terraform apply 始终需要确认 ⚠️ terraform destroy 默认已禁用 ⚠️ 修改状态需要确认 ⚠️ 执行 apply 前请审查计划输出

Agent 集成

• devops（主要）：基础设施管理
• architect（次要）：基础设施设计
• cloud-integrator（次要）：云资源配置

故障排除

问题	解决方案
Init 失败	检查提供商凭据
状态已锁定	检查是否有其他操作正在进行
Plan 失败	仔细检查错误输出

模块开发

创建可复用模块

按照 HashiCorp 约定组织模块：

modules/
  vpc/
    main.tf          # Resource definitions
    variables.tf     # Input variables
    outputs.tf       # Output values
    versions.tf      # Required provider versions
    README.md        # Module documentation

模块最佳实践

实践	描述
单一职责	每个模块管理一个逻辑资源组
类型化变量	对所有变量使用 type 约束
验证块	为输入约束添加 validation {}
敏感输出	使用 sensitive = true 标记机密信息
版本约束	固定模块源版本

模块源模式

# Local module
module "vpc" {
  source = "./modules/vpc"
}

# Terraform Registry
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"
}

# Git source (pinned tag)
module "vpc" {
  source = "git::https://github.com/org/modules.git//vpc?ref=v1.2.0"
}

Provider 开发模式

自定义 Provider 框架

package provider

import (
    "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
)

func Provider() *schema.Provider {
    return &schema.Provider{
        Schema: map[string]*schema.Schema{
            "api_key": {
                Type:        schema.TypeString,
                Required:    true,
                Sensitive:   true,
                DefaultFunc: schema.EnvDefaultFunc("API_KEY", nil),
            },
        },
        ResourcesMap: map[string]*schema.Resource{
            "myservice_resource": resourceMyServiceResource(),
        },
    }
}

测试模块

# Validate module syntax
cd modules/vpc && terraform validate

# Run module tests (Terraform 1.6+)
terraform test

# Plan with module
terraform plan -var-file=examples/basic.tfvars

铁律

1. 始终运行 terraform plan 并在执行 terraform apply 前检查输出
2. 绝不在 .tf 文件中硬编码凭据或机密信息——使用机密管理器（AWS Secrets Manager、Azure Key Vault、HashiCorp Vault）
3. 始终使用带加密和状态锁定的远程状态，以防止并发修改
4. 绝不直接编辑状态文件——只能使用 terraform state 命令
5. 始终固定 Provider 和模块版本，以确保基础设施部署完全可复现

反模式

反模式	失败原因	正确做法
在 .tf 文件中硬编码凭据	机密信息暴露在 VCS 中，导致合规失败	使用由机密管理器后端支持的变量
未启用状态锁定	并发 apply 会破坏状态	启用后端锁定（S3+DynamoDB、Azure Blob、GCS）
未检查计划就运行 terraform apply	意外删除或重新创建资源	始终先运行 plan，检查差异，然后再运行 apply
Provider 和模块未指定版本	构建无法复现，且可能发生破坏性变更	固定版本：version = "~> 4.0"
资源未添加标签	成本无法追踪，且可能导致合规失败	为所有资源添加 env、owner、cost-center 标签

记忆协议（强制）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设任务可能中断：如果没有记录在记忆中，就等于没有发生。