terraform-module 快速入门

用 Skill 帮 AI 写”能上生产”的 Terraform 模块——不是堆资源块,而是带变量、输出、状态管理的完整模块。

这是什么?解决什么问题?

terraform-module 是一个归属于 Anthropic 生态系(skills 套件)的运维类 Skill,聚焦在”用基础设施即代码(IaC)描述云资源”这件具体的事上。它要解决的是 Terraform 使用过程中最普遍的几个痛点:第一,新手写出来的 .tf 文件像一锅粥,变量、locals、resource、output 全部平铺,加一个新参数要改三处;第二,模块复用性差,每个项目都从零写,代码 copy-paste 后改两行就开始”漂移”;第三,State 文件管理混乱,terraform plan 看到一堆不明就里的 diff,真上生产时心惊胆战。

这个 Skill 的核心思路是:让 AI 在生成 Terraform 内容时,强制遵守”模块化结构 + 输入输出契约 + State 后端约定”。具体来说,它引导 AI 写出符合 HashiCorp 官方推荐结构的模块(根目录 main.tf / variables.tf / outputs.tf / versions.tf 分文件),要求每个模块有清晰的 variable 描述、output 用途,以及版本约束(required_version 和 required_providers)。对 State,会引导使用 S3 + DynamoDB / GCS / Terraform Cloud 等远程后端,而不是本地 terraform.tfstate。

在生态归属上,它属于 Anthropic Skills 集合中偏”工程化输出”的子集,设计上可与 mcp-builder、skill-creator 等 Skill 配合。开源上常被收录在 awesome-agent-skills 一类的索引仓库里,采用 Apache-2.0 协议,可在 Claude Code 中加载使用。

准备工作

1. Terraform 1.5+:HashiCorp 官方建议使用 1.5 或以上版本,本 Skill 生成的代码会用到 required_providers 等较新语法。安装参考 https://developer.hashicorp.com/terraform/install。
2. 本地已配置好云厂商 CLI:至少配置好 AWS CLI / gcloud / azcli 其中之一,并通过 aws configure、gcloud auth login 等命令登录。
3. 一个空项目目录:不要直接在生产 Terraform 目录里试,先建一个 terraform-lab/ 练手。
4. Claude Code 或兼容 Agent:本 Skill 是 Agent Skill,需要宿主(Claude Code)能执行 shell + 编辑文件。
5. 一个 State 后端(可选):生产用建议先准备好 S3 bucket + DynamoDB 表(或对应云厂商的等价物);练手阶段可以用本地 State。

3 步快速上手

第 1 步:安装 Skill

通过 awesome-agent-skills 索引或 Anthropic 官方 Skills 仓库加载本 Skill。常见做法是把 SKILL.md 放到 Agent 能识别的目录:

git clone https://github.com/JackyST0/awesome-agent-skills.git ~/awesome-agent-skills
mkdir -p ~/.claude/skills
ln -s ~/awesome-agent-skills/skills/terraform-module ~/.claude/skills/terraform-module

或者从 Anthropic 官方 skills 仓库 https://github.com/anthropics/skills 找到 terraform-module 子目录,按相同方式软链接。

第 2 步:验证安装

打开 Claude Code,新开对话,问:

列出已加载的 Skill,看看有没有 terraform-module。

Agent 应能回读 SKILL.md 的 frontmatter 并简述它的核心规则(模块结构、变量约束、State 后端等)。同时可在 shell 里验证 Terraform 可用:

terraform version

应输出 Terraform 1.5+ 的版本号。

第 3 步:用 Skill 跑第一个任务

在 terraform-lab/ 目录下启动 Claude Code,输入:

用 terraform-module 流程,生成一个 AWS S3 静态网站托管模块,要求:输入 bucket 名称和环境(dev/prod),输出网站 endpoint URL,启用版本控制和访问日志,dev 环境强制关闭日志 bucket 的公开访问块。

Agent 会按 SKILL.md 自动写出 4 个文件:

• variables.tf:定义 bucket_name、environment、log_bucket_name 等。
• main.tf:写 aws_s3_bucket、aws_s3_bucket_versioning、aws_s3_bucket_public_access_block 等资源。
• outputs.tf:输出 website_endpoint。
• versions.tf:required_version >= 1.5.0、required_providers 锁定 AWS Provider 版本。

然后引导你跑:

terraform init
terraform plan
terraform apply

常见踩坑

