保姆级指南 | Terraform基础设施即代码

▌ 技术引导

我见过太多人用Terraform写基础设施代码，最后还是得靠手动操作补漏洞。最值钱的经验是：别把所有资源都写在同一个模块里，资源间依赖关系要捋清楚，否则状态文件容易出错。使用state file的remote backend是必须的，本地状态管理会拖垮团队协作。资源创建顺序要考虑provider初始化的优先级，比如AWS和GCP之间切换时，provider配置得优先加载。别指望Terraform能自动处理所有依赖，资源的depends_on参数要精确到实例级别。实践表明，用locals块管理环境变量比直接写在resource块里更安全，尤其是多环境部署时。如果你没用terraform validate，先别想部署，这玩意能提前发现问题。别用输出变量直接作为其他资源的input，除非你确定输出是稳定的。最后，别忘记用terraform plan -lock=true，锁定状态文件防止他人误操作。这些细节踩过坑才会懂。

▌ 技术参考

一 用Terraform管理云资源时，必须明确资源间的依赖关系。比如创建VPC后才能创建子网，子网创建后才能部署EC2实例。Terraform通过隐式依赖自动处理部分关系，但关键资源如负载均衡器、数据库实例必须显式指定depends_on。在AWS场景中，可以这样写：resource "aws_subnet" "example" { depends_on = [aws_vpc.example] }。如果依赖关系复杂，推荐用locals块管理，比如locals { vpc_id = aws_vpc.example.id }，再在其他资源中引用locals.vpc_id。这样可以避免状态文件异常，尤其是在多模块协作时。

二 Terraform的remote backend配置是部署的基石。默认使用local backend容易导致状态文件冲突，尤其在团队协作和CI/CD环境中。推荐使用S3作为后端，配置参数包括bucket_name、key、region等。比如：terraform {
backend "s3" {
bucket = "my-bucket"
key = "terraform.tfstate"
region = "us-east-1"
}
}。此外，需设置state_locking和state_serialization，防止多人同时修改状态文件。如果使用GCP，后端配置方式类似，只需替换为google_cloud_storage_backend。注意，后端配置必须放在terraform块内，不能在单独的backend.tf文件中写。配置后，用terraform init -backend-config=... 来初始化。

三 在Terraform中使用模块时，必须保证模块的输入变量和输出变量匹配。比如，主模块调用子模块时，子模块的output必须被主模块的input引用。如果变量未定义，会报错提示missing input variable。另外，模块参数需定义类型，如string、number、map、list等，否则可能会出现类型冲突。比如，如果某个参数预期是list，但传入了string，会提示incompatible types。在实际项目中，推荐使用tfvars文件来管理变量，这样可以避免硬编码。如果变量是敏感的，需要用sensitive参数标记，防止泄露。

四 资源创建顺序可能影响整个部署流程。Terraform默认按依赖关系处理资源，但有些资源如数据库连接，必须在实例创建后才能配置。这种情况下，需要显式设置depends_on。例如，在创建RDS实例后，才能配置数据库用户和权限：resource "aws_db_instance" "example" { ... } resource "aws_db_user" "example" { depends_on = [aws_db_instance.example] }。如果配置错误，Terraform会提示resource has no attribute，这通常是依赖关系没设对。建议用terraform graph命令查看资源依赖关系图，确保逻辑正确。

五 Terraform的state file管理是避坑的关键。如果多个开发人员同时操作，本地状态容易被覆盖。使用remote backend后，state file会存储在S3或GCS中，确保只有一个版本。同时，state locking机制能防止并发操作冲突。配置state_locking后，每次修改前会加锁，其他人不能同时操作。如果在CI/CD中使用，建议启用state_serialization，防止状态文件被意外修改。另外，state file的版本控制必须跟进，比如用git管理，每次更新都要提交，否则回滚时会丢失状态。

六 在Terraform中配置provider时，注意版本控制和环境变量。比如AWS provider配置可以写成：provider "aws" { region = "us-west-2" }。如果有多环境部署，可以将region和profile写成变量，用terraform apply -var region=us-east-1来控制。某些provider需要环境变量，比如AWS的AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY，可以通过env变量注入。如果provider版本冲突，可以用required_version参数限制，比如required_version = ">= 2.0"。同时，provider配置应放在单独的文件中，如provider.tf，便于管理。

七 Terraform的plan和apply命令必须配合使用，否则无法保证变更安全。plan命令会生成变更计划，apply会执行变更。如果没用plan，直接apply可能会造成资源删除或创建错误。注意，plan生成后，最好用terraform show查看详细变更内容。如果发现变更过多，可以调整resource的依赖关系或参数，减少不必要的变更。另外，使用terraform plan -lock=true能防止状态文件被其他操作修改。在大型项目中，建议用terraform plan -target=... 来逐个资源测试，避免一次性变更导致不可控。

