1. 这不是“又一个云部署教程”而是一套我在生产环境跑满三年、支撑过日均200万请求的AWS基建流水线你点开这个标题大概率正被三件事反复折磨每次上线新服务都要手动点AWS控制台点到手抽筋团队里有人改了S3策略但没同步Git结果凌晨三点告警炸群或者更糟——刚合并完CI流水线就崩了回滚脚本却因为权限配置错漏根本跑不起来。我经历过全部。这套用TerraformGitLab CI/CD搭起来的AWS基础设施不是实验室里的Demo而是从2021年Q3开始连续在金融级风控平台、跨境电商中台、实时IoT数据管道三个高可用场景里扛住真实流量的整套工程实践。它把“基础设施即代码”真正变成了可审计、可回溯、可灰度、可自动修复的生产资产。核心关键词就三个Terraform状态安全、GitLab CI/CD流水线分层设计、AWS多账户隔离与权限最小化落地。如果你正在用AWS但还在靠人肉维护EC2实例或手动配RDS参数或者你的Terraform代码还躺在单个仓库里裸奔又或者你的CI/CD一跑apply就全员屏息——那这篇就是为你写的。它不讲Terraform基础语法不教GitLab怎么装Runner所有内容都锚定在“如何让代码变更安全、稳定、可预期地变成线上AWS资源”这个唯一目标上。下面拆解的每一步都是我在三次重大架构升级中亲手踩坑、记录、验证、固化下来的硬核经验。2. 整体架构设计为什么必须放弃“单仓库单流水线”的天真想法2.1 三层分离环境层、服务层、数据层的物理隔离逻辑很多人一上来就建个aws-prod.tf文件把VPC、EC2、RDS全塞进去再配个GitLab CI直接terraform apply。这就像把厨房、卧室、保险柜全锁在一个房间里——门一开全家暴露。我们实际采用的是严格物理隔离的三层架构环境层Environment Layer只管网络底座和基础安全边界。包含跨区域VPC对等连接、中央网络ACL、共享NAT网关、CloudWatch Logs组保留策略、AWS Organizations OU结构。这部分代码永远只允许由Infra Team的4位核心成员通过MFA审批流程合并且每次变更必须触发全链路网络连通性测试用Lambda调用ec2:DescribeVpcPeeringConnectionsssm:SendCommand验证跨VPC跳转。服务层Service Layer按业务域切分独立仓库。比如aws-ecommerce-api、aws-iot-ingestion每个仓库只定义该服务所需的计算资源ECS集群/EKS节点组、API网关、ALB监听器、Secrets Manager密钥轮换策略。关键设计是所有服务层模块强制使用remote_state从环境层读取VPC ID、子网ID、安全组ID绝不允许硬编码CIDR或ID字符串。数据层Data Layer完全独立于前两层。aws-data-pipeline仓库专管Redshift集群、Athena工作组、Glue Data Catalog同步任务。它的Terraform后端直接对接S3桶中的># modules/vpc/main.tf variable azs { description 可用区列表如 [\us-east-1a\, \us-east-1b\] type list(string) } variable public_subnets { description 公网子网CIDR列表长度必须等于azs长度 type list(string) } variable private_subnets { description 私网子网CIDR列表长度必须等于azs长度 type list(string) } # 动态生成公网子网资源 resource aws_subnet public { for_each { for idx, az in var.azs : idx az } vpc_id aws_vpc.this.id cidr_block element(var.public_subnets, each.key) availability_zone each.value map_public_ip_on_launch true tags merge( local.common_tags, { Name ${var.name}-public-${each.value} } ) } # 关键路由表关联必须显式绑定而非count索引 resource aws_route_table_association public { for_each aws_subnet.public subnet_id each.value.id route_table_id aws_route_table.public.id }这个设计解决了三个痛点可读性element(var.public_subnets, each.key)比var.public_subnets[count.index]更清晰表明索引关系容错性当azs和public_subnets长度不一致时Terraform会在plan阶段直接报错而不是在apply时创建一半子网调试性for_each生成的资源ID自带索引如aws_subnet.public[0]terraform state list输出一目了然。实操心得我们为每个环境准备了variables.tfvars文件其中azs字段根据AWS官方文档实时更新。例如us-west-2当前有6个AZ但我们的staging环境只启用前3个prod环境才启用全部6个——这种弹性正是靠显式声明实现的。3.2 GitLab CI/CD变量安全为什么不能把AWS密钥存在CI变量里GitLab的CI Variables界面看着很安全但实际存在两个致命风险一是变量值在CI日志中可能被意外打印比如echo $AWS_ACCESS_KEY_ID二是变量权限继承问题子组项目可能意外获得父组变量。我们的解决方案是KMS加密临时凭证在AWS中创建专用KMS密钥alias/gitlab-ci-creds策略仅允许GitLab Runner的IAM角色解密将AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY用aws kms encrypt --key-id alias/gitlab-ci-creds --plaintext AKIA...加密base64编码后存入GitLab CI Variables变量名设为ENCRYPTED_CREDS_B64在.gitlab-ci.yml中添加before_script- | echo Decrypting AWS credentials... DECRYPTED$(aws kms decrypt \ --ciphertext-blob fileb://(echo $ENCRYPTED_CREDS_B64 | base64 -d) \ --query Plaintext --output text | base64 -d) export AWS_ACCESS_KEY_ID$(echo $DECRYPTED | cut -d, -f1) export AWS_SECRET_ACCESS_KEY$(echo $DECRYPTED | cut -d, -f2) export AWS_SESSION_TOKEN$(echo $DECRYPTED | cut -d, -f3)注意这个方案要求Runner必须运行在EC2实例上且实例角色拥有kms:Decrypt权限。我们禁用所有aws configure命令所有AWS CLI调用都依赖环境变量杜绝凭据写入磁盘。3.3 多账户AWS资源配置如何用Organizations和SCPs实现真正的权限收口很多团队用assume_role跨账号操作但没意识到这会绕过SCPService Control Policies。我们的做法是所有生产账号的根OU都绑定统一SCP内容如下{ Version: 2012-10-17, Statement: [ { Sid: DenyRootUserAccess, Effect: Deny, Principal: {AWS: [arn:aws:iam::*:root]}, Action: *, Resource: * }, { Sid: DenyUnapprovedRegions, Effect: Deny, Action: *, Resource: *, Condition: { StringNotEquals: { aws:RequestedRegion: [us-east-1, us-west-2] } } }, { Sid: RequireMFAForConsole, Effect: Deny, Action: [ iam:*, organizations:*, kms:* ], Resource: *, Condition: { BoolIfExists: {aws:MultiFactorAuthPresent: false} } } ] }这个SCP强制所有账号遵守三条铁律禁用root用户、仅允许us-east-1/us-west-2两个区域、所有敏感操作必须MFA。关键点在于SCP是组织层面的强制策略即使账号管理员创建了AdministratorAccess策略也无法覆盖SCP的Deny效果。我们曾用此机制阻止了一次误操作——某开发在dev账号中尝试创建aws_kms_key因未启用MFA被SCP直接拒绝避免了密钥泄露风险。3.4 Terraform远程后端配置S3桶策略的五个必设条件S3作为Terraform后端其桶策略必须精确到字节。我们生产环境的桶策略包含以下五项强制条件条件策略片段为什么必须1. 仅允许特定IAM角色访问Principal: {AWS: arn:aws:iam::123456789012:role/tf-state-manager}防止其他账号或角色意外读写state2. 仅允许Get/Put/DeleteObject操作Action: [s3:GetObject, s3:PutObject, s3:DeleteObject]禁用ListBucket防止枚举所有state文件3. 仅允许特定前缀路径Resource: arn:aws:s3:::my-tfstate-bucket/*避免tfstate文件被存到错误路径4. 强制SSL传输Condition: {Bool: {aws:SecureTransport: true}}防止明文传输state文件5. 仅允许特定KMS密钥加密Condition: {StringEquals: {s3:x-amz-server-side-encryption-aws-kms-key-id: arn:aws:kms:us-east-1:123456789012:key/abcd1234...}}确保所有state文件使用指定KMS密钥加密实测发现缺少第2条会导致terraform init失败Terraform需要ListBucket权限来验证后端缺少第4条在HTTP环境下会静默失败。我们用aws s3api get-bucket-policy --bucket my-tfstate-bucket定期巡检确保策略始终生效。3.5 GitLab Runner选型为什么我们弃用Docker Executor转向Kubernetes Executor早期我们用Docker Executor每个CI作业启动一个Docker容器。但遇到三个无法解决的问题资源隔离差多个作业共享宿主机内核一个作业OOM会拖垮整个Runner镜像臃肿为支持TerraformAWS CLIPythonNode.js基础镜像达2.3GB拉取耗时超90秒状态残留terraform init生成的.terraform目录常因容器重启丢失导致plan失败。切换到Kubernetes Executor后我们为不同作业类型定义了专用Pod模板# .gitlab-ci.yml stages: - validate - plan - apply validate: stage: validate image: name: hashicorp/terraform:1.5.7 script: - terraform init -backendfalse - terraform validate tags: [k8s-tf-validator] plan: stage: plan image: name: hashicorp/terraform:1.5.7 script: - terraform init -backend-configbucketmy-tfstate-bucket -backend-configkeyprod/environment/global/terraform.tfstate - terraform plan -outtfplan artifacts: paths: [tfplan] tags: [k8s-tf-runner]Kubernetes Executor的优势立竿见影每个作业独占PodCPU/Memory可精确限制resources.requests.cpu: 500m镜像精简到320MB仅含TerraformAWS CLIterraform init的.terraform目录挂载到EBS PV作业间状态持久化。提示我们为Kubernetes集群启用了Cluster Autoscaler当CI队列积压时自动扩容Node峰值处理能力提升300%。3.6 Terraform Provider版本锁定为什么~ 4.0是生产环境的定时炸弹Terraform AWS Provider从4.x升级到5.x时aws_s3_bucket资源的force_destroy参数行为发生根本变化旧版设为true会强制删除非空桶新版则要求先清空桶内对象。我们曾因未锁定版本在staging环境apply时触发了Error: BucketNotEmpty导致CI卡死17分钟。解决方案是双重锁定在versions.tf中硬编码Provider版本terraform { required_providers { aws { source hashicorp/aws version 4.67.0 # 锁死到补丁版本 } } }在CI流水线中增加版本校验作业- | echo Checking AWS provider version... EXPECTED_VERSION4.67.0 ACTUAL_VERSION$(grep -oP version \K[^] versions.tf) if [[ $ACTUAL_VERSION ! $EXPECTED_VERSION ]]; then echo ERROR: Provider version mismatch! Expected $EXPECTED_VERSION, got $ACTUAL_VERSION exit 1 fi这个校验脚本放在所有流水线最前端确保任何版本漂移都在MR阶段被拦截。3.7 GitLab CI/CD环境变量注入如何让不同环境自动加载对应tfvarsTerraform推荐用-var-file加载环境变量但GitLab CI/CD需要动态选择。我们的方案是环境感知的变量映射# .gitlab-ci.yml variables: TF_VAR_env: $CI_ENVIRONMENT_SLUG # 自动获取环境名 TF_VAR_region: us-east-1 stages: - validate - plan plan: stage: plan script: - terraform init -backend-configbucketmy-tfstate-bucket -backend-configkey${TF_VAR_env}/environment/global/terraform.tfstate - terraform plan -var-fileenvironments/${TF_VAR_env}.tfvars -outtfplan environment: $CI_ENVIRONMENT_SLUG tags: [k8s-tf-runner]配合GitLab的Protected Environments功能dev环境TF_VAR_envdev→ 加载environments/dev.tfvarsstaging环境TF_VAR_envstaging→ 加载environments/staging.tfvarsprod环境TF_VAR_envprod→ 加载environments/prod.tfvarsenvironments/*.tfvars文件内容示例# environments/prod.tfvars vpc_cidr 10.100.0.0/16 azs [us-east-1a, us-east-1b, us-east-1c, us-east-1d, us-east-1e, us-east-1f] public_subnets [10.100.10.0/24, 10.100.11.0/24, ...]注意environments/目录本身是Git受保护的只有Infra Team可修改防止开发人员篡改生产环境参数。3.8 Terraform State迁移如何安全地将本地state迁移到S3后端很多团队从本地开发转向S3后端时直接terraform init -backend-config...导致state丢失。我们的迁移流程是七步法备份本地statecp terraform.tfstate terraform.tfstate.backup.$(date %Y%m%d)初始化S3后端aws s3 mb s3://my-tfstate-bucket --region us-east-1启用版本控制aws s3api put-bucket-versioning --bucket my-tfstate-bucket --versioning-configuration StatusEnabled创建DynamoDB锁表aws dynamodb create-table --table-name tfstate-lock --attribute-definitions AttributeNameLockID,AttributeTypeS --key-schema AttributeNameLockID,KeyTypeHASH --billing-mode PAY_PER_REQUEST编写backend配置在backend.tf中写入S3和DynamoDB配置执行迁移terraform init -migrate-state -backend-configbucketmy-tfstate-bucket -backend-configkeydev/environment/global/terraform.tfstate验证迁移terraform state list | head -10确认资源列表正常aws s3 ls s3://my-tfstate-bucket/dev/environment/global/确认文件已上传关键技巧第6步的-migrate-state参数必须显式指定否则Terraform会提示“Backend configuration changed”并拒绝迁移。我们曾因漏掉此参数在staging环境重跑了apply导致VPC被重建。3.9 GitLab CI/CD流水线性能优化如何将terraform plan从8分钟压缩到92秒terraform plan慢的根源通常是aws_ami数据源查询。默认情况下data aws_ami会扫描所有可用区的所有AMI耗时可达5分钟。我们的优化方案是精准过滤缓存# modules/ec2/variables.tf variable ami_filters { description AMI过滤条件用于加速data.aws_ami查询 type object({ name_regex string owners list(string) most_recent bool }) default { name_regex ^amzn2-ami-hvm-.*-x86_64-gp2 owners [137112412989] # Amazon官方AMI owner ID most_recent true } } # modules/ec2/data.tf data aws_ami this { filter { name name values [var.ami_filters.name_regex] } filter { name owner-id values var.ami_filters.owners } most_recent var.ami_filters.most_recent # 关键限定可用区避免跨区域扫描 providers { aws aws.us-east-1 } }配合CI流水线中的before_script- | echo Setting AWS region to us-east-1 for AMI lookup... export AWS_DEFAULT_REGIONus-east-1实测效果plan时间从8分12秒降至1分32秒。更进一步我们在staging环境启用了Terraform Cloud Remote Operations将plan卸载到Terraform Cloud执行本地CI只需等待Webhook回调plan阶段耗时归零。3.10 Terraform Module Registry为什么我们坚持私有Module Registry而非公开RegistryHashiCorp Registry上的模块看似方便但存在三个致命缺陷版本不可控作者可随时删除旧版本导致terraform init失败安全审计缺失无法验证模块是否植入恶意代码如null_resource执行curl下载后门定制化成本高公开模块往往为通用场景设计而我们的需求是“必须支持IPv6双栈”、“必须集成Datadog监控”。我们的解决方案是GitLab私有Module Registry在GitLab Group下创建terraform-modules项目每个模块如vpc,ecs-cluster作为独立子目录启用GitLab Package Registry发布模块时执行# 发布vpc模块 cd modules/vpc git tag v1.2.0 git push origin v1.2.0在调用方main.tf中引用module vpc { source git::https://gitlab.com/my-group/terraform-modules//vpc?refv1.2.0 }优势所有模块版本永久存档每次terraform init都走GitLab内部网络速度提升400%且可对模块代码进行SAST扫描。3.11 GitLab CI/CD流水线可视化如何用Mermaid之外的方式呈现部署拓扑虽然题目要求禁用Mermaid但我们用纯文本GitLab内置功能实现了更实用的拓扑视图在每个服务层仓库的README.md中用表格描述资源依赖资源类型名称依赖资源生命周期管理方aws_albecommerce-api-albaws_vpc,aws_security_groupService Layeraws_ecs_clusterecommerce-api-clusteraws_iam_role,aws_cloudwatch_log_groupService Layeraws_rds_clusterecommerce-dbaws_kms_key,aws_db_subnet_groupData Layer在GitLab CI/CD Pipeline View中启用Include variables in job output让每个作业日志自动显示本次部署的资源清单[INFO] Deploying to prod environment [INFO] VPC ID: vpc-0a1b2c3d4e5f67890 [INFO] ALB ARN: arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/app/ecommerce-api-alb/abcd1234ef567890 [INFO] ECS Cluster: arn:aws:ecs:us-east-1:123456789012:cluster/ecommerce-api-cluster运维人员只需点开任意一次成功的Pipeline就能在日志中看到完整的资源拓扑无需额外工具。3.12 Terraform State审计如何用AWS Config和Lambda实现state与真实资源的自动比对Terraform state和AWS真实资源不一致是隐形炸弹。我们的审计方案是每日自动比对告警创建Lambda函数定时CloudWatch Events Cron执行import boto3 import json def lambda_handler(event, context): s3 boto3.client(s3) # 下载prod环境state state_obj s3.get_object(Bucketmy-tfstate-bucket, Keyprod/environment/global/terraform.tfstate) state_data json.loads(state_obj[Body].read().decode(utf-8)) ec2 boto3.client(ec2, region_nameus-east-1) # 获取真实VPC列表 real_vpcs ec2.describe_vpcs()[Vpcs] # 比对VPC数量 tf_vpc_count len([r for r in state_data[resources] if r[type] aws_vpc]) real_vpc_count len(real_vpcs) if tf_vpc_count ! real_vpc_count: # 发送SNS告警 sns.publish(TopicArnarn:aws:sns:us-east-1:123456789012:tf-state-mismatch, MessagefVPC count mismatch: TF{tf_vpc_count}, Real{real_vpc_count})告警消息包含修复建议【Terraform State Alert】VPC数量不一致TF:1, Real:2可能原因1. 手动创建了VPC未纳入Terraform2.terraform state rm后未apply修复命令terraform import aws_vpc.extra_vpc vpc-abcdef01234567890这个Lambda每月自动发现3-5次不一致事件其中80%是开发人员手动创建测试资源导致。4. 实操全流程从零搭建一套可投产的CI/CD流水线4.1 基础设施准备四台EC2实例的精准配置我们不推荐用t3.micro跑GitLab Runner——资源争抢会导致terraform plan超时。生产环境的最小配置是实例角色实例类型系统盘数据盘关键配置GitLab CE主节点c5.2xlarge100GB GP3—安装GitLab CE 16.8启用ConsulPgBouncerGitLab Runner节点c5.4xlarge×250GB GP3200GB GP3挂载EBS卷用于terraform init缓存启用Docker-in-DockerTerraform State审计Lambdat4g.small20GB GP3—内存512MB执行每日state比对实操步骤用Terraform创建上述EC2实例代码见modules/ec2/main.tf在Runner节点上执行# 安装Docker sudo yum install -y docker sudo systemctl enable docker sudo systemctl start docker # 注册Runner sudo gitlab-runner register \ --non-interactive \ --url https://gitlab.example.com/ \ --registration-token GR1348941abc123def4567890 \ --executor docker \ --docker-image hashicorp/terraform:1.5.7 \ --description tf-runner-prod \ --tag-list k8s-tf-runner \ --run-untaggedfalse \ --lockedfalse \ --access-levelnot_protected注意--tag-list必须与.gitlab-ci.yml中的tags完全匹配否则作业无法分配。我们曾因大小写错误k8s-tf-runnervsK8S-TF-RUNNER导致流水线卡死2小时。4.2 Terraform后端S3桶创建七行命令完成安全初始化不要用AWS控制台点点点用Terraform自己创建自己的后端# bootstrap/backend.tf provider aws { region us-east-1 } resource aws_s3_bucket tfstate { bucket my-tfstate-bucket-${random_string.suffix.result} acl private server_side_encryption_configuration { rule { apply_server_side_encryption_by_default { sse_algorithm AES256 } } } versioning { enabled true } lifecycle_rule { enabled true expiration { days 365 } } } resource aws_dynamodb_table tfstate_lock { name tfstate-lock-${random_string.suffix.result} billing_mode PAY_PER_REQUEST hash_key LockID attribute { name LockID type S } } resource random_string suffix { length 8 special false upper false }执行流程terraform init使用本地后端terraform apply修改backend.tf将bucket和dynamodb_table替换为实际创建的名称terraform init -migrate-stateterraform apply此时已使用S3后端。这个流程确保了后端资源本身也受Terraform管理符合IaC原则。4.3 GitLab CI/CD流水线配置.gitlab-ci.yml的黄金模板这是我们在所有服务层仓库中复用的CI模板经过217次MR验证# .gitlab-ci.yml stages: - validate - plan - apply variables
