name: terraform-skilldescription: “Terraform infrastructure as code best practices”risk: safesource: “https://github.com/antonbabenko/terraform-skill”date_added: “2026-02-27”Claude 的 Terraform 技能涵盖测试、模块、CI/CD 和生产模式的全面 Terraform 和 OpenTofu 指导。基于 terraform-best-practices.com 和企业经验。何时使用此技能在以下情况激活此技能创建新的 Terraform 或 OpenTofu 配置或模块为 IaC 代码设置测试基础设施在测试方法之间做决策validate、plan、框架构建多环境部署结构为基础设施即代码实现 CI/CD审查或重构现有的 Terraform/OpenTofu 项目在模块模式或状态管理方法之间做选择不要将此技能用于基本的 Terraform/OpenTofu 语法问题Claude 已了解提供程序特定的 API 参考链接到文档即可与 Terraform/OpenTofu 无关的云平台问题核心原则1. 代码结构理念模块层次类型何时使用范围资源模块单一逻辑组的关联资源VPC 子网、安全组 规则基础设施模块为实现某目的而收集的资源模块同一区域/账户中的多个资源模块组合完整的基础设施跨多个区域/账户层次结构资源 → 资源模块 → 基础设施模块 → 组合目录结构environments/ # Environment-specific configurations ├── prod/ ├── staging/ └── dev/ modules/ # Reusable modules ├── networking/ ├── compute/ └── data/ examples/ # Module usage examples (also serve as tests) ├── complete/ └── minimal/来自 terraform-best-practices.com 的关键原则将环境prod、staging与模块可重用组件分开使用examples/既作为文档又作为集成测试夹具保持模块小而专注单一职责有关详细的模块架构请参阅代码模式模块类型与层次结构2. 命名约定资源# Good: Descriptive, contextual resource aws_instance web_server { } resource aws_s3_bucket application_logs { } # Good: this for singleton resources (only one of that type) resource aws_vpc this { } resource aws_security_group this { } # Avoid: Generic names for non-singletons resource aws_instance main { } resource aws_s3_bucket bucket { }单例资源当你的模块只创建该类型的一个资源时使用this✅ 要resource aws_vpc this {} # Module creates one VPC resource aws_security_group this {} # Module creates one SG❌ 不要对多个资源使用 “this”resource aws_subnet this {} # If creating multiple subnets创建同类型的多个资源时使用描述性名称。变量# Prefix with context when needed var.vpc_cidr_block # Not just cidr var.database_instance_class # Not just instance_class文件main.tf- 主要资源variables.tf- 输入变量outputs.tf- 输出值versions.tf- 提供程序版本data.tf- 数据源可选测试策略框架决策矩阵选择哪种测试方法你的情况推荐方法工具成本快速语法检查静态分析terraform validate、fmt免费提交前验证静态 代码检查validate、tflint、trivy、checkov免费Terraform 1.6简单逻辑原生测试框架内置terraform test免费-低1.6 之前或有 Go 专长集成测试Terratest低-中安全/合规重点策略即代码OPA、Sentinel免费成本敏感工作流Mock 提供程序1.7原生测试 模拟免费多云、复杂完整集成Terratest 真实基础设施中-高基础设施测试金字塔/\ / \ End-to-End Tests (Expensive) /____\ - Full environment deployment / \ - Production-like setup /________\ / \ Integration Tests (Moderate) /____________\ - Module testing in isolation / \ - Real resources in test account /________________\ Static Analysis (Cheap) - validate, fmt, lint - Security scanning原生测试最佳实践1.6在生成测试代码之前使用 Terraform MCP 验证模式Search provider docs → Get resource schema → Identify block types选择正确的命令模式command plan- 快速用于输入验证command apply- 计算值和集合类型块所必需正确处理集合类型块不能用[0]索引使用for表达式进行迭代或者使用command apply来具体化常见模式S3 加密规则集合使用 for 表达式生命周期转换集合使用 for 表达式IAM 策略语句集合使用 for 表达式有关详细的测试指南请参阅测试框架指南- 深入探讨静态分析、原生测试和 Terratest快速参考- 决策流程图和命令速查表代码结构标准资源块排序保持一致的严格排序count或for_each放在最前面其后空一行其他参数tags作为最后一个实际参数depends_on放在 tags 之后如果需要lifecycle放在最末尾如果需要# ✅ GOOD - Correct ordering resource aws_nat_gateway this { count var.create_nat_gateway ? 1 : 0 allocation_id aws_eip.this[0].id subnet_id aws_subnet.public[0].id tags { Name ${var.name}-nat } depends_on [aws_internet_gateway.this] lifecycle { create_before_destroy true } }变量块排序description始终必需typedefaultvalidationnullable当设为 false 时variable environment { description Environment name for resource tagging type string default dev validation { condition contains([dev, staging, prod], var.environment) error_message Environment must be one of: dev, staging, prod. } nullable false }有关完整的结构指南请参阅代码模式块排序与结构Count 与 For_Each何时使用哪个快速决策指南场景使用原因布尔条件创建或不创建count condition ? 1 : 0简单的开/关切换简单的数字复制count 3固定数量的相同资源项目可能被重排/移除for_each toset(list)稳定的资源地址按键引用for_each map对资源的命名访问多个命名资源for_each更好的可维护性常见模式布尔条件# ✅ GOOD - Boolean condition resource aws_nat_gateway this { count var.create_nat_gateway ? 1 : 0 # ... }使用 for_each 实现稳定寻址# ✅ GOOD - Removing us-east-1b only affects that subnet resource aws_subnet private { for_each toset(var.availability_zones) availability_zone each.key # ... } # ❌ BAD - Removing middle AZ recreates all subsequent subnets resource aws_subnet private { count length(var.availability_zones) availability_zone var.availability_zones[count.index] # ... }有关迁移指南和详细示例请参阅代码模式Count 与 For_Each使用 Locals 进行依赖管理使用 locals 确保正确的资源删除顺序# Problem: Subnets might be deleted after CIDR blocks, causing errors # Solution: Use try() in locals to hint deletion order locals { # References secondary CIDR first, falling back to VPC # Forces Terraform to delete subnets before CIDR association vpc_id try( aws_vpc_ipv4_cidr_block_association.this[0].vpc_id, aws_vpc.this.id, ) } resource aws_vpc this { cidr_block 10.0.0.0/16 } resource aws_vpc_ipv4_cidr_block_association this { count var.add_secondary_cidr ? 1 : 0 vpc_id aws_vpc.this.id cidr_block 10.1.0.0/16 } resource aws_subnet public { vpc_id local.vpc_id # Uses local, not direct reference cidr_block 10.1.0.0/24 }为什么这很重要防止销毁基础设施时的删除错误无需显式depends_on即可确保正确的依赖顺序对于带辅助 CIDR 块的 VPC 配置特别有用有关详细示例请参阅代码模式用于依赖管理的 Locals模块开发标准模块结构my-module/ ├── README.md # Usage documentation ├── main.tf # Primary resources ├── variables.tf # Input variables with descriptions ├── outputs.tf # Output values ├── versions.tf # Provider version constraints ├── examples/ │ ├── minimal/ # Minimal working example │ └── complete/ # Full-featured example └── tests/ # Test files └── module_test.tftest.hcl # Or .go最佳实践摘要变量✅ 始终包含description✅ 使用显式type约束✅ 在适当的地方提供合理的default值✅ 为复杂约束添加validation块✅ 对机密使用sensitive true输出✅ 始终包含description✅ 用sensitive true标记敏感输出✅ 考虑为相关值返回对象✅ 记录消费者应如何使用每个输出有关详细的模块模式请参阅模块模式指南- 变量最佳实践、输出设计、✅ 要与 ❌ 不要模式快速参考- 资源命名、变量命名、文件组织CI/CD 集成推荐的工作流阶段验证- 格式检查 语法验证 代码检查测试- 运行自动化测试原生或 Terratest计划- 生成并审查执行计划应用- 执行更改生产环境需审批成本优化策略对 PR 验证使用模拟免费仅在 main 分支上运行集成测试受控成本实现自动清理防止孤立资源标记所有测试资源跟踪支出有关完整的 CI/CD 模板请参阅CI/CD 工作流指南- GitHub Actions、GitLab CI、Atlantis 集成、成本优化快速参考- 常见 CI/CD 问题和解决方案安全与合规基本安全检查# Static security scanningtrivy config.checkov-d.要避免的常见问题❌不要在变量中存储机密使用默认 VPC跳过加密将安全组开放到 0.0.0.0/0✅要使用 AWS Secrets Manager / Parameter Store创建专用 VPC启用静态加密使用最小权限安全组有关详细的安全指导请参阅安全与合规指南- Trivy/Checkov 集成、机密管理、状态文件安全、合规测试版本管理版本约束语法version 5.0.0 # Exact (avoid - inflexible) version ~ 5.0 # Recommended: 5.0.x only version 5.0 # Minimum (risky - breaking changes)按组件的策略组件策略示例Terraform固定次要版本required_version ~ 1.9提供程序固定主版本version ~ 5.0模块生产固定确切版本version 5.1.2模块开发允许补丁更新version ~ 5.1更新工作流# Lock versions initiallyterraform init# Creates .terraform.lock.hcl# Update to latest within constraintsterraform init-upgrade# Updates providers# Review and testterraform plan有关详细的版本管理请参阅代码模式版本管理现代 Terraform 功能1.0各版本功能可用性功能版本用例try()函数0.13安全回退替代element(concat())nullable false1.1防止变量中出现空值moved块1.1无需销毁/重建即可重构带默认值的optional()1.3可选对象属性原生测试1.6内置测试框架Mock 提供程序1.7零成本单元测试提供程序函数1.8提供程序特定的数据转换跨变量验证1.9验证变量之间的关系只写参数1.11机密永不存储在状态中快速示例# try() - Safe fallbacks (0.13) output sg_id { value try(aws_security_group.this[0].id, ) } # optional() - Optional attributes with defaults (1.3) variable config { type object({ name string timeout optional(number, 300) # Default: 300 }) } # Cross-variable validation (1.9) variable environment { type string } variable backup_days { type number validation { condition var.environment prod ? var.backup_days 7 : true error_message Production requires backup_days 7 } }有关完整的模式和示例请参阅代码模式现代 Terraform 功能版本特定指导Terraform 1.0-1.5使用 Terratest 进行测试没有可用的原生测试框架专注于静态分析和计划验证Terraform 1.6 / OpenTofu 1.6新增原生terraform test/tofu test命令考虑从外部框架迁移简单测试仅将 Terratest 保留用于复杂的集成测试Terraform 1.7 / OpenTofu 1.7新增用于单元测试的 Mock 提供程序通过模拟外部依赖降低成本使用真实集成测试进行最终验证Terraform 与 OpenTofu两者都完全受此技能支持。有关许可证、治理和功能比较请参阅快速参考Terraform 与 OpenTofu。详细指南此技能使用渐进式披露- 主文件中包含基本信息需要时提供详细指南参考文件测试框架- 静态分析、原生测试和 Terratest 的深入指南模块模式- 模块结构、变量/输出最佳实践、✅ 要与 ❌ 不要模式CI/CD 工作流- GitHub Actions、GitLab CI 模板、成本优化、自动清理安全与合规- Trivy/Checkov 集成、机密管理、合规测试快速参考- 命令速查表、决策流程图、故障排查指南使用方法当你在某个主题上需要详细信息时请参考相应的指南。Claude 将按需加载它以提供全面指导。许可证此技能根据Apache License 2.0许可。完整的条款请参阅 LICENSE 文件。版权所有 © 2026 Anton Babenko局限性仅当任务明确符合上述范围时使用此技能。不要将输出视为环境特定验证、测试或专家审查的替代品。如果缺少必需的输入、权限、安全边界或成功标准请停下来询问澄清。