1. 变量没描述、没类型、没默认值:variable "foo" {} 这种空壳变量是反模式,Skill 会反复要求补 description、type、default,生产环境必踩坑。
2. State 留在本地:本地 terraform.tfstate 适合单兵,团队/多环境立刻崩。本 Skill 强制推荐远端后端,即使你”先跑通再说”,也要在第一次 commit 前切到 S3/GCS。
3. Provider 版本不锁定:provider "aws" {} 不带版本,几个月后 terraform init 拉到新版本 Provider,plan 出现一片意料外 diff。Skill 强调用 required_providers 锁定。
4. 变量命名不区分环境:environment / env / stage 混用,模块复用困难。Skill 倾向统一 environment 且取值为 ["dev","staging","prod"]。
5. output 缺失:写完资源就结束,不下游消费。Skill 要求每个模块至少输出 1 个核心值(例 S3 模块输出 arn 和 website_endpoint)。
6. 直接在 main.tf 里堆条件逻辑:count、for_each 满天飞,应拆为多个 module,Skill 会引导用 module 嵌套组合,而不是单文件巨型 if/else。

初级用法

• 写第一个 S3 模块:跑一次上面的”3 步上手”,熟悉 variables.tf / main.tf / outputs.tf 三件套结构。
• 复用模块:在 root module 里 module "site" { source = "./modules/s3-static-site" bucket_name = "my-site-dev" environment = "dev" },通过 terraform output 拿到 website_endpoint。
• 多环境切换:用 terraform workspace 或独立 backend 配置(.tfbackend 文件)区分 dev/prod,Skill 推荐的写法是后者——避免 workspace 在远端后端下的”看似隔离实则共享状态”陷阱。

高级玩法

• 模块 Registry:把内部模块推到私有 Git 仓库,通过 source = "git::https://git.example.com/iac-modules/s3-static-site.git?ref=v1.2.0" 引用,带 tag 管理版本。
• CI 配合 + Atlantis / Terraform Cloud:Skill 不替代 CI,但生成的模块结构天然适合接入 Atlantis 或 Terraform Cloud 的”PR 计划预览”流程。
• Policy as Code 联用:和 sentinel(HashiCorp)或 opa(Open Policy Agent)联用,在 plan 阶段挡掉”未启用加密""日志未开启”等违规配置。
• 多云抽象:对同时跑 AWS / GCP / Azure 的团队,可以让 AI 在 Skill 引导下生成”参数化 provider”的统一模块,内部条件选择具体资源类型。

小技巧

1. 给每个模块都加 README.md,Skill 引导 AI 写模块时一并生成,里面含输入输出示例,降低团队上手成本。
2. 用 pre-commit 框架 + terraform fmt / terraform validate / tflint / tfsec 钩子,Skill 生成的代码通常能直接通过这些检查。
3. 永远不要在公共仓库里 hardcode AKID/SK——Skill 会反复提示变量化,如果发现 AI 写死了密钥,立即拒绝合并。
4. 把 terraform.tfstate 加入 .gitignore,但同时把 *.tfstate.backup 也加入,避免误提交旧 state。
5. terraform plan -out=tfplan 后再用 terraform apply tfplan 执行,可避免”plan 时看到的 diff 和 apply 时不一致”。

参考链接

• awesome-agent-skills 索引仓库:https://github.com/JackyST0/awesome-agent-skills
• Anthropic 官方 Skills 仓库:https://github.com/anthropics/skills
• Terraform 官方”模块开发”指南:https://developer.hashicorp.com/terraform/language/modules/develop
• HashiCorp 官方”标准模块结构”:https://developer.hashicorp.com/terraform/language/modules#standard-module-structure
• AWS Provider 文档:https://registry.terraform.io/providers/hashicorp/aws/latest/docs

写在最后:Skill 是”代码风格约束器”

terraform-module 这个 Skill 本质上是一个”代码风格约束器”——它不会替你做架构决策,也不会替你写资源,但它会保证 AI 写出来的 Terraform 是”可读、可审、可复用”的标准结构。对一个刚接触 IaC 的工程师,Skill 的最大价值是帮你在一开始就养成正确的工程习惯:每个模块有 input/output、有版本约束、有远端 State。对一个资深 SRE,Skill 的价值是让团队产出的 IaC 风格统一,新人接手不用从零理解。最后要强调的是:Skill 生成的代码依然是 AI 写的,正式 apply 之前必须自己 review 一遍,这是 IaC 永远不能跳过的环节。

补充一个实际工程经验:第一次用本 Skill 跑大项目时,先在”最简单的一个 S3 bucket 模块”上试水,熟悉完 variables.tf / main.tf / outputs.tf 的文件切分习惯后,再让 AI 帮你做 VPC、RDS、ECS 这种复杂模块。复杂模块一次跑通难度大,拆成”先 VCP、再子网、再安全组、再 RDS”的串联模块组合,反而比一次到位更稳。

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。