1. 项目概述：这不是一份“说明书”，而是一张可复用的基础设施航海图
“Navigator's Guide: Modular Infrastructure Configuration”——光看标题，你可能以为这是本枯燥的运维手册，或者某个云厂商塞给客户的PDF文档。但实际不是。它本质上是一套面向真实交付场景的基础设施配置方法论，核心目标非常朴素：让团队在不同环境、不同云平台、不同业务阶段里，能像拼乐高一样快速组装出稳定、一致、可审计的基础设施，而不是每次上线都重写一堆零散的Terraform脚本，再靠人工核对几十个变量文件是否漏填、填错、版本不一致。
我带过6个跨云迁移项目，最深的体会是：90%的线上故障不是出在代码逻辑，而是出在环境配置漂移、模块耦合过紧、参数传递链断裂上。比如一个数据库模块，本该只暴露instance_type和backup_retention_days两个输入，结果被硬编码了VPC ID、子网ID、安全组规则甚至IAM策略；另一个Kubernetes集群模块，又把节点数、自动伸缩范围、监控告警阈值全揉进一个variables.tf里——最后改一个参数，得翻5个文件、跑3次terraform plan、等8分钟，还经常漏掉某个环境的staging分支没同步。这种状态，根本谈不上“基础设施即代码”，顶多算“基础设施即文本”。
这个指南解决的，正是这类“看似能跑，实则脆弱”的配置顽疾。它不教你怎么写第一个resource "aws_s3_bucket"，而是聚焦在模块怎么切、接口怎么定、依赖怎么管、变更怎么控这四个致命环节。关键词里的Terraform是载体，modules是骨架，infrastructure是对象，configuration是本质——所有操作最终都落在“如何让配置本身成为可验证、可组合、可演进的一等公民”。适合三类人：刚从手动部署转过来、正被tfstate混乱折磨的中级工程师；负责制定团队IaC规范的Tech Lead；以及需要向非技术干系人解释“为什么这次扩容要花三天而不是三小时”的运维负责人。它不承诺“一键全自动”，但能让你每次执行terraform apply前，心里有底。
2. 整体设计思路：为什么必须“模块化”，又为什么不能“过度模块化”
2.1 模块化的底层动因：对抗熵增的必然选择
基础设施配置天然具有熵增特性。新服务加进来，要开新VPC；安全合规要求升级，要补新标签、新日志策略；业务流量突增，要调节点数、扩存储——这些变化不会整齐划一地发生，而是像毛细血管一样渗透到每个资源定义里。如果所有配置都堆在一个main.tf里，就像把所有电线拧成一股麻绳：表面看连通了，但想换其中一根，就得拆开整捆，还容易扯断别的线。
模块化，本质是通过边界控制复杂度。Terraform官方文档说“模块是封装的配置包”，但这太轻描淡写了。真正有效的模块，必须满足三个硬性条件：
- 语义自治：模块内部知道“自己是谁”。一个
aws-rds-postgres模块，绝不该关心ECS服务的健康检查路径；它只回答一个问题：“给我网络、密码、规格，我能给你一个符合PCI-DSS基础要求的PostgreSQL实例”。 - 契约清晰：输入输出像API一样明确定义。输入变量要有类型、默认值、描述（不是
variable "vpc_id" {}，而是variable "vpc_id" { type = string; description = "ID of the VPC where DB instance will be deployed"; }）；输出必须是下游真正需要的值（output "endpoint" { value = aws_db_instance.main.endpoint }，而不是把整个aws_db_instance.main对象全吐出去）。 - 演化隔离：模块内部重构不影响外部。今天用
aws_db_instance，明天换成aws_rds_cluster，只要输入输出契约不变，调用它的上层模块完全无感。这就像你手机换了芯片，只要充电口还是USB-C，你的充电线就不用换。
我见过最典型的反模式，是把“模块”当成文件夹分类。比如建个modules/networking/目录，里面放vpc.tf、subnet.tf、security_group.tf三个文件，然后在根目录用module "network" { source = "./modules/networking" }调用——这根本不是模块，只是把代码物理拆分，逻辑上仍是强耦合的。真正的模块，应该是一个vpc模块，它内部决定要不要创建NAT网关、是否启用DNS支持、如何分配子网CIDR，外部只传入region、azs、cidr_block三个参数。
2.2 过度模块化的陷阱：当抽象变成障碍
但模块化不是银弹。我亲手踩过最痛的坑，是把“抽象”玩脱了。当时为了追求“极致复用”，设计了一套“元模块”：generic-compute、generic-storage、generic-network，每个模块都带十几层嵌套的dynamic块和for_each循环，试图用一套代码覆盖AWS EC2、GCP Compute Engine、Azure VM三种云。结果呢？terraform plan耗时从47秒暴涨到11分钟；variables.tf里光是disk_type相关变量就有7个，文档写了23页；更可怕的是，当AWS发布新实例类型m7i.large时，我们得改遍所有generic-compute的映射表，测试覆盖所有云厂商组合——这已经不是基础设施管理，是在维护一个脆弱的翻译引擎。
所以这个指南的核心取舍原则是：模块粒度由“变更频率”和“责任归属”决定，而非“技术相似性”。
- 如果一个数据库配置，开发团队和DBA团队要频繁协商调整（比如备份策略、慢查询阈值），那就把它独立成
database-configuration模块，由DBA团队维护； - 如果VPC的CIDR和AZ列表，半年才变一次，且由网络组统一管理，那
vpc模块就该足够厚重，包含路由表、流日志、DNS解析等完整能力； - 但绝不要为“所有云厂商的负载均衡器”造一个
lb模块——AWS ALB、GCP HTTP(S) Load Balancing、Azure Application Gateway的模型差异太大，强行统一只会让每个实现都带着补丁。
实操中，我用一个简单判断法：当两个资源的生命周期、审批流程、监控指标、告警联系人不同时，它们就不该属于同一个模块。比如ECS服务的task_definition和service，虽然技术上紧密耦合，但task_definition的更新通常由CI/CD自动触发，而service的扩缩容可能由运维手动执行——这时把它们拆成ecs-task和ecs-service两个模块，反而更利于权限分离和操作审计。
2.3 导航图的结构逻辑：四层金字塔，每层解决一类问题
这张“导航图”不是线性流程，而是一个四层金字塔结构，自下而上构建稳定性：
第1层：基础模块（Foundation Modules）
这是地基，只做三件事：网络（VPC/子网/路由）、身份（IAM角色/策略）、基础存储（S3桶/加密密钥）。它们的特点是：极少变更、高度标准化、由Infra Team集中维护。比如我们的foundation-vpc模块，强制要求所有子网打上environment=prod/staging/dev标签，并内置aws_vpc_endpoint连接S3和DynamoDB——不是因为业务需要，而是合规审计的硬性要求。第2层：服务模块（Service Modules）
这是承重墙，封装具体技术栈。aws-eks-cluster、gcp-cloud-sql、azure-app-service各自独立，不互相依赖。关键设计是：每个服务模块必须自带最小可行监控和日志配置。比如aws-eks-cluster模块，不仅创建集群，还自动部署cloudwatch-agentDaemonSet和预设的cluster-autoscaler告警规则——不是锦上添花，而是避免新集群上线后，监控空白期长达24小时。第3层：应用模块（Application Modules）
这是功能层，对接业务需求。一个payment-service模块，会调用aws-eks-cluster（获取kubeconfig）、aws-rds-postgres（获取连接串）、aws-s3-bucket（获取存储桶名），然后部署Helm Chart。它的核心价值在于：将业务语义注入基础设施。比如payment-service模块的输入变量里，有pci_compliance_level = "level_1"，模块内部据此自动开启RDS的加密、S3的版本控制、EKS的Pod Security Policy——技术细节被封装，业务意图被显式表达。第4层：环境模块（Environment Modules）
这是顶层甲板，定义“在哪里运行”。production、staging、feature-branch三个环境模块，各自引用相同的应用模块，但传入不同的参数：production用m6i.2xlarge节点、staging用t3.medium、feature-branch用Spot实例。更重要的是，环境模块负责兜底治理：production模块强制开启所有资源的tags和backup，staging模块自动添加destroy_after = "2024-12-31"生命周期标签，feature-branch模块则禁用所有公网IP和外网访问策略。
这四层不是静态的，而是动态演进的。当某个服务模块被5个以上应用模块调用，且参数组合超过10种时，我们就把它拆成更细的service-core和service-addon；当某个环境模块的配置差异过大（比如production要对接企业AD，staging用本地LDAP），我们就把它升格为独立的identity-provider模块。导航图的价值，正在于这种可感知、可度量、可决策的演进路径。
3. 核心细节解析：模块接口设计、状态管理与依赖治理
3.1 接口设计：变量不是参数列表，而是服务契约
很多人把模块变量当成函数参数，这是巨大误区。变量是模块对外承诺的服务契约，必须像API文档一样严谨。我们团队强制执行的变量设计规范如下：
必填变量必须有明确业务含义，禁止技术裸露
错误示例：variable "instance_type" {}—— 类型是什么？t3.micro还是c5.4xlarge？适用场景？CPU密集型还是内存密集型？
正确做法：variable "compute_profile" { type = string; description = "Compute profile for this service: 'general_purpose' (t3/t4g), 'memory_optimized' (r6i), or 'cpu_optimized' (c5/c6i). Determines instance type and EBS volume type."; validation { condition = contains(["general_purpose", "memory_optimized", "cpu_optimized"], var.compute_profile) } }
这样，调用方不需要查AWS文档，只需理解业务需求（“我要跑Java应用，内存大点”），模块内部自动映射到r6i.xlarge+gp3卷。默认值不是偷懒，而是设定安全基线
variable "enable_encryption" { type = bool; default = true; description = "Enable encryption at rest. Set to false only for ephemeral staging resources." }
我们所有生产模块的加密、日志、标签默认全开。default = false只允许出现在staging或test专用模块里，且必须在描述中强调风险。敏感变量必须显式标记，杜绝隐式泄露
variable "db_password" { type = string; sensitive = true; description = "Database master password. Will be stored in AWS Secrets Manager." }
关键是sensitive = true——这不仅是UI隐藏，更是Terraform State的保护机制。曾经有同事在调试时把db_password变量设为default = "password123"，结果terraform state show直接打印明文，被扫描工具抓出漏洞。现在所有敏感变量必须强制sensitive，且CI流水线会用terraform validate --check-variables校验。复杂结构用
object类型约束，拒绝自由发挥
错误示例：variable "autoscaling_config" { type = map(any) }—— 调用方可以传任意key，模块内部还得写一堆lookup()和try()来防御。
正确做法：variable "autoscaling_config" { type = object({ min_capacity = number; max_capacity = number; target_cpu_utilization = number; scale_out_cooldown = number; }); default = { min_capacity = 2; max_capacity = 10; target_cpu_utilization = 70; scale_out_cooldown = 300; }; }
这样，IDE能自动补全，terraform plan能校验类型，错误在apply前就被拦截。
提示：我们用
terraform-docs自动生成模块README，但绝不手写。每次git commit前，CI会运行terraform-docs markdown table ./modules/xxx > README.md，确保文档永远和代码一致。曾经有新人改了变量但忘了更新文档，CI直接阻断合并——文档不是附属品，是契约的一部分。
3.2 状态管理：State不是黑盒，而是可审计的配置快照
Terraform State常被妖魔化为“定时炸弹”，根源在于把它当成了黑盒。实际上，terraform.tfstate本质就是基础设施的JSON快照，关键在于如何让它可读、可追溯、可协作。
我们采用三级State策略：
第一级：模块级State隔离
每个基础模块（如foundation-vpc）拥有独立的State文件，存储在S3 Backend中，路径为s3://my-infra-state/foundation/vpc/terraform.tfstate。这样，修改VPC配置时，terraform plan只读取VPC State，不会加载整个EKS集群的几千行状态——速度提升7倍，冲突概率趋近于零。第二级：环境级State锁定
production环境State文件启用DynamoDB锁表，且terraform apply必须带-var-file=prod.auto.tfvars。这个.auto.tfvars文件由CI生成，内容包括：commit_hash = "a1b2c3d"、deployed_by = "ci-pipeline"、deploy_time = "2024-05-20T14:23:00Z"。这意味着，任何手动apply都会因缺少commit_hash变量而失败——State变更必须关联代码提交，不可追溯的操作被彻底杜绝。第三级：State审计自动化
每日凌晨，一个Lambda函数扫描所有State文件，执行三项检查：- 标签一致性：检查所有资源是否都有
environment、team、cost_center标签，缺失则发Slack告警； - 配置漂移：对比State中记录的
aws_s3_bucketversioning字段和AWS API实时返回值，不一致则触发修复流水线； - 密钥轮换：检查
aws_kms_key的key_rotation_enabled是否为true，未启用则自动开启并记录事件。
这套机制让我们在2023年Q4的第三方安全审计中，State管理项拿到满分。审计员说：“你们的State不是配置记录，而是活的合规仪表盘。”
- 标签一致性：检查所有资源是否都有
3.3 依赖治理：用显式依赖替代隐式假设
Terraform的depends_on常被滥用为“我不知道为啥要等，先加上保险”。真正的依赖治理，是让模块间的协作关系可声明、可验证、可可视化。
我们弃用depends_on，改用两种机制：
输出即依赖：模块间唯一合法的依赖方式，是通过
output传递必要信息。比如aws-eks-cluster模块输出kubeconfig和cluster_endpoint，payment-service模块必须通过module.eks-cluster.kubeconfig引用——如果payment-service试图直接调用aws_eks_cluster.this.endpoint，CI会用tfsec报错：“Forbidden direct resource reference across modules”。依赖图谱自动生成：在CI流水线中，
terraform graph -type=plan生成DOT格式依赖图，再用graphviz转成PNG。每次PR提交，都会在评论区自动贴出本次变更的依赖图。例如，一个修改foundation-vpc子网CIDR的PR，图谱会清晰显示：foundation-vpc→aws-eks-cluster→payment-service→monitoring-stack，共4层影响。开发人员一眼就能判断：“哦，这次改VPC会影响监控告警，得通知SRE团队一起Review”。
注意：我们严禁跨层调用。
application-module可以直接调用service-module，但绝不允许调用foundation-module。所有跨层访问，必须通过service-module的输出中转。比如payment-service需要VPC ID，不是自己去module.foundation-vpc.vpc_id，而是让aws-eks-cluster模块在输出中增加vpc_id = module.foundation-vpc.vpc_id，再由payment-service引用module.eks-cluster.vpc_id。这增加了两行代码，但换来的是清晰的责任边界——网络组只对foundation-vpc模块负责，EKS组对aws-eks-cluster模块负责，业务组只关心应用模块。
4. 实操过程：从零搭建一个可落地的模块化配置体系
4.1 第一步：初始化模块仓库与基础骨架
别急着写代码。先搭好“脚手架”，否则后面全是补丁。我们用Git Submodule管理模块仓库，主仓库infra-root只存环境配置，所有模块放在独立仓库infra-modules中。
# 创建模块仓库（独立Git repo） mkdir infra-modules && cd infra-modules git init # 创建标准目录结构 mkdir -p modules/{foundation,service,application,environment} # 每个模块目录下，强制包含4个文件 touch modules/foundation/vpc/{main.tf,variables.tf,outputs.tf,README.md} # 初始化模块元数据 echo '{ "name": "foundation-vpc", "description": "Standard VPC with public/private subnets, NAT gateways, and flow logs", "version": "1.0.0", "terraform_version": ">= 1.5.0" }' > modules/foundation/vpc/module.json关键细节：
module.json不是Terraform必需，但它是CI流水线的“身份证”。terraform-docs、tfsec、terrascan都读取它来校验模块合规性。README.md模板固定包含：Usage（调用示例）、Inputs（变量表）、Outputs（输出表）、Requirements（Terraform/Provider版本）、Providers（所需Provider）、Resources（创建的资源清单）。没有“高级技巧”、“最佳实践”等虚内容，全是机器可读的结构化信息。
实操心得：我们曾用
terraform registry托管模块，但很快放弃。原因有三：1）私有模块无法设置细粒度权限（比如只让DevOps组能发布，不让开发组看到源码）；2）版本回滚困难（Registry的1.0.0和1.0.1都是不可变的，但内部模块常需紧急热修复）；3）缺乏与CI深度集成。现在所有模块都在GitLab私有仓库，用git tag v1.0.0打版本，CI自动构建并推送到S3 Backend——比Registry更可控，也更符合企业安全要求。
4.2 第二步：编写第一个基础模块——foundation-vpc
以modules/foundation/vpc为例，展示如何写出“生产就绪”的模块：
variables.tf（精简核心）：
variable "region" { type = string description = "AWS Region where VPC will be created" validation { condition = can(regex("^[a-z]{2}-[a-z]+-[0-9]$", var.region)) error_message = "Region must match format like 'us-east-1'" } } variable "cidr_block" { type = string description = "Primary CIDR block for the VPC" default = "10.0.0.0/16" validation { condition = cidrhost(var.cidr_block, 0) != "" error_message = "Invalid CIDR block format" } } variable "azs" { type = list(string) description = "List of Availability Zones, e.g. [\"us-east-1a\", \"us-east-1b\"]" default = ["us-east-1a", "us-east-1b"] } variable "enable_flow_logs" { type = bool default = true description = "Enable VPC Flow Logs to CloudWatch Logs" }main.tf（核心逻辑）：
# 创建VPC resource "aws_vpc" "this" { cidr_block = var.cidr_block enable_dns_hostnames = true enable_dns_support = true tags = merge( local.common_tags, { Name = "${local.name_prefix}-vpc" } ) } # 创建公有子网（每个AZ一个） resource "aws_subnet" "public" { count = length(var.azs) vpc_id = aws_vpc.this.id cidr_block = cidrsubnet(var.cidr_block, 8, count.index + 1) availability_zone = var.azs[count.index] map_public_ip_on_launch = true tags = merge( local.common_tags, { Name = "${local.name_prefix}-public-${var.azs[count.index]}" } ) } # 创建私有子网（每个AZ一个） resource "aws_subnet" "private" { count = length(var.azs) vpc_id = aws_vpc.this.id cidr_block = cidrsubnet(var.cidr_block, 8, count.index + 10) availability_zone = var.azs[count.index] map_public_ip_on_launch = false tags = merge( local.common_tags, { Name = "${local.name_prefix}-private-${var.azs[count.index]}" } ) } # 创建NAT网关（每个公有子网一个） resource "aws_nat_gateway" "this" { count = length(aws_subnet.public) allocation_id = element(aws_eip.nat.*.id, count.index) subnet_id = element(aws_subnet.public.*.id, count.index) tags = merge( local.common_tags, { Name = "${local.name_prefix}-nat-${var.azs[count.index]}" } ) } # 流日志（可选） resource "aws_flow_log" "vpc" { count = var.enable_flow_logs ? 1 : 0 iam_role_arn = aws_iam_role.flow_logs.arn log_destination = aws_cloudwatch_log_group.flow_logs.arn traffic_type = "ALL" vpc_id = aws_vpc.this.id }outputs.tf（契约输出）：
output "vpc_id" { value = aws_vpc.this.id description = "ID of the created VPC" } output "public_subnets" { value = aws_subnet.public[*].id description = "List of public subnet IDs" } output "private_subnets" { value = aws_subnet.private[*].id description = "List of private subnet IDs" } output "availability_zones" { value = var.azs description = "List of AZs used for subnets" }关键设计点解析：
- CIDR计算自动化：
cidrsubnet(var.cidr_block, 8, count.index + 1)自动为每个AZ分配/24子网，无需手动计算10.0.1.0/24、10.0.2.0/24——减少人为错误，也便于未来扩展到更多AZ。 - 命名规范化：所有资源标签都通过
local.common_tags统一注入，包含environment、team、managed_by = "terraform"，确保审计时能精准归因。 - 流日志条件化：用
count = var.enable_flow_logs ? 1 : 0控制资源创建，比lifecycle { ignore_changes = [enabled] }更干净——不需要的资源，根本不进State。
4.3 第三步：构建环境模块——environments/production
环境模块是“导航图”的终点，也是所有模块的消费者。environments/production目录结构如下：
environments/production/ ├── main.tf # 调用所有模块 ├── variables.tf # 定义环境级变量（如region, account_id） ├── terraform.tf # Backend配置 └── auto.tfvars # 环境特定参数（CI生成）main.tf（核心编排）：
# 基础设施 module "foundation" { source = "git::https://gitlab.com/my-org/infra-modules.git//modules/foundation/vpc?ref=v1.2.0" region = var.region cidr_block = "10.10.0.0/16" azs = ["us-east-1a", "us-east-1b", "us-east-1c"] enable_flow_logs = true } # 服务层 module "eks_cluster" { source = "git::https://gitlab.com/my-org/infra-modules.git//modules/service/aws-eks-cluster?ref=v2.1.0" vpc_id = module.foundation.vpc_id public_subnets = module.foundation.public_subnets private_subnets = module.foundation.private_subnets cluster_name = "prod-payment-cluster" node_groups = [ { name = "core-ng" instance_type = "m6i.2xlarge" min_capacity = 3 max_capacity = 10 } ] } # 应用层 module "payment_service" { source = "git::https://gitlab.com/my-org/infra-modules.git//modules/application/payment-service?ref=v3.0.0" eks_cluster_endpoint = module.eks_cluster.cluster_endpoint eks_cluster_ca_cert = module.eks_cluster.cluster_certificate_authority_data rds_endpoint = module.rds_postgres.endpoint s3_bucket_name = module.s3_storage.bucket_name environment = "production" }auto.tfvars（CI生成的黄金配置）：
# 此文件由CI Pipeline在部署前自动生成 region = "us-east-1" account_id = "123456789012" commit_hash = "a1b2c3d4e5f67890abcdef1234567890abcdef12" deployed_by = "pipeline-prod-deploy"实操要点：
- 版本锁定：所有
source都带?ref=vX.Y.Z，绝不使用?ref=main。模块版本升级必须走PR Review，附带升级指南和回滚步骤。 - 环境隔离：
production、staging、feature-branch是三个完全独立的目录，各自有自己的terraform.tf指向不同的Backend（s3://prod-state/、s3://staging-state/、s3://feature-state/）。没有共享State，就没有意外覆盖。 - 参数注入：
auto.tfvars不存Git，由CI从环境变量注入。terraform apply -var-file=auto.tfvars命令在CI脚本中固化，开发人员无法绕过。
4.4 第四步：CI/CD流水线——让导航图自动运转
没有自动化，再好的设计也是纸上谈兵。我们的CI流水线（GitLab CI）包含四个核心阶段：
| 阶段 | 工具 | 关键动作 | 失败后果 |
|---|---|---|---|
| Validate | terraform validate,tflint | 检查语法、变量、Provider兼容性 | 阻断PR合并 |
| Plan | terraform plan -out=tfplan | 生成执行计划，上传为CI产物 | 不阻断，但供Review |
| Security Scan | tfsec,checkov | 扫描硬编码密钥、未加密存储、开放安全组 | 阻断PR合并（高危） |
| Apply | terraform apply tfplan | 执行部署 | 仅限production分支，需双人Approval |
关键配置片段（.gitlab-ci.yml）：
stages: - validate - plan - security - apply validate: stage: validate script: - terraform init -backend-config="bucket=my-infra-state" -backend-config="key=validate.tfstate" - terraform validate - tflint --module plan: stage: plan script: - terraform init -backend-config="bucket=my-infra-state" -backend-config="key=plan.tfstate" - terraform plan -out=tfplan artifacts: paths: [tfplan] security: stage: security script: - tfsec . - checkov -d . apply: stage: apply script: - terraform init -backend-config="bucket=my-infra-state" -backend-config="key=apply.tfstate" - terraform apply tfplan rules: - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/ - if: $CI_COMMIT_BRANCH == "production" needs: ["plan"]经验教训：
- 我们曾把
terraform apply放在plan阶段之后立即执行，结果一次plan生成的tfplan被多个并发Job读取，导致状态错乱。现在tfplan作为CI产物，apply阶段必须显式needs: ["plan"]，确保顺序执行。 security阶段不阻断PR，但会生成详细报告。高危问题（如aws_s3_bucket未启用server_side_encryption_configuration）必须修复才能Merge；中危问题（如缺少tags）则记录为Tech Debt，每月清理。- 所有
terraform命令都加-no-color参数，确保CI日志可读。曾经有次terraform plan输出带ANSI颜色码，导致日志解析失败，告警延迟2小时。
5. 常见问题与排查技巧实录：那些文档里不会写的坑
5.1 问题速查表：高频故障与根因定位
| 现象 | 可能根因 | 快速定位命令 | 解决方案 |
|---|---|---|---|
Error: Invalid count argument | count表达式中引用了未定义变量或空列表 | terraform console，输入length(var.azs)看返回值 | 检查variables.tf中default值，或用count = length(var.azs) > 0 ? 1 : 0兜底 |
Error: Error loading state: Failed to read state file | Backend配置错误，或S3 Bucket不存在 | aws s3 ls s3://my-infra-state/，检查路径和权限 | 在terraform.tf中确认key路径，用aws s3api head-bucket --bucket my-infra-state验证Bucket存在 |
Error: Cycle: module.a -> module.b -> module.a | 模块间存在循环依赖（A输出给B，B又输出给A） | terraform graph -type=plan | dot -Tpng -o graph.png | 删除双向引用，改为通过第三个模块（如shared-config）中转 |
Error: Provider configuration not present | required_providers未声明，或版本不匹配 | terraform providers，查看已加载Provider | 在模块根目录versions.tf中声明required_providers { aws = { source = "hashicorp/aws"; version = "~> 5.0" } } |
Error: Invalid function argument | cidrsubnet()参数超出范围（如newbits太大） | terraform console，输入cidrsubnet("10.0.0.0/16", 8, 100)看报错 | 计算公式：max_subnets = 2^newbits，确保newbits不超过32 - prefix_length |
5.2 独家避坑技巧：来自血泪现场
技巧1：用
null_resource做模块“钩子”，而非改模块代码
有时需要在模块创建后执行额外操作（如向S3上传配置文件、调用API注册服务）。很多人会把aws_s3_object直接写进模块里，但这破坏了模块的通用性。正确做法：在环境模块中，用null_resource监听模块输出：resource "null_resource" "upload_config" { triggers = { cluster_id = module.eks_cluster.cluster_id config_hash = filesha256("${path.module}/config.yaml") } provisioner "local-exec" { command = "aws s3 cp ${path.module}/config.yaml s3://my-bucket/config/${module.eks_cluster.cluster_id}/" } }这样，模块保持纯净，环境模块按需扩展。
技巧2：
for_each的键名必须稳定，避免State漂移
错误写法：for_each = toset(["app", "api", "db"])——toset顺序不保证，可能导致app资源被销毁重建。
正确写法：for_each = { for k in ["app", "api", "db"] : k => k }，或直接用map：for_each = { app = "app", api = "api", db = "db" }。键名稳定，State就不会乱。技巧3：模块内
locals不要跨模块引用，用output代替
曾有同事在aws-eks-cluster模块里定义`