八 环境变量在Terraform中的使用非常灵活，但要小心处理。比如，设置AWS_PROFILE和AWS_DEFAULT_REGION可以让provider自动识别环境。如果想用变量控制环境，可以通过terraform apply -var region=us-west-2参数来指定。在某些场景下，比如多账户部署，可以用env变量传递账户ID，避免硬编码。但若未正确设置，可能会导致provider找不到默认配置。建议用terraform init -backend-config=... 来指定环境变量，确保一致性。同时，注意别在公共代码中暴露敏感变量，应通过加密方式传递，比如vault或aws secrets manager。

九 Terraform的locals块是管理变量的好工具，但使用时要谨慎。比如，定义一个locals块来管理VPC子网ID：locals { vpc_id = aws_vpc.example.id }。这样可以避免在多个地方重复引用资源ID，提高可读性。但如果locals块中的变量依赖于未定义的资源，可能会报错提示missing value。因此在使用locals时，要确保所引用的资源已经定义，或者使用condition判断。比如，如果某个资源可能不存在，可以用locals { db_exists = length(aws_db_instance.example) > 0 } 来控制后续逻辑。locals建议放在单独的文件中，便于维护和复用。

十 Terraform的output块是暴露资源信息的常用方式，但输出变量必须稳定。比如，输出一个子网ID：output "subnet_id" { value = aws_subnet.example.id }。如果子网ID在部署过程中可能变化，比如子网被删除或重新创建，输出可能会失效。因此在设计output时，要确保输出的资源是最终状态，比如输出EC2实例ID而不输出临时资源。此外，output的名称要清晰，比如output "vpc_id" 优于 output "vpc"。如果需要输出多个值，推荐用map结构，而不是列表，这样更易读。

十一 Terraform的state file备份和迁移是必须的，尤其是在环境变更时。比如，如果需要将state file从S3迁移到GCS，需先用terraform state pull获取当前状态，再用terraform state push强制迁移。如果迁移失败，可能需要手动调整state file的后端配置。另外，定期备份state file到其他存储介质，比如S3的版本控制或本地硬盘，能防止数据丢失。如果state file损坏，可以用terraform state replace-state来恢复。注意，操作前最好用terraform show确认当前状态，避免误操作。

十二 Terraform的模块化设计能提高代码复用率，但模块边界要清晰。比如，将数据库模块单独封装，主模块只负责调用。这样能降低耦合度，避免一个模块变动影响其他部分。模块输入变量应尽可能少，只暴露必要的参数，比如region和实例类型，而不是内部资源ID。模块输出变量要详细，比如输出数据库连接字符串、端口号等。如果模块之间存在复杂依赖，可以用module块的depends_on参数来处理。模块化建议用git仓库管理，便于版本控制和团队协作。

十三 Terraform的条件表达式是控制资源创建的重要手段。比如，如果某个资源只在生产环境创建：resource "aws_instance" "example" { count = var.environment == "prod" ? 1 : 0 }。或者用if判断控制资源类型：resource "aws_db_instance" "example" { if var.use_rds { ... } else { ... } }。注意，条件表达式不能嵌套太深，否则会影响可读性。此外，条件表达式要配合变量使用，避免硬编码。如果条件表达式逻辑复杂，建议用locals块辅助，减少代码冗余。

十四 Terraform的模块重用要注意版本兼容性。比如，在主模块中调用子模块时，要指定子模块的版本，如module "db" { source = "./modules/db" version = "1.0" }。这样能防止子模块更新后，主模块配置失效。如果子模块版本不兼容，可能会导致资源创建失败或状态不一致。建议在使用新版本模块前，先用terraform plan检查变更，确保兼容性。模块版本建议用语义化版本号，如"1.2.3"，便于追踪。如果模块未版本化，直接使用source路径可能引发不可控问题。

十五 Terraform的变量文件（.tfvars）和环境变量的结合使用能提高部署灵活性。比如，使用terraform apply -var-file=dev.tfvars来加载开发环境的变量，再用环境变量覆盖某些参数。比如，在AWS场景中，可以设置AWS_ACCESS_KEY_ID环境变量，再在provider中用var.aws_profile来引用。注意，环境变量优先级高于变量文件，因此在调试时要确认优先级是否正确。如果变量未定义，可能会报错提示missing variable，解决方法是检查变量来源或添加默认值。在ci/cd流程中，推荐用变量文件来管理不同环境的配置，避免硬编码。