Iac on IT 运维小秋

Terraform cicd

chenwx716@139.com — Sat, 20 Sep 2025 12:30:00 +0800

Terraform-cicd

方案 1: github workflows
方案 2: Atlantis 根据分支合并请求 + 评论进行
方案 3: jenkins 手动发布

GitHub

PR 触发: 向 main 分支提交 PR 时, 流水线会运行, 主要为了校验代码和展示计划
Push 触发: 当代码合入 main 后, 流水线会执行实际的部署

可选事件

dev 环境在 dev 分支, 提交后自动触发变更, 不需人工审批
生产环境走人工确认步骤
将每个环境独立为不同的 workflows 文件, 避免复杂逻辑

实践 1: pr plan 生成的计划文件提交到 artifact, apply 时直接应用此文件
缺点: 计划可能过时, 如审批时间太久, 线上已经漂移, 或先合并了其它 pr 等场景, 所以一般情况不推荐这种做法;
更推荐以 main 分支为准, 提交或合并时, 执行当前最新生成的 plan 计划;

.github/workflows/terraform.yml

name: Terraform Validate

permissions:
  id-token: write   # 允许生成 OIDC JWT 令牌(用于云服务身份认证)
  contents: read    # 允许读取仓库代码(最基本的需求)
  pull-requests: write  # 允许对 PR 进行评论, 更新状态等

on:
  push:
    branches: [main]
    paths:
      - 'environments/**'
      - 'modules/**'
  pull_request:
    branches: [main]

env:
  TF_VERSION: '1.9.2'
  AWS_REGION: ap-northeast-1

# 并行控制 - 新任务排队 等前面的结束后再运行;
concurrency:
  group: terraform-task
  cancel-in-progress: false


jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Linter 校验检查
      - uses: terraform-linters/setup-tflint@v3
        with:
          tflint_version: v0.53.0

      - run: tflint --format=compact

      # 执行
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      # 语法和格式检查
      - name: Terraform Validate
        run: |
          for env in environments/*/; do
            echo "Validating $env"
            cd $env
            terraform init -backend=false
            terraform fmt -check -recursive
            terraform validate
            cd ../..
          done

  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tfsec
        uses: aquasecurity/tfsec-action@v1.0.0


  plan:
    needs: [validate, security-scan]
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    strategy:
      matrix:
        environment: [dev, staging]
    steps:
      - uses: actions/checkout@v3

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

          # 推荐使用 OIDC 认证
          # role-to-assume: arn:aws:iam::123456789012:role/tf-prod
          aws-region: ${{ env.AWS_REGION }}

      - name: Terraform Plan
        id: plan
        run: |
          cd environments/${{ matrix.environment }}
          terraform init
          terraform plan -no-color -out=tfplan

        # 忽略错误
        # 即使 plan 失败(比如权限不够或逻辑冲突), 也让流水线继续走下去;
        # 这是为了让下一步能把错误信息(如果有的话)反馈给开发者
        continue-on-error: true

      # 调用 GitHub API 在 PR 页面下方自动留言
      # 可以通过 @ 提醒指定人员
      - name: Update PR
        uses: actions/github-script@v7
        if: github.event == 'pull_request'
        with:
          script: |
            const output = `#### Terraform Plan 📖 \n\nplease @${{ github.actor }} review\n\n${{ steps.plan.outputs.stdout }}`;
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: output
            })


  apply:
    runs-on: ubuntu-latest
    environment: production   # 可选, 限制必须需要手动确定后才继续

    # 限制只有当代码真正合并到 main 分支时才会执行; pr 不会执行
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

    strategy:
      matrix:
        environment: [dev, staging]
    steps:
      - uses: actions/checkout@v3

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      # 针对直接变更 main 分支的场景, 也进行一次语法和格式检查
      - name: Terraform Validate
        run: |
          for env in environments/*/; do
            echo "Validating $env"
            cd $env
            terraform init -backend=false
            terraform fmt -check -recursive
            terraform validate
            cd ../..
          done

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-region: ${{ env.AWS_REGION }}
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

          # 推荐使用 OIDC 认证
          # role-to-assume: arn:aws:iam::123456789012:role/tf-prod

      - name: Terraform Apply
        run: |
          cd environments/${{ matrix.environment }}
          terraform init
          terraform apply -auto-approve

gitlib

示例1

.gitlab-ci.yml


stages:
  - validate
  - plan
  - apply
  - cleanup

variables:
  TF_VERSION: 1.8.0
  AWS_DEFAULT_REGION: ap-northeast-1

terraform:validate:
  stage: validate
  image: hashicorp/terraform:${TF_VERSION}
  before_script:
    - cd environments/prod
  script:
    - terraform init -backend=false
    - terraform validate
    - terraform fmt -check
  only:
    - merge_requests
    - main

terraform:plan:
  stage: plan
  image: hashicorp/terraform:${TF_VERSION}
  before_script:
    - cd environments/prod
    - alias aws='aws --region ${AWS_DEFAULT_REGION}'
  script:
    - terraform init
    - terraform plan -out=tfplan
  artifacts:
    name: tfplan
    paths:
      - environments/prod/tfplan
    expire_in: 1 day
  only:
    - merge_requests
    - main

terraform:apply:
  stage: apply
  image: hashicorp/terraform:${TF_VERSION}
  before_script:
    - cd environments/prod
    - alias aws='aws --region ${AWS_DEFAULT_REGION}'
  script:
    - terraform init
    - terraform apply -auto-approve tfplan
  environment:
    name: production
  when: manual
  only:
    - main

示例2

变量注入:
Terraform 配置云 AccessKey, 将 AK/SK 通过 CI/CD 变量注入;

变量说明

Masked 变量在所有 Job 日志中被 [MASKED] 替代，防止泄露
Protected 变量仅在 protected 分支的 Pipeline 中生效
Terraform alicloud provider 自动读取 ALICLOUD_ACCESS_KEY/SECRET_KEY 环境变量

Stage 划分

validate
plan
apply 手动确认
destroy 手动确认

envs/dev.tfvars
envs/prod.tfvars



# .gitlab-ci.yml
# ============================================
# 全局配置
# ============================================
workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_PIPELINE_SOURCE == "web"
default:
  image:
    name: hashicorp/terraform:1.9

    # 覆盖 Terraform 镜像默认入口点
    entrypoint: [""]
  tags:
    - terraform
stages:
  - validate
  - plan
  - apply
  - destroy

# ============================================
# 全局变量
# ============================================
variables:
  TF_ROOT: ${CI_PROJECT_DIR}/terraform-landing-zone
  TF_ENV: "dev"
  TF_INPUT: "false"             # 禁用交互式提示，适配 CI 环境
  TF_IN_AUTOMATION: "true"

# 缓存 Provider 插件
cache:
  key: terraform-${TF_ENV}
  paths:
    - ${TF_ROOT}/.terraform/

# 公共脚本片段
.terraform_init: &terraform_init
  - cd ${TF_ROOT}
  - terraform --version
  - mkdir -p ~/.ssh && echo "${SSH_PUBLIC_KEY}" > ~/.ssh/id_ed25519.pub
  - |
    cat > ~/.terraformrc << 'EOF'
    provider_installation {
      network_mirror {
        url = "https://mirrors.aliyun.com/terraform/"
        include = [
          "registry.terraform.io/aliyun/alicloud"
        ]
      }
      direct {
        exclude = [
          "registry.terraform.io/aliyun/alicloud"
        ]
      }
    }
    EOF
  - terraform init -reconfigure
# ============================================
# Stage 1: 代码验证
# ============================================
fmt:
  stage: validate
  script:
    - cd ${TF_ROOT}
    - terraform fmt -recursive -check -diff
  allow_failure: false
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
validate:
  stage: validate
  script:
    - *terraform_init
    - terraform validate
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# ============================================
# Stage 2: 执行计划
# ============================================
plan:
  stage: plan
  script:
    - *terraform_init
    - terraform plan
      -var-file="envs/${TF_ENV}.tfvars"
      -out="${TF_ENV}.tfplan"
    - terraform show -no-color "${TF_ENV}.tfplan"
      > "${TF_ENV}-plan-output.txt"
  artifacts:
    name: "plan-${TF_ENV}-${CI_COMMIT_SHORT_SHA}"
    paths:
      - ${TF_ROOT}/${TF_ENV}.tfplan
      - ${TF_ROOT}/${TF_ENV}-plan-output.txt
    expire_in: 7 days

    # 在 MR 中显示 plan 摘要
    reports:
      terraform:
        - ${TF_ROOT}/${TF_ENV}-plan-output.txt
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# ============================================
# Stage 3: 部署基础设施
# ============================================
apply:
  stage: apply
  script:
    - *terraform_init
    - terraform apply -auto-approve "${TF_ENV}.tfplan"
  dependencies:
    - plan      # 依赖阶段
  environment:
    name: ${TF_ENV}
    action: start
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual          # 需人工在界面中点击触发
      allow_failure: false
  resource_group: ${TF_ENV}     # 确保同环境不并发执行

# ============================================
# Stage 4: 销毁基础设施
# ============================================
destroy:
  stage: destroy
  script:
    - *terraform_init
    - terraform destroy
      -var-file="envs/${TF_ENV}.tfvars"
      -auto-approve
  environment:
    name: ${TF_ENV}
    action: stop
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual
      allow_failure: true
  resource_group: ${TF_ENV}

#===================================================================

Terraform-Atlantis

chenwx716@139.com — Sat, 20 Sep 2025 12:30:00 +0800

Atlantis

https://github.com/runatlantis/atlantis

一个独立的服务器来负责运行 terrform plan 和 apply

流程

修改代码, 提交到 git dev 分支, 并创建分支合并 MR
git webhook 触发, 将 MR 事件发送给 Atlantis
Atlantis 拉取代码, 并执行 plan
将 plan 的结果以评论的方式发布到 MR 中
团队 Review 后, 有权限的人在 MR 中评论 atlantis apply
Atlantis 执行 terraform apply, 并将结果评论到 MR 中

优势

自动管理 Lock, 同一目录并发操作自动排队 / 拒绝
凭证仅存储在 Atlantis 服务器上
所有 plan 和 apply 结果都作为评论保留在 MR 中
可通过 GitLab 的 Approval 规则和权限控制谁能执行 apply
环境一致性

在 PR 上评论：
atlantis plan
atlantis apply

实践

可以在 ci 流程中进行代码静态检查等操作
实际 plan apply 再由 atlantis 进行操作

多副本部署：Atlantis 支持多副本运行，但需要配置共享的锁后端（如 Redis 或数据库），默认使用内存锁

在 GitLab 中配置 Atlantis

创建 GitLab Access Token

推荐使用 Project Access Token 或 Group Access Token

所需权限(Scopes):
api (完整 API 访问, 用于读写 MR 评论, 读取代码)
或者精细控制: read_repository, write_registry, api (GitLab 目前对 MR 评论写入通常需要 api scope)
角色: 至少需要 Maintainer 角色(如果需要合并 MR)或 Developer(仅评论和 plan)

部署 Atlantis 服务

Atlantis 服务器必须有公网可达的 URL, 因为要 webhook 回调

docker run -d \
   --name atlantis \
   -p 4141:4141 \
   -e ATLANTIS_GITLAB_HOSTNAME=gitlab.com \             # 或你的自建 GitLab 域名
   -e ATLANTIS_GITLAB_TOKEN=<your-gitlab-token> \        # 步骤 1 创建的 Token
   -e ATLANTIS_GITLAB_USER=atlantis-bot \                # Token 对应的用户名
   -e ATLANTIS_GITLAB_WEBHOOK_SECRET=<your-secret> \     # Webhook 验证密钥
   -e ATLANTIS_REPO_ALLOWLIST=gitlab.com/mygroup/* \     # 允许 Atlantis 运行的仓库白名单
   -e ATLANTIS_PORT=4141 \
   -v /path/to/atlantis/data:/home/atlantis \            # 持久化数据(Lock, cloned repos)
   ghcr.io/runatlantis/atlantis:latest server

在 Atlantis 服务器上配置 Terraform 需要的云厂商凭证

配置 GitLab Webhook

进入 GitLab 项目 → Settings → Webhooks

URL: https://your-atlantis-domain.com/events

Secret token: 与 Atlantis 的 ATLANTIS_GITLAB_WEBHOOK_SECRET 保持一致

Trigger（触发事件）
必须勾选：
✅ Merge request events （MR 创建、更新、关闭）
✅ Comments （Note events，用于接收 atlantis apply 等指令）

MR核心工作流

# 开发者本地操作
git checkout -b feature/add-s3-bucket
# 修改 terraform/main.tf ...
git add .
git commit -m"feat: add S3 bucket for logs"
git push origin feature/add-s3-bucket

然后在 GitLab 上创建 Merge Request（源分支 feature/add-s3-bucket → 目标分支 main）

阶段 2：Atlantis 自动 Plan

MR 创建后几秒内，Atlantis 会：
检测到 MR 中修改了 terraform/ 目录下的 .tf 文件
自动在该目录下执行 terraform init 和 terraform plan
将 Plan 结果以评论形式发布到 MR 中：
同时，Atlantis 会锁定该目录（Lock），防止其他 MR 同时修改同一目录导致状态冲突

Code Review
如果代码需要修改

1
2
3

# 开发者修改代码后再次 push
 git commit -am"fix: add encryption to s3 bucket"
 git push origin feature/add-s3-bucket

Atlantis 检测到新的 push，会自动重新执行 Plan 并更新 MR 中的评论

Review 通过后，有权限的用户（通常是 Maintainer 或指定角色）在 MR 评论区输入：

`1`	`atlantis apply -d terraform`

Atlantis 收到指令后：

验证评论者是否有权限执行 apply
执行 terraform apply -auto-approve
将结果评论到 MR 中

合并 MR 与解锁

Apply 成功后，可以手动合并 MR（或配置自动合并）
MR 合并/关闭后，Atlantis 会自动解锁该目录，允许其他 MR 继续操作

常用评论命令速查表

命令必须以 atlantis 开头，且单独成行; 支持在一条评论中写多行命令

命令            说明
atlantis plan               对所有变更目录重新执行 plan
atlantis plan -d <dir>      对指定目录执行 plan
atlantis plan -w <workspace>    对指定 workspace 执行 plan
atlantis apply              对所有已 plan 且未锁定的目录执行 apply
atlantis apply -d <dir>     对指定目录执行 apply
atlantis apply -p <project> 对 atlantis.yaml 中定义的特定项目执行 apply
atlantis unlock             手动解锁当前 MR 锁定的目录
atlantis version            显示 Atlantis 和 Terraform 版本
atlantis help               显示帮助信息

atlantis.yaml

放在仓库根目录的配置文件，用于精细化控制 Atlantis 的行为
对于多环境、多目录、多 Workspace 的复杂项目至关重要

示例：多目录多环境

version: 3

# 项目列表，每个项目对应一个 Terraform Root Module
projects:

    # name 项目唯一标识，用于在评论中通过 -p <name> 指定
   - name: dev-networking

    # Terraform 代码所在目录（相对于仓库根目录）
     dir: environments/dev/networking
     workspace: default                 # Terraform Workspace 名称

     # 定义哪些文件变更会触发自动 Plan
     autoplan:
       when_modified: ["*.tf","*.tfvars","../modules/networking/**/*"]

       # 是否启用自动 Plan（设为 false 则需手动评论 atlantis plan）
       enabled: true

     # 安全控制，定义 Apply 前必须满足的条件
     # approved: MR 必须获得 GitLab Approvals（至少一个 Approve）。这直接集成 GitLab 的审批功能
     # mergeable: MR 必须处于"可合并"状态（即：无冲突、Pipeline 通过、满足 Approval 规则等）
     # unlocked：目录未被其他 MR 锁定
     apply_requirements: ["approved"]

   - name: prod-networking
     dir: environments/prod/networking
     workspace: default
     autoplan:
       when_modified: ["*.tf","*.tfvars","../modules/networking/**/*"]
       enabled: true
     apply_requirements: ["approved","mergeable"]

   - name: dev-app
     dir: environments/dev/app
     workspace: default
     autoplan:
       when_modified: ["*.tf","*.tfvars"]
       enabled: true

自定义 Workflow

可以在 atlantis.yaml 中定义自定义的 plan/apply 步骤，例如集成 terragrunt 或 checkov

version: 3
workflows:
   terragrunt:
     plan:
       steps:
         - env:
             name: TERRAGRUNT_IAM_ROLE
             value: "arn:aws:iam::123456:role/terraform"
         - run: terragrunt plan -out=$PLANFILE
     apply:
       steps:
         - run: terragrunt apply -auto-approve $PLANFILE

projects:
   - name: my-project
     dir: live/production
     workflow: terragrunt

Terraform导入元数据

chenwx716@139.com — Sat, 20 Sep 2025 12:30:00 +0800

导入环境信息到本地状态文件

方案一: 小批量逐个导入

核心逻辑是在配置文件中先声明一个空的资源块,
然后通过命令将远程资源的状态关联进来, 最后再根据实际属性补齐配置

适合导入单个资源

1
2
3

# 注意: 括号内先留空, 不写任何参数
resource "alicloud_vpc" "pro-vpc" {}
resource "alicloud_instance" "app-2" {}

执行导入

1
2
3

# 命令格式: terraform import resource_type.resource_name 线上实际的资源ID
terraform import alicloud_vpc.pro-vpc vpc-abc12345
terraform import alicloud_instance.app-2 i-2ze0kcfjzxynv4545yuz

补齐代码

# 查看当前状态文件内的资源的属性, 并将属性信息选择性拷贝到代码中
terraform show
terraform state show alicloud_vpc.pro-vpc
terraform state show alicloud_instance.app-2

# 补齐代码内的内容, 剔除只读参数(如 id, creation_time 等)

# 直到运行显示 "No changes" 为止
terraform plan

方案二: 小批量逐个导入 - 模块方式导入

module "testmodule" {
  source           = "../modules/instance"
  environment      = "xxx"
  vswitch_info     = "xxxx"
  vpc_id           = "xxxx"
  instance_type    = "xxxx"
  security_groups  = "xxxx"
  service          = "xxxx"
  instance_count   = "xxxxx"
  system_disk_size = "xxxxx"
  system_disk_category = "xxxxx"
  alicloud_availability_zones = "xxxxx"
}

terraform import module.testmodule.alicloud_instance.instance i-xxxxxxxxxxxxxx

# 如果该服务有多个实例，则要指定下标
terraform import module.testlistmodule.alicloud_instance."instance[0]" i-xxxxxxxxxxxxxx

方案三: import 代码块导入

优点是导入这个动作被记录在了代码中

import {
  to = alicloud_vpc.vpc1                # 本地新的资源名称
  id = "vpc-2zekv3mnatn04rognc9sy"      # 真实线上资源ID
}

# 生成指定的资源配置文件 tf
# Terraform 会读取远程 VPC 的属性, 并自动生成一个包含完整参数定义的 generated_vpc.tf 文件
# 注意, 这里并不会更改状态文件; 只是生成了代码
# 这里这个代码文件不一定完全合适, 可能还需要手工调整一下
terraform plan -generate-config-out=generated_vpc.tf

# 检查生成的配置文件内容, 确认无误后

# 将真实资源关联到状态文件 - 即写入状态文件
terraform import alicloud_vpc.vpc1 vpc-2zekv3mnatn04rognc9sy

# 验证 - 此时应该是 No changes
terraform plan

terraform state list

方案四: Terraformer

1
2
3

https://github.com/GoogleCloudPlatform/terraformer

terraformer-alicloud-linux-amd64

import  # 将当前状态导入 Terraform configuration; 默认输出在 generated 目录下
plan    # 预览导入

--resources         # 指定要导入的资源集合
--regions           # 指定资源所在地域
--path-pattern      # 生成的目录模式
--path-output       # 目录文件路径
--compact           # 将资源都输出到 resources.tf 一个文件中

terraformer-alicloud-linux-amd64 plan alicloud list

# 扫描阿里云北京区域的所有 ECS 实例
# 会在本地生成一个包含 terraform.tfstate 和 *.tf 文件的文件夹
terraformer import alicloud --resources=ecs --regions=cn-beijing

# 指定安全组
terraformer import alicloud --resources=sg --ids=sg-abc12345

# 区域的全部安全组
terraformer import alicloud --resources=sg --regions=cn-beijing

# 导入多种资源
terraformer import alicloud --resources=vpc,sg --regions=cn-beijing

aws

terraformer import aws -r sg,vpc \
    --filter Type=sg;Name=vpc_id;Value=VPC_ID --filter Type=vpc;Name=id;Value=VPC_ID

terraformer import aws --resources=vpc,subnet --filter=vpc=myvpcid --regions=eu-west-1

terraformer import aws --resources=s3 --filter="Name=tags.Abc" --regions=eu-west-1

`1`	`terraformer plan google --resources=networks,firewall --projects=my-project --regions=europe-west1-d`

方案五: aliterraformer 阿里云

是 Terraformer 的阿里云版本

1
2
3

https://help.aliyun.com/zh/terraform/import-resources-into-terraform

wget https://terraform-share.oss-cn-hangzhou.aliyuncs.com/aliterraformer/aliterraformer_linux_amd64.zip

配置供应商

terraform {
  required_providers {
    alicloud = {
      source  = "aliyun/alicloud"
      version = "~>1.272.1"
    }
  }
}

cli

# 若本地的 Terraform 版本 >=0.13.0，需要执行以下命令来对状态文件进行修改以适配新版本 Terraform
terraform state replace-provider -auto-approve "registry.terraform.io/-/alicloud" "aliyun/alicloud"


# 查看当前版本支持导入的产品列表
aliterraformer products

# 查看当前版本某一产品下支持导入的资源列表
aliterraformer resources -p <productName>

# 查看导入参数
aliterraformer import alicloud -h


# 导入 vpc、vswitch、ECS 实例
aliterraformer import alicloud -r=vpc,vswitch,instance

# 导入 ACK、ALB 产品下所有资源
aliterraformer import alicloud --products=ACK,ALB

# 导入 ACK、ECS 产品下所有资源以及所有 vpc、vswitch
aliterraformer import alicloud --products=ACK,ECS -r=vpc,vswitch

# 导入 ACK 下除 alicloud_cs_kubernetes 外所有资源
aliterraformer import alicloud --products=ACK --excludes=cs_kubernetes

# products 输入 ALL 代表所有的产品
aliterraformer import alicloud --products=ALL

# 导入除 VPNGateway,WAF 外的所有产品
aliterraformer import alicloud --products=ALL --excludes-products=VPNGateway,WAF

# 导入除 VPNGateway,WAF 外的所有产品，排除 alicloud_cs_kubernetes 资源
aliterraformer import alicloud --products=ALL --excludes-products=VPNGateway,WAF --excludes=cs_kubernetes

实践



export ALICLOUD_REGION=cn-beijing

# 查看 ack 模块可以导入的资源
aliterraformer resources -p ACK

# 多个资源 导入 - 有失败的
aliterraformer import alicloud --products=ACK,ALB,AutoScaling,VPC,EIP,ECS,NATGateway,OSS,CDN,RAM,Alidns,SLS


# 按模块单独导入
aliterraformer resources -p VPC
aliterraformer import alicloud --products=VPC --excludes=vpc_ha_vip

aliterraformer import alicloud --products=ALB --excludes=alb_listener_additional_certificate_attachment

aliterraformer resources -p ECS
aliterraformer import alicloud --products=ECS

aliterraformer resources -p EIP
aliterraformer resources -p NATGateway
aliterraformer import alicloud --products=EIP,NATGateway

aliterraformer resources -p OSS
aliterraformer import alicloud --products=OSS

aliterraformer resources -p Alidns
aliterraformer import alicloud --products=Alidns

aliterraformer resources -p CDN
aliterraformer import alicloud --products=CDN

Terraform函数

chenwx716@139.com — Sat, 20 Sep 2025 12:30:00 +0800

HCL
- 表达式
- 内置函数

HCL

HCL(HashiCorp Configuration Language)作为核心语言

配置文件支持两种格式:

HCL(HashiCorp Configuration Language), 文件名以 .tf 结尾
JSON, 文件名以 .tf.json 结尾

表达式

条件表达式

`1`	`condition ? true_val : false_val`

for 表达式

1
2

[ for VAR in OBJECT : VAR]
[ for INDEX, VAR in OBJECT: "${INDEX}=${VAR}"]

for 表达式创建对象

output "vpc_ids" {
  value = {
    for k, v in alicloud_vpc.example : k => v.id    # 这个 => 就是赋值的意思
  }
}

splat 表达式

比用 for 表达式更简洁的循环方式

内置函数

Terraform 语言包括许多内置函数, 可以从表达式中调用这些函数来转换;
function(arg1,arg2)

数值类

计算函数

max(12, 54, 3)
min(12, 54, 3)
ceil(5.2) –> 6 # 向上取整
floor(4.5) –> 4 # 向下取整
pow(3, 2) –> 9 # 计算指数幂
abs(number)
log(16, 2) –> 4 # 除

parseint() # 进制转换, 解析字符串数字为对应进制的整数
parseint(“100”, 10)
parseint(“FF”, 16) –> 255
parseint(“aA”, 62) –> 656

示例

output "my_func1" {
  value = {
    f1 = [max(1, 2, 3), min(7, 8, 9), parseint("111", 2)],
    f2 = [max([1, 2, 3]...), min([7, 8, 9]...), parseint("111", 2)]
  }
}

字符串

format() 按指定格式拼接字符串 format(“Hello, %s!”, “Terraform”)
lower()
upper()
title(“hello world”) # 首字母大写

join() 用分隔符将字符串列表拼接为一个字符串; join(", “, [“a”, “b”, “c”])
split() 将字符串按分隔符拆分为列表
substr() 从字符串中截取子串 substr(“hello world”, 0, 5)
replace() 替换字符串中的内容
chomp(“hello\r\n”) –> hello
endswith(string, suffix)

trimspace(“a b c”) –> “abc” # 清理空格
trimprefix(“dev-server”, “dev-”) –> server # 清除前面的字符
trimsuffix(“user.txt”, “.txt”) –> user # 清除后面的字符

output "my_func2" {
  value = {
    f1 = format("Hello %s!", "anliven"),
    f2 = join(":", ["name", "age", "title"]),
    f3 = replace("a=b=c", "=", "–"),
    f4 = split(",", "name,age,title")

  }
}

set-map

element() 通过索引获取列表中的某个元素 element([“a”, “b”, “c”], 1)
length() 获取列表、映射或字符串的长度 length([“a”, “b”, “c”])
lookup(map,key,default) 在映射中查找键的值，若不存在则返回默认值 lookup({a=“A”, b=“B”}, “c”, “C”)
keys() 返回映射的所有键组成的列表 keys({a=1, b=2})
values(map) 创建map中value的list

merge(map1,map2,map3) 合并多个映射或对象, 相同key会被最后覆盖 merge({a=1}, {b=2})
flatten() 将嵌套的列表展开为单层列表 flatten([[“a”], [“b”, “c”]])

alltrue() 判断元素中都是 true
anytrue() 判断元素中存在 true

chunklist(list, size) 按照指定size拆分list

compact(list) 去除list中的空元素
concat(list1, list2) 合并两个list
contains(list, value) 判断元素是否存在list中
distinct(list) 去除list中的重复元素

list[index] 根据index获取list中的元素

index(list, value) 返回value元素的index

sort([“z”, “b”, “a”]) # 排序

toset() # 将字符串列表转换为集合, 会丢弃顺序并删除重复元素

示例


locals {
  list1 = [1, 2, 3]
  list2 = [7, 8, 9, null]
  list3 = ["a", "b", "c", "a", "b", "c"]
}
//内置Collection集合函数
output "my_func3" {
  value = {
    p1 = alltrue([true, false]) //判断元素中都是true
    p2 = anytrue([])            //判断元素中存在true

    p3  = chunklist(["a", "b", "c"], 2)      //按照指定size拆分list
    p4  = compact(local.list2)               //去除list中的空元素
    p5  = concat(local.list1, local.list2)   //合并两个list
    p7  = distinct(local.list3)              //去除list中的重复元素
    p8  = element(local.list3, 0)            //根据index获取list中的元素
    p9  = flatten([[["a", "b"], []], ["c"]]) //将多层list转换成单list
    p10 = index(local.list3, "c")            //返回value元素的index, 返回第一个匹配的索引

    p11 = length({ "a" = 1, "b" = 2 })                      //计算string、list、map的长度
    p12 = lookup({ a = "111", b = "222" }, "c", "what?")    //检索map的key，不存在返口default
    p13 = merge({ a = "b", c = "d" }, { e = "f", c = "z" }) //合并map，相同key会被最后覆盖
    p14 = keys({ a = 1, c = 2, d = 3 })                     //创建map中key的list
    p15 = values({ a = 3, c = 2, d = 1 })                   //创建map中value的list

    p6  = contains(local.list2, 9)      # 判断元素是否存在list中
    p16 = contains(["us-east-1", "us-west-2"], var.region)

  }
}

正则

regex() # regex("[0-9]+”, “env42-prod”)
regexall() # 多次

编码和加解密

base64decode()
base64encode()
base64gzip()
csvdecode
jsondecode
jsonencode
textdecodebase64
textencodebase64
urlencode
yamldecode
yamlencode

brypt
bash64sha256
bash64sha512
filebase64sha256
filemd5
filesha1
filesha256
md5
sha1
sha256
sha512
uuid
uuidv5

路径和文件名

bashpath
dirname
pathexpand
basename
file() 读取文件的内容 value = file("${path.module}/config.json")
fileexists
fileexists
filebase64
templatefile() 动态渲染模板

templatefile

nginx.conf.tmpl 原始文件内容
server {
  listen 80;
  server_name ${domain};
}

output "nginx_config" {
  value = templatefile("${path.module}/nginx.conf.tmpl", {
    domain = "example.com"  # 变量渲染
  })
}

时间

formatdate
plantimestamp
timeadd
timecmp
timestamp

ip

cidrhost
cidrnetmask
cidrsubnet() # 子网计算
cidrsubnets()

cidrsubnet 从 CIDR 生成子网

cidrsubnet(原始网段, 掩码, 子网步长)

default = cidrsubnet(“172.20.0.0/16”, 8, 36) # 最终等于 172.20.36.0/24

理解

172.20.0.0/16
16+8=24
将 “172.20.0.0/16” 拆成 24 个子网
使用第 36 个子网

cidrsubnet(“10.0.0.0/16”, 8, 1) –> “10.0.1.0/24”
cidrsubnet(“10.0.0.0/16”, 8, 2) –> “10.0.2.0/24”

技巧

展开参数 …

把列表中的值作为多个参数传给函数时，可以在列表后加 …

1
2

# 等同于 min(1, 2, 3)
min([1, 2, 3]...)

Terraform核心对象

chenwx716@139.com — Sat, 20 Sep 2025 12:30:00 +0800

核心对象

核心对象

resource 资源
data 数据源
locals 局部变量
output 输出和模块导出
variable 变量
ephemeral 临时变量
moved 移动资源, 即重命名
removed 只删除本地状态内的对象, 不影响云上资源

resource 资源

资源定义

“资源模块名 + 状态名称” 需要全局唯一

`1`	`resource "资源模块名" "状态名称" {}`

元参数

每种资源都可用

resource "xxxxx" "xxxxx" {
    # 显式声明依赖关系
    depends_on: []
    # 创建多个资源实例
    count:

    # 迭代集合, 为集合中每一个元素创建一个对应的资源实例
    for_each:

    # 指定非默认 Provider 实例
    provider:

    # 自定义资源的生命周期行为
    lifecycle:

    # 默认是在资源 创建时执行 执行一些额外的操作
    provisioner:

    在资源创建后执行一些额外的操作
    connection:
}

如果创建的资源实例彼此之间几乎完全一致，那么 count 比较合适
如果多个资源参数差异较大, 那么使用 for_each 会更加安全合适

count

count 元参数接受一个整数, 并创建相应数量的资源或模块实例

一个资源或 Module 块不能同时使用 count 和 for_each
标号从 0 开始

示例: 创建4个主机


variable "host_names" {
  description = "List of host name prefixes"
  type        = list(string)
  default     = ["web", "app", "db"]
}

resource "aws_instance" "server" {
  count = length(var.host_names)        # 3
  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"

  # sever-web-1
  # sever-app-2
  # sever-db-3
  instance_name   = "server-${var.host_names[count.index]}-${count.index + 1}"

  tags = {
    Name = var.host_names[count.index]  # 读取标号
  }
}

output "my_server_1" {
  value = {
    data = aws_instance.server[0]   # 只引用了单个实例
  }
}

使用 count 条件式创建资源

variable "create_slb" {
  description = "Whether to create SLB"
  type        = bool
  default     = true
}

resource "alicloud_slb_load_balancer" "app" {
  # 只有当 create_slb = true 时创建资源; 即为 true 时, count 的值 = 0
  count = var.create_slb ? 1 : 0

  load_balancer_name = "app-lb"
  address_type       = "internet"
  load_balancer_spec = "slb.s2.small"

  tags = {
    Name = "ApplicationLB"
  }
}

for_each

针对集合类型(set) 或映射(map) 进行迭代创建资源

核心在于每个资源有一个固定的标识符 key, 这使得 Terraform 能够精确跟踪单个资源实例, 即使底层集合的顺序发生变化;

一个 resource 块不允许同时声明 count 与 for_each
不能直接使用列表(list), 需要转换为 set

each 对象
each.key — 对应于此实例的映射键(或集合成员); 必须是已知值, 不能是生成值;
each.value — 对应于此实例的映射值; (如果提供的是集合, 则与 each.key 相同; )

resource "xxxxx" "rg" {
  # map 映射
  for_each = {
    a_group = "eastus"
    b_group = "westus2"
  }
  name     = each.key
  location = each.value
}

# list to set
resource "xxxx" "the-accounts" {
  for_each = toset( ["Todd", "James", "Alice", "Dottie"] )
  name     = each.key
  display_name = "User ${each.key}"

}

示例2

variable "vpcs" {
  type = map(object({
    cidr_block = string
    zone_id    = string
  }))
}

resource "alicloud_vpc" "example" {
  for_each = var.vpcs
  vpc_name   = each.key
  cidr_block = each.value.cidr_block
}

resource "alicloud_vswitch" "example" {

  # 因为此时 alicloud_vpc.example 可以理解为就是一个 map 对象了;
  for_each = alicloud_vpc.example

  # each.value 是一个完整的 alicloud_vpc 对象
  vpc_id      = each.value.id

  # 此处理解为是从具体的 vpc 资源里面获取的 cidr_block 的值, 而不是从 vpcs 这个map里面获取的值
  cidr_block  = cidrsubnet(each.value.cidr_block, 8, 0)

  # each.key 是通过 alicloud_vpc.example 继承下来的; 反查 vpcs 里面的 value
  zone_id     = var.vpcs[each.key].zone_id
  vswitch_name = "${each.key}-default-vswitch"
}

output "vpc_ids" {
  value = {
    for k, v in alicloud_vpc.example : k => v.id
  }
}

在 for_each = alicloud_vpc.example 这一步时, 也一并继承了其关联的 vpcs 的键;
所以在 zone_id = var.vpcs[each.key].zone_id 这一步时能通过正确的key名进行查询;

示例3: 有时候需要 list to set

1
2
3

locals {
  vswitch_ids = toset(["vsw-abc123456", "vsw-def789012"])
}

lifecycle 生命周期

  lifecycle {

    # 忽略某些差异
    ignore_changes = [
      tags,
    ]

    # 运行前校验
    postcondition {
      condition     = self.tags["Component"] == "nomad-server"
      error_message = "tags[\"Component\"] must be \"nomad-server\"."
    }
  }

provisioner

默认是资源创建时执行

resource "aws_instance" "server" {
  provisioner "local-exec" {
    when    = destroy       # 设定为资源销毁时执行
    command = "echo 'Destroy-time provisioner'"
  }
}

变量

变量类型

基础类型:

string
number
bool

复合类型:

list() 本身是有序的
set() 一组不重复的值
map() 键类型必须是 string;
any: 任意类型
object((ATTR_NAME = ATTR_TYPE, …))
tuple([,…])

map 只是kv结构, object 才是嵌入结构

变量引用: var.VAR_NAME

变量传入和优先级

默认值 variable 中的 default 值
文件 *.tfvars, *.tfvars.json, *.auto.tfvars, *.auto.tfvars.json
有 TF_VAR_ 的名称开头的系统环境变量会进行关联
命令行参数, -var 选项传递变量, -var-file 选项加载一个变量文件
当没有默认值, 且没有传入时, 会要求手动输入

注意: 其它非 TF_VAR_ 的名称开头变量是供应商模块运行所需自行读取的, 与用户自定义变量无关;

-var region=us-east-1
-var-file my-vars.tfvars
-var='image_id_list=["ami-abc123","ami-def456"]'
-var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}'

export TF_VAR_xxx=xxxxx

默认变量文件

.tfvars
.tfvars.json
terraform.tfvars
terraform.tfvars.json
.auto.tfvars
.auto.tfvars.json

variable 变量

variable "image_id" {
  type        = string          # 类型 string, number 等
  description = ""              # 描述
  default = "cn-beijing"        # 变量的默认值
  nullable = false              # 变量是否可为空, 禁止为 null
  sensitive = false             # 是否为秘密, 为 true 时输出时隐藏显示且不记录到日志

  # 定义变量验证规则, 为 true 时输入变量合法
  validation {

    # 验证条件
    # 验证 image_id 的值是否长度超过 4 并且是否以 ami- 为开头
    condition     = length(var.image_id) > 4 && substr(var.image_id, 0, 4) == "ami-"

    # 验证失败后的消息输出
    error_message = "The image_id value must be a valid AMI id, starting with \"ami-\"."
  }
}

variable "env_list" {
  type        = list(string)
  description = "define environment name"
  default     = ["dev"]
}

variable "dns_record" {
  type        = map(string)
  description = "define dns name"
}

variable "ecs_info" {
  type = object({
    ecs_image = string,
    ecs_name  = string
  })
  description = "define ecs info"
}

ephemeral 临时变量

针对敏感秘密的场景, 不进行任何形式的持久化;

不在 console 和 log 文件中
不在 plan 计划文件中
不在状态文件中
只能在特定上下文中引用临时变量

locals 局部变量

通过 locals 关键字进行定义, 通过 local.VAR_NAME 调用

局部值有助于避免在配置中多次重复相同的值或表达式, 多用于调试和测试

场景:
用一个比较复杂的表达式计算某一个值，并且反复使用，
这时把这个复杂表达式赋予一个局部值，然后多次引用该局部值

locals {
  test_var1 = "local test1"
  test_var2 = "local test2"
}

output "local_var" {
  value = local.test_var1       # 注意使用时是 local 而不是 locals
}

data 数据源

需要从其它地方查询数据的情况

从 remote state 获取
使用数据源查询 - 这种方式是从云 api 获取的数据

data "aws_ami" "example" {
  most_recent = true

  owners = ["self"]
  tags = {
    Name   = "app-server"
    Tested = "true"
  }
}

output "xxxx" {
  value = data.aws_ami.example.outputs.id
}

// 查询名称是GA的分布式交换机
data "vsphere_distributed_virtual_switch" "vds" {
  name          = "GA"
  datacenter_id = data.vsphere_datacenter.datacenter.id
}

// 查询名称是NET1的分布式交换下端口组
data "vsphere_network" "network" {
  name          = "NET1"
  distributed_virtual_switch_uuid =  data.vsphere_distributed_virtual_switch.vds.id
  datacenter_id = data.vsphere_datacenter.datacenter.id
}

跨 State 状态文件共享数据

读取另外一个 tf 项目状态文件的输出;
注意另一个项目需要定义好对应的 output;

因为 output 的内容实际上是存储在状态文件中的, 所以远程调用时, 实际是从文件里面获取的数据内容;

data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = "my-tf-state"
    key    = "network/terraform.tfstate"
    region = "us-west-2"
  }
}

output "vpc_id" {
  value = data.terraform_remote_state.network.outputs.vpc_id
}

数据源查询

实际上是云 saas 接口查询的数据

# 查询 VPC 信息
data "alicloud_vpcs" "default" {
  ids = [data.terraform_remote_state.pro.outputs.vpc_id]
}

# 然后在规则中使用
cidr_ip = data.alicloud_vpcs.default.vpcs[0].cidr_block

aws 常用示例

# 查询当前账号信息
data "aws_caller_identity" "current" {}

output "account_id" {
  value = data.aws_caller_identity.current.account_id
}


# 查询可用区列表
data "aws_availability_zones" "available" {
  state = "available"
}

# 查询最新 Amazon Linux 2 AMI
data "aws_ami" "amazon_linux_2" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
  }
}

# 查询私有子网 ID
data "aws_subnet_ids" "private" {
  vpc_id = var.vpc_id

  tags = {
    Type = "private"
  }
}

http查询

通过 http 协议去获取一个内容

https://registry.terraform.io/providers/hashicorp/http/latest/docs/data-sources/http

data "http" "example" {
  url = "https://checkpoint-api.hashicorp.com/v1/check/terraform"
  method = "HEAD"       # GET, POST

  request_headers = {
    Accept = "application/json"
  }

  request_body = "request body"

  lifecycle {
    postcondition {
      condition     = contains([201, 204], self.status_code)
      error_message = "Status code invalid"
    }
  }

  ca_cert_pem = ""
  insecure = true
  # request_timeout_ms = 1000
}

output

资源的输出值, 也是可导出属性, 可在 Terraform 配置的其他地方被引用
输出值类似于编程语言中的返回值;

root 模块引用子模块内容时, 必须要子模块定义输出

sensitive 特别说明

不在 console 输出
不在 log 日志中
在 plan 计划中
在状态文件中

output "vswitch_id" {
  value = alicloud_vswitch.main_vswitch.id
  description = "描述"
  sensitive = true      # 是否敏感信息
  depends_on = []       # 依赖关系

  ephemeral   = true    # 临时值, 不要持久化到状态文件

  # 断言条件
  precondition = ""
}

查看敏感输出

`1`	`terraform output -json \| jq '.db_password.value' -r`

内部资源

random_id

生成唯一后缀以避免存储桶名称冲突

resource "random_id" "suffix" {
  byte_length = 4
}


output "my_func1" {
  value = {
    data = ${random_id.suffix.hex}
  }
}

local_file 本地文件

resource “local_file” “example” {
content = “Hello Terraform”
filename = “${path.module}/hello.txt”
}

moved 移动资源, 即重命名

只会修改本地状态

moved {
    from = <old address for the resource>
    to = <new address for the resource>
}

removed

从 tf 文件中删除资源, 但不希望删除云上的资源时, 标记需要删除状态

removed {
  from = aws_instance.example
  lifecycle {
    destroy = false
  }
}

removed {
  from = "<resource.address>"       # 指定了你想移除的资源地址
  lifecycle {
    destroy = < true || false >     # false, 在不实质删除的情况下移除托管
  }
  connection {
    <connection-settings>
  }
  provisioner "<TYPE>" {
    when = destroy
    <provisioner-type-arguments>
  }
}

can 与 try 错误处理

用于优雅处理可能的出错表达式

can: 成功时返回 true；失败时返回 false
做条件判断，根据表达式是否成功来决定后续逻辑
不抛出错误，只返回布尔值供你判断

try: 成功时返回表达式的值；失败时返回你指定的默认值
为可能失败的表达式提供后备值，让配置继续执行
静默失败，使用你给的默认值

try(表达式1, 表达式2, …)
会按顺序尝试执行所有表达式，并返回第一个成功执行的表达式的结果

can 示例

locals {
  server_data = {
    name = "web-server"
    # disk = "100GB"
  }

  has_disk = can(local.server_data.disk)    # 检查磁盘信息是否存在
}

# 只有当 has_disk 为 true 时，才创建磁盘资源
resource "alicloud_disk" "example" {
  count = local.has_disk ? 1 : 0
  name  = "data-disk"
  size  = local.server_data.disk
}

# 输入验证
variable "env" {
  type = string
  validation {
    condition     = can(regex("^(dev|staging|prod)$", var.env))
    error_message = "环境必须是 dev/staging/prod"
  }
}

try 示例

locals {
  instance_info = {
    id = "i-123456"
    # region = "us-east-1"  # 假设这个字段不存在！
  }

  # 使用 try 安全地获取 region, 如果不存在则使用 "unknown"
  region = try(local.instance_info.region, "unknown")
}

variable "instance_type" {
  default = "t2.micro"
}

output "safe_lookup" {
  value = try(var.instance_type, "t3.micro")    # 如果没有定义则为 t3.micro
}

Secrets敏感信息处理

输出时标记此为敏感信息, 注意状态文件内还有明文

output "db_password" {
  value     = aws_db_instance.main.password
  sensitive = true
}

使用 AWS Secrets Manager 或 HashiCorp Vault 存储敏感数据

data "aws_secretsmanager_secret_version" "db_creds" {
  secret_id = "prod/db-password"
}

resource "aws_db_instance" "main" {
  # 从 Secrets Manager 获取密码, 而非明文存储
  password = data.aws_secretsmanager_secret_version.db_creds.secret_string
}

ephemeral 方式管理

ephemeral "vault_kv_secret_v2" "proxmox_auth" {
  mount = "homelab"
  name  = "infra/proxmox/local-cluster/auth"
}

Terraform状态管理

chenwx716@139.com — Sat, 20 Sep 2025 12:30:00 +0800

tfstate状态管理

tfstate状态管理

状态文件

即期望的线上环境状态;

代码有 + 状态无 = 需要新增资源
代码无 + 状态有 = 需要删除资源

状态文件内记录着代码和输入的全部信息, 也包含输入的全部明文密码;

文件安全

支持加密存储的远程后端
敏感信息分级, 避免非常敏感的数据被存入状态

管理cli

# 迁移状态文件到 新定义的后端, 数据不会丢失
terraform init -migrate-state

# 重新配置后端, 不会迁移状态文件
terraform init -reconfigure -backend-config="conn_str=$PGURL"

terraform plan

  + create                                  # 创建资源
  - del                                     # 删除资源
  ~ update in-place                         # 原地更新资源属性, 安全
-/+ destroy and then create replacement     # 删除后创建

漂移处理

场景: 未通过 tf 修改了云上资源

# 生成计划查看当前状态与配置的差异
terraform plan -out=tfplan

# 方法 1: 以本地为准
terraform apply

# 方法 2: 以云上为准, 逐个确认
# 生成一个计划, 告诉哪些地方发生了"漂移", 并询问是否要将这些变化写入状态文件
# 注意: 只是合并到了状态文件, tf 代码还得手动写一份
terraform plan -refresh-only

# 确保没有任何差异
terraform plan

状态管理实践

1阶段, 单人维护某项目, 本地存储 terraform.tfstate
2阶段, 状态文件可以提交到 git 但是需要扫描避免泄漏密钥等信息
3阶段, cicd串行执行 apply, 避免人工执行变更
4阶段, 远程存储+锁机制, 在加cicd串行
5阶段, 权限控制, 只允许cdcd进行 apply

企业内网环境: 可以使用 pg
gitlib/gitea 等仓库存储, 适合统一规范时

后端

其它支持: gcs oss,

local

# 默认的配置
terraform {
  backend "local" {
    path = "terraform.tfstate"
  }
}

# 数据源查询
data "terraform_remote_state" "base" {
  backend = "local"  # 使用 local 后端

  config = {
    # 相对于当前执行目录的路径
    path = "../01-base/terraform.tfstate"
  }
}

gitea

1.26+ 开始支持

Settings -> Applications 中生成一个 Access Token

state_name: 状态文件的名称(例如 pve-cluster-prod); 建议每个独立的 .tf 项目对应一个唯一的名称

terraform {
  backend "http" {
    # Gitea 地址, 所有者和仓库名
    address        = "https://git.services.wait/api/v1/packages/chenwx/terraform/state/local-pve"
    lock_address   = "https://git.services.wait/api/v1/packages/chenwx/terraform/state/local-pve/lock"
    unlock_address = "https://git.services.wait/api/v1/packages/chenwx/terraform/state/local-pve/lock"

    # 鉴权配置
    username = "chenwx"
    password = "564ad2cd0112723ed85730e85a4aa2115b8fedc8" # 填入生成的 Token
  }
}

postgres

注解

schema 默认是 terraform_remote_state 用于区分不同项目
表名固定为 states

创建库

`1`	`CREATE DATABASE tfstate_db OWNER wait;`

terraform {
  backend "pg" {
    conn_str = "postgres://wait:passw0rd@192.168.5.9:5432/tfstate?sslmode=disable"
    # schema_name = "terraform_remote_state"
  }
}

pg 后端支持的入参方式

backend.conn_str 固定

init -backend-config 时传递

`1`	`terraform init -backend-config="conn_str=postgres://user:pass@db:5432/db?sslmode=disable"`

环境变量传递

`1`	`export PG_CONN_STR=postgres://wait:passw0rd@192.168.5.9:5432/tfstate_db?sslmode=disable`

使用外部配置文件 (.tfbackend)

1
2

# secret.pg.tfbackend
conn_str = "postgres://user:pass@db:5432/db?sslmode=disable"

`1`	`terraform init -backend-config=secret.pg.tfbackend`

vault

1
2

# 从 vault 内获取连接字符串
export PG_CONN_STR=$(vault kv get -field=conn_str homelab/infra/postgres/tf)

s3

方案 1: s3 + DynamoDB
方案 2: s3 + s3 原生锁

HashiCorp 官方已经宣布 DynamoDB 做状态锁的方式会被废弃, 未来推荐用 S3 原生锁

s3 原生锁

会通过自动创建和删除 .tflock 文件进行状态锁定
桶必须在创建时就启用对象锁(Object Lock)功能和版本功能

原生锁的原理
通过 If-None-Match 机制在文件不存在时才创建, 第一个任务执行成功时获取到了文件锁, 执行完成后会删除此文件;
但是如果执行到一半退出, 不一定会释放成功;

对象锁: 目的为了避免意外删除;

# 创建启用对象锁的存储桶
aws s3api create-bucket --bucket your-terraform-state-bucket --region us-east-1 \
  --object-lock-enabled-for-bucket

# 启用版本控制 (原生锁的强依赖)
aws s3api put-bucket-versioning --bucket your-terraform-state-bucket \
  --versioning-configuration Status=Enabled

# 对于已经存在的桶-启用对象锁
aws s3api put-object-lock-configuration --bucket your-existing-bucket \
    --object-lock-configuration '{"ObjectLockEnabled": "Enabled"}'

terraform {
  backend "s3" {
    bucket         = "your-terraform-state-bucket"
    # 多环境可以共用一个桶, 但 key 需要区分开
    key            = "path/to/your/statefile.tfstate"
    region         = "us-east-1"
    encrypt        = true
    use_lockfile   = true   # 启用 S3 原生锁定
  }
}

DynamoDB 锁

# create bucket
aws s3 mb s3://my-terraform-state --region ap-northeast-1

# 启用版本控制
aws s3api put-bucket-versioning --bucket my-terraform-state \
    --versioning-configuration Status=Enabled

# DynamoDB 表必须预先创建并配置主键 LockID
aws dynamodb create-table \
    --table-name terraform-state-locks \
    --attribute-definitions AttributeName=LockID,AttributeType=S \
    --key-schema AttributeName=LockID,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST

terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    region         = "ap-northeast-1"
    key            = "prod/vpc/terraform.tfstate"
    region         = "ap-northeast-1"
    dynamodb_table = "terraform-state-locks"    # 状态锁表
    encrypt        = true                       # 启用加密
	# kms_key_id     = "alias/terraform-kms"
	# profile        = "terraform" 		    # 可选
    # 可选, 使用 assume role
    # role_arn       = "arn:aws:iam::ACCOUNT_ID:role/TerraformRole"
  }
}

s3 管理cli

启用版本控制时的快速回滚

# 查看状态版本历史
aws s3api list-object-versions --bucket my-terraform-state \
    --prefix network/terraform.tfstate

# 回滚到特定版本
aws s3api get-object --bucket my-terraform-state \
    --key network/terraform.tfstate \
    --version-id <version-id> \
    terraform.tfstate

意外锁定时的处理流程


# 1. 查看资源锁定状态
aws ec2 describe-vpc-attribute --vpc-id vpc-0abcd1234ef567890 \
    --attribute enableDhcpOptions

# 2. 如果是 Terraform 状态锁定, 检查 DynamoDB
aws dynamodb get-item --table-name terraform-locks \
    --key '{"LockID": {"S": "project-terraform"}}'

# 子目录时
aws dynamodb get-item --table-name terraform-state-lock \
  --key '{"LockID":{"S":"my-terraform-state-bucket/prod/terraform.tfstate-md5"}}'


# 扫描 DynamoDB 表中 LockID
aws dynamodb scan --table-name terraform-lock

# 3. 强制解锁(仅在确认无其他 Terraform 进程时)
terraform force-unlock <lock-id>

minio

terraform {
  backend "s3" {
    bucket         = "terraform"
    key            = "homeLab/proxmox/terraform.tfstate"
    region         = "us-east-1"
    endpoints = {
        s3 = "https://minio.chenwx.top"
    }
    skip_requesting_account_id = true       # 不尝试获取 AWS 账号 ID
    skip_credentials_validation = true
    skip_metadata_api_check     = true

    # MinIO 通常需要使用路径风格, 即 bucket 在 路径中而不是子域名里面
    force_path_style            = true
    use_lockfile                = true      # 原生文件锁
    encrypt                     = false     # 本地没有加密

    access_key=""
    secret_key=""
  }
}

1
2

export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=

HCP Terraform

官方远程状态管理

免费额度: 500元, 按资源数计费

terraform {
  cloud {
    organization = "my-org"
    workspaces {
      name = "dev-workspace"
    }
  }
}

阿里云 oss

创建 alicloud_oss_bucket, alicloud_ots_instance, alicloud_ots_table 资源
将代码配置添加到一个名为 backend.tf 的新 Terraform 配置文件中, 接着运行 terraform init
不需要考虑冲突时, 也可以不配置 tablestore_endpoint 和 tablestore_table

表格存储: 实例和表需要提前创建好, 表里必须有一个主键列, 名称为 LockID, 类型为字符串(String)

terraform {
  backend "oss" {
    bucket = "bucket-for-terraform-state"
    prefix   = "tf/state"
    key   = "pro.tfstate"
    region = "cn-beijing"

    tablestore_endpoint = "https://terraform-remote.cn-hangzhou.ots.aliyuncs.com"
    tablestore_table = "statelock"
  }
}

读取另一个项目的状态数据文件

terraform_remote_state 是专门为远程后端设计的数据源

一般数据源方式

data "terraform_remote_state" "base" {
  backend = "oss"
  config = {
    bucket = "my-terraform-state"
    key    = "dev/01-base/terraform.tfstate"
    region = "cn-beijing"
  }
}

resource "alicloud_instance" "web" {
  vswitch_id = data.terraform_remote_state.base.outputs.vswitch_id
  # ...
}

http

http 远程后端 - 只读;

需要自己去维护这个 http 远程文件是否是最新状态

data "terraform_remote_state" "base" {
  backend = "http"

  config = {
    address = "http://localhost:8080/terraform.tfstate"
  }
}

Terraform综合

chenwx716@139.com — Sat, 20 Sep 2025 12:30:00 +0800

Terraform

基础设置即代码, 管理多云环境

一款基础设施即代码(Infrastructure as Code, IaC)工具
描述和管理云端, 本地, 混合环境中的资源, 实现了可重复, 可审计, 可共享的基础设施管理模式

https://developer.hashicorp.com/terraform

# 社区模板
https://registry.terraform.io/
https://registry.terraform.io/modules/

# opentofu
是 Terraform 的一个分支, 由社区驱动
https://opentofu.org/
https://github.com/opentofu/opentofu
https://opentofu.org.cn/docs


# http doc
https://registry.terraform.io/providers/hashicorp/http/

https://registry.terraform.io/providers/aliyun/alicloud/latest/docs

# 云文档
https://learn.microsoft.com/zh-cn/azure/developer/terraform/

https://help.aliyun.com/zh/terraform/infrastructure-as-code-overview

场景

多公有云场景, 环境复杂度高

不适合场景

单云或少量设备, 少量环境
paas 服务, 不需要关注底层设施

组件

Provider(供应商): 具体实现的厂家 - 外部环境
Module 模块: 是可复用的 Terraform 配置单元;
状态: Terraform 使用 state 文件追踪已部署资源
数据源: 即只有在运行时才能知道的值

VS Code 集成

HashiCorp Terraform 插件

提供语法高亮 / 自动补全 / 格式化
支持直接运行 terraform plan / apply
图形化资源依赖关系图

项目组织结构

运行时会读取工作目录中所有的 *.tf, *.tfvars 文件

一般约定
variables.tf 定义变量
terraform.tfvars 传入变量的值, 格式: 简单的键值对

versions.tf 用于约束 tf 的版本和供应商的版本
output.tf 定义输出内容

provider.tf 云厂商的配置 region 等
terraform.tf tf 环境依赖, 供应商依赖
main.tf 核心逻辑

依赖

隐式依赖: Terraform 已知的, 可以自动推导出来的; 通过属性值引用赋值的方式来设置
显示依赖: 使用 depends_on 来显式声明依赖关系

resource "alicloud_vpc" "default {
    # 依赖某个资源创建后
    depends_on = ["xxx.xxx"]
}

override 合并文件

内嵌块的内容不会合并
需要文件名显式带 override.tf

# example.tf
resource "aws_instance" "web" {
  instance_type = "t2.micro"
  ami           = "ami-408c7f28"
}

# override.tf
resource "aws_instance" "web" {
  ami = "foo"
}

# 最终的文件
resource "aws_instance" "web" {
  instance_type = "t2.micro"
  ami           = "foo"
}

一般流程

初始化
格式化与验证
计划与预览
执行

初始化

下载安装云厂商的对应版本的 Provider
初始化配置后端 state 文件
当 provider 版本或模块参数变化时, 需要重新初始化

terraform init
terraform fmt       # 格式化代码, 保持代码整洁
terraform validate  # 对定义的代码进行语法校检
terraform plan
terraform apply     # 执行变更

install cli

sudo apt update && sudo apt install terraform   # Ubuntu / Debian
sudo yum install terraform                     # RedHat / CentOS

yum install -y yum-utils
yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
yum -y install terraform

brew tap hashicorp/tap
brew install hashicorp/tap/terraform
terraform version

wget https://releases.hashicorp.com/terraform/1.13.4/terraform_1.13.4_linux_amd64.zip
unzip terraform_1.13.4_linux_amd64.zip
mv terraform ~/bin/

管理 cli

调试模式

# 启用调试日志
export TF_LOG=TRACE             # DEBUG
export TF_LOG_PATH=./terraform-trace.log

# 只针对 provider 进行调试
export TF_LOG_PROVIDER=TRACE


terraform plan

`1`	`export TF_INPUT=false # 禁用交互式提示，适配 CI 环境`

基础命令


terraform init                  # 初始化并下载 provider 插件

terraform plan                  # 查看执行计划
terraform plan -out=tfplan      # 生成详细执行计划文件
terraform plan -input=false     # 如果缺少变量不需要输入 直接退出

terraform output                # 输出所有预定义的 output
terraform output instance_ip    # 显示特定输出
terraform output -json          # 以JSON格式输出

terraform apply                 # 部署资源 - 交互式执行
terraform apply --auto-approve  # 部署资源 - 自动确认, 不需要输入 yes
terraform apply tf.tfplan       # 执行某个计划文件 - 不需要交互确认

terraform destroy                   # 销毁全部资源
terraform destroy --auto-approve

高阶命令


terraform show                      # 显示当前状态
terraform show -json                # 显示状态机读格式
terraform show tfplan               # 显示计划文件内容

terraform init -upgrade     # 更新供应商版本

terraform force-unlock <LOCK_ID>    # 解锁


terraform plan -target=aws_instance.web_server  # 特定资源, 注意会自动关联依赖资源
terraform plan -var-file="prod.tfvars"

terraform plan -destroy             # 生成销毁计划但不执行
terraform plan -destroy -out=tf.tfplan
terraform plan -destroy -out=tf.tfplan -target=resource     # 销毁指定资源

terraform plan -refresh-only        # 执行刷新计划, 只查看状态与云上的差异


# 仅更新本地状态文件，使其与真实云资源重新同步，而不会对实际的云资源做任何修改
terraform apply -refresh-only

terraform apply -parallelism=20         # 并行度控制(默认 10)
terraform apply -target=aws_vpc.main    # 目标特定资源


terraform destroy -target=aws_instance.web_server   # 特定资源

格式化和语法


terraform fmt               # 语法格式化
terraform fmt -recursive    # 递归格式化子目录
terraform fmt -check        # 检查格式但不修改(用于 CI 检查)
terraform fmt -width 120    # 使用指定格式化宽度

terraform validate          # 验证当前目录下文件, 不会访问云 API 或实际资源
terraform validate /path/to/config  # 验证指定目录配置

state 状态管理

terraform state list                            # 列出当前的 state 文件所有管理的项目资源清单
terraform state list -id=vpc-0abcd1234ef567890  # 列出特定资源

terraform state rm alicloud_instance.testecs    # 删除状态内的信息
terraform state rm aws_instance.old_server      # 将资源从状态中移除(但不销毁实际资源)

terraform state show aws_vpc.main               # 显示资源详情

terraform state mv aws_vpc.main aws_vpc.new_name    # 重命名资源名时

# 将现有资源导入状态, 需要目标资源配置模板存在
terraform state import aws_vpc.existing vpc-0abcd1234ef567890

terraformrc 镜像

官方模块仓库的镜像站点配置, 加速下载

~/.terraformrc

// 让阿里云相关的 Provider 通过阿里云镜像下载
provider_installation {
  network_mirror {
    url = "https://mirrors.aliyun.com/terraform/"
    include = ["registry.terraform.io/aliyun/alicloud",
               "registry.terraform.io/hashicorp/alicloud"]
  }
  direct {
    exclude = ["registry.terraform.io/aliyun/alicloud",
               "registry.terraform.io/hashicorp/alicloud"]
  }
}

外部工具

tflint

使用 tflint 检查最佳实践

场景

例如指定的 aws 区域没有这个 ec2 实例规则时也会检查出错误

brew install tflint

tflint --init       # 初始化(下载 Provider 规则插件)
tflint              # 运行检查

driftctl 漂移检测

https://docs.driftctl.com/0.40.0

Driftctl 是专门做漂移检测的开源工具，比 terraform plan 更专业，能并行检测大量资源

Driftctl 还能识别"已删除"和"未管理"的资源

curl -L https://github.com/snyk/driftctl/releases/latest/download/driftctl_linux_amd64 -o driftctl

# 扫描
driftctl scan --to aws+tf

driftctl scan --from tfstate://terraform.tfstate
driftctl scan --from tfstate+s3://my-bucket/path/to/state.tfstate
driftctl scan --from tfstate://terraform_S3.tfstate --from tfstate://terraform_VPC.tfstate

driftctl scan --from tfstate://path/to/**/*.tfstate
driftctl scan --from tfstate+s3://path/to/**/*.tfstate

# 输出 JSON
driftctl scan --to aws+tf --output json://drift.json

# 支持上传到 S3 / 发 Slack 通知

infracost成本预估

https://github.com/infracost/infracost

云成本预估

支持 AWS, Azure, GCP 等主流厂商

在 terraform plan 之前查看预期的账单费用

实时估价: 扫描 *.tf 文件 → 调用 Infracost Cloud Pricing API → 输出资源级月费用列表
差异对比: infracost diff 可对比两条 plan 之间的成本差
用量文件: 对 Lambda, S3 等按量计费资源, 可用 YAML 自定义"每月调用次数 / 存储量", 进行估算

curl -fsSL https://raw.githubusercontent.com/infracost/infracost/master/scripts/install.sh | sh

# 安装 Infracost
brew install infracost

# 注册免费 API Key 后登录
infracost register

infracost auth login

# 浏览器跳转, 完成后 key 写入
~/.config/infracost/credentials.yml

# 估算成本
infracost breakdown --path .

# 变更费用评估一
# 进入含 Terraform 代码的目录, 生成 baseline(当前成本快照)
infracost breakdown --path . --format json --out-file infracost-base.json

# 修改 *.tf 后, 查看差异
infracost diff --path . --compare-to infracost-base.json


# 变更费用评估二
在 PR 里直接给出变更前后每月费用的差异
infracost breakdown --path . --format json --out-file infracost.json

infracost diff --path infracost.json

# out
Project: terraform-alicloud
Monthly cost change for this PR: - ¥ 1,243.50
  ├─ alicloud_instance.api[2]       - ¥ 980.00  (changed from ecs.c7.large -> ecs.c7.medium)
  └─ alicloud_slb.lb_public         - ¥ 263.50  (deleted)


# 生成总的费用报告
infracost breakdown --path . --format html > report.html

# 对比不同配置的成本
infracost diff --path . --compare-to terraform.tfstate

# 生成 HTML 报告
infracost output --path /tmp/infracost.json --format html > cost-report.html

其它工具


# 版本管理工具
tfenv
tfenv list         # 查看已有版本
tfenv use 1.9.5    # 切换到1.9.5版本

# 使用 tfsec 安全扫描
tfsec .

Provider 供应商管理

https://registry.terraform.io/
https://registry.terraform.io/browse/providers
https://registry.terraform.io/providers/hashicorp/aws/latest/docs
https://registry.terraform.io/providers/aliyun/alicloud/latest/docs
https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs

Provider 约束

Terraform 会在 .terraform.lock.hcl 文件中锁定版本

provider "aws" {
  version = "~> 5.0"   # 允许 5.x 升级, 不跨到 6.x
  region  = "us-west-2"
}

说明

各个 Provider 插件都是独立的进程, 与 Terraform 主进程之间通过 RPC 进行通讯

Terraform 引擎首先读取并分析用户编写的 Terraform 代码, 形成一个由 data 与 resource 组成的图(Graph),
再通过 RPC 调用这些 data 与 resource 所对应的 Provider 插件

市场插件分类

Offical 官方插件
Partner 第三方认证插件
Community 社区版本插件

常见问题处理

1. terraform init 失败

# 检查网络连接
curl -I https://registry.terraform.io

# 如果在国内, 配置镜像
# 创建 ~/.terraformrc
cat > ~/.terraformrc << EOF
provider_installation {
  network_mirror {
    url = "https://mirrors.aliyun.com/terraform/"
  }
}
EOF

# 或者使用代理
export HTTPS_PROXY="http://proxy:8080"
terraform init

2. 状态文件损坏

# 从远程后端拉取最新状态
terraform state pull > terraform.tfstate.backup

# 如果状态与实际不符, 导入资源
terraform import aws_vpc.main vpc-xxxxxxxx

# 刷新状态
# terraform refresh         # 旧命令
terraform apply -refresh-only

3. 资源漂移检测

如果有漂移, 需要决定是更新状态还是覆盖资源

# 检测实际资源与状态的差异
terraform plan -refresh-only

# 更新状态到实际值 - 线上为准
terraform apply -refresh-only

# 或者重新应用配置 - 状态为准
terraform apply

Module 模块

将基础设施配置封装为可重用, 可共享的组件

模块分类

本地模块: 可以将通过软连接的方式引用本地的源目录(修改后, 无需操作)
git远程模块: 即有版本控制系统
Terraform Registry: 官方仓库模块

管理 cli


terraform get                   # 下载模块
terraform graph                 # 查看模块
terraform graph -module-depth   # 汇总对象

模块设计

注意

避免无意义的模块封装
一般嵌套不超过 2 层, 维护可读性和可维护性
环境差异过大时, 最好还是拆分2个模块独立维护来减少代码复杂度

有意义的模块封装

组合多个官方模块来完成一个项目
固化公司/团队规范, 资源标准化, 固定的规范参数
屏蔽多云差异
可能会大量复用
屏蔽调用方不需要关心的细节
封装业务概念, 而不是技术概念

两种主要的 Module 类型

Root Module(根模块): 是 Module 配置的主入口, 负责调用和组织其他模块
Child Module(子模块): 被 Root Module 或其他模块调用的模块, 专注于特定功能, 可被多次重用

组织结构

方式1: 平铺, 阶段式

environments/
├── dev/
│   ├── 01-base/          # 第一步: VPC, 交换机, NAT 网关
│   ├── 02-security/      # 第二步: 安全组, 网络 ACL
│   └── 03-application/   # 第三步: ECS, RDS, 应用资源
└── prod/                 # 生产环境同样的结构
    ├── 01-base/
    ├── 02-security/
    └── 03-application/

方式2: 模块化

terraform-project/environment/dev
terraform-project/environment/prod
terraform-project/environment/test1
terraform-project/modules/vpc
terraform-project/modules/rds
terraform-project/modules/ec2
terraform-project/modules/eks

语法

1
2
3

name:  模块的名称, 在 terraform 中可以使用模块名称进行引用
source: 模块代码的路径, 本地或者远程的仓库
version: 版本信息

引用
模块的输出值, 便于其他模块引用
引用方式: module.MODULE_NAME.OUTPUT_NAME

实例化
一个模块可以被多次实例化
每个实例定义唯一的名称, 指定相同的 source 来源

模块版本约束

本地路径模块不支持版本控制

# 推荐: 生产环境锁定具体版本
module "vpc_prod" {
  source  = "alibaba/vpc/alicloud"
  version = "1.10.0"  # 锁定精确版本, 确保稳定性
}

# 开发环境: 允许补丁版本更新
module "vpc_dev" {
  source  = "alibaba/vpc/alicloud"
  version = "~> 1.10.0"  # 允许 1.10.x 的补丁更新
}

# 不推荐: 过于宽松的版本约束
module "vpc_risky" {
  source  = "alibaba/vpc/alicloud"
  version = ">= 1.0.0"  # 风险较高, 可能引入破坏性变更
}

source 源

支持

本地路径
Terraform Registry
git
http
GitHub

基础语法

1
2
3

module "vpc" {
  source = ""
}

本地路径

1
2

    source = "./modules/ecs"
    source = "../modules/ecs"

Terraform Registry

1
2

    source  = "alibaba/ecs-instance/alicloud"
    version = "1.2.0"

github

    # HTTPS 方式
    source = "github.com/alibabacloud-automation/terraform-alicloud-ram"

    # SSH 方式
    source = "git@github.com:alibabacloud-automation/terraform-alicloud-ram.git"

    # 引用GitHub仓库中的子模块
    source = "github.com/alibabacloud-automation/terraform-alicloud-ram//modules/ram-user"

    # 通过SSH方式引用特定版本的子模块
    source = "git@github.com:alibabacloud-automation/terraform-alicloud-ram.git//modules/ram-user?ref=v2.1.0"

    source = "git::https://github.com/org/vpc-module.git?ref=v1.2.0"

私有git仓库认证

export GITHUB_TOKEN="ghp_xxx"

module "vpc" {
  source = "git::https://github.com/my-org/terraform-vpc.git?ref=v1.0.0"
}

通用 Git 仓库

    # HTTPS 方式
    source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-vpc.git"

    # SSH 方式
    source = "git::ssh://git@github.com/alibabacloud-automation/terraform-alicloud-vpc.git"

    # 引用Git仓库中的子模块并选择特定版本
    source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-ram.git//modules/ram-user?ref=v2.1.0"

    # 引用私有Git仓库中的子模块
    source = "git::ssh://git@example.com/company/terraform-modules.git//security/waf?ref=v1.0.0"


    # 选择特定版本 - 默认是 默认分支, 选择特定标签
    source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-vpc.git?ref=v1.11.0"

    # 选择特定提交
    source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-vpc.git?ref=51d462976d84fdea54b47d80dcabbf680badcdb8"

    # 浅克隆
    source = "git::https://github.com/alibabacloud-automation/terraform-alicloud-vpc.git?depth=1&ref=v1.11.0"

http

    source = "https://example.com/modules/vpc"

    source = "https://example.com/vpc-module.zip"

    # 从zip归档文件中引用子模块
    source = "https://example.com/vpc-module.zip//modules/subnet"

Terraform Workspace

是同一套代码管理多份独立 State 的内建机制

每个 Workspace 拥有独立的 terraform.tfstate 文件, 在 apply 时互不干扰;

Terraform 默认就有一个名为 default 的 Workspace,
平时使用的 terraform apply 就是在 default Workspace 中操作

注意

共用一套代码, 逻辑容易因大量 count 和 lookup 变得臃肿难懂
修改 main.tf 会影响所有环境
合并代码前, 在所有 Workspace 下执行 plan

因为抽象层度很高, 除非很标准化的场景, 尽量避免使用 workspace 这种模式

实例设计

dev / staging / prod 三环境设计

命名规范: 所有资源名称统一添加 Workspace 前缀, 确保同一账号下资源不冲突:

# 命名模式: landing-zone-{workspace}-{resource}
# 示例:
landing-zone-dev-vpc
landing-zone-dev-sg-app
landing-zone-dev-app-1 # ECS 实例
landing-zone-staging-vpc
landing-zone-staging-nat-gw
landing-zone-prod-vpc
landing-zone-prod-app-rt # 路由表

在代码中通过 local.ws.project_name 自动获取当前环境的项目名前缀, 各模块的资源名均基于 project_name 变量构建

workspace.tf

环境变量映射

# ==========================================
# Workspace 环境配置映射
# ==========================================
# 根据当前 workspace 名称自动选择环境参数
# 支持 dev / staging / prod 三个环境
locals {
  # ========================================
  # 各环境的差异化配置
  # ========================================
  workspace_config = {
    dev = {
      environment       = "dev"
      project_name      = "landing-zone-dev"
      vpc_cidr          = "172.16.0.0/16"
      management_cidrs  = ["172.16.0.0/24", "172.16.1.0/24"]
      application_cidrs = ["172.16.10.0/24", "172.16.11.0/24"]
      database_cidrs    = ["172.16.20.0/24", "172.16.21.0/24"]
      ecs_instance_type = "ecs.u1-c1m1.large"
      ecs_image_id      = "rockylinux_9_7_x64_20G_alibase_20260213.vhd"
      ecs_disk_size     = 20
      ecs_count         = 1
      nat_bandwidth     = 5
    }
    staging = {
      environment       = "staging"
      project_name      = "landing-zone-staging"
      vpc_cidr          = "172.17.0.0/16"
      management_cidrs  = ["172.17.0.0/24", "172.17.1.0/24"]
      application_cidrs = ["172.17.10.0/24", "172.17.11.0/24"]
      database_cidrs    = ["172.17.20.0/24", "172.17.21.0/24"]
      ecs_instance_type = "ecs.u1-c1m1.large"
      ecs_image_id      = "rockylinux_9_7_x64_20G_alibase_20260213.vhd"
      ecs_disk_size     = 20
      ecs_count         = 2
      nat_bandwidth     = 10
    }
    prod = {
      environment       = "prod"
      project_name      = "landing-zone-prod"
      vpc_cidr          = "10.0.0.0/16"
      management_cidrs  = ["10.0.0.0/24", "10.0.1.0/24"]
      application_cidrs = ["10.0.10.0/24", "10.0.11.0/24"]
      database_cidrs    = ["10.0.20.0/24", "10.0.21.0/24"]
      ecs_instance_type = "ecs.u1-c1m1.large"
      ecs_image_id      = "rockylinux_9_7_x64_20G_alibase_20260213.vhd"
      ecs_disk_size     = 40
      ecs_count         = 2
      nat_bandwidth     = 50
    }
  }
  # 当前 workspace 对应的配置(将默认 default workspace 映射到 dev)
  ws_name = contains(keys(local.workspace_config), terraform.workspace) ? terraform.workspace : "dev"
  ws      = local.workspace_config[local.ws_name]
}

locals.tf

使用 local.ws 替代硬编码的变量值


locals {
  # 通用标签 — 自动携带当前环境信息
  common_tags = {
    Project     = local.ws.project_name
    Environment = local.ws.environment
    Workspace   = terraform.workspace
    ManagedBy   = "Terraform"
  }
  # 可用区选择 — 筛选条件:
  #   1. 支持指定 ECS 实例规格 + 磁盘类型(来自 alicloud_zones)
  #   2. 镜像存在性由 data.alicloud_images.ecs_image 在 plan 阶段验证
  #   3. 根据环境 ecs_count 决定最终数量
  available_zone_ids = data.alicloud_zones.available_zones.ids
  selected_zones     = slice(
    local.available_zone_ids, 0,
    min(local.ws.ecs_count, length(local.available_zone_ids))
  )
}

main.tf

原来引用 var.xxx 的地方改为引用 local.ws.xxx

# ==========================================
# 根模块 - 调用各子模块
# ==========================================
# ==========================================
# 1. VPC 模块
# ==========================================
module "vpc" {
  source = "./modules/vpc"
  vpc_name = "${local.ws.project_name}-vpc"
  vpc_cidr = local.ws.vpc_cidr
  tags     = local.common_tags
}
# ==========================================
# 2. VSwitch 模块 - 管理网段
# ==========================================
module "vswitch_management" {
  source = "./modules/vswitch"
  vpc_id       = module.vpc.vpc_id
  zone_ids     = local.selected_zones
  cidr_blocks  = local.ws.management_cidrs
  subnet_tier  = "management"
  project_name = local.ws.project_name
  tags         = local.common_tags
}

State 隔离机制

Workspace 的核心价值在于自动隔离 State;
不同 Workspace 的 State 完全独立, 对 dev 执行 terraform destroy 不会影响 prod

本地后端 State 结构

terraform-landing-zone/
├── terraform.tfstate                    # default workspace
└── terraform.tfstate.d/
    ├── dev/
    │   └── terraform.tfstate            # dev workspace
    ├── staging/
    │   └── terraform.tfstate            # staging workspace
    └── prod/
        └── terraform.tfstate            # prod workspace

OSS 远程后端


# ==========================================
# 远程状态存储 - 阿里云 OSS
# ==========================================
# Workspace 启用后, State 路径自动变为:
#   terraform-landing-zone/env:/dev/terraform.tfstate
#   terraform-landing-zone/env:/staging/terraform.tfstate
#   terraform-landing-zone/env:/prod/terraform.tfstate
# ==========================================
terraform {
  required_version = ">= 1.0"
  backend "oss" {
    bucket  = "myself-terraform-state"
    prefix  = "terraform-landing-zone"
    region  = "cn-beijing"
    encrypt = true
    # TableStore 状态锁(防止并发修改)
    tablestore_endpoint      = "https://mytfstate.cn-beijing.ots.aliyuncs.com"
    tablestore_instance_name = "mytfstate"
    tablestore_table         = "terraform_state_lock"
  }
}

初始化和操作


# 进入项目目录
cd terraform-landing-zone

terraform init      # 初始化 Terraform(下载 provider 插件)

terraform workspace new dev         # 创建并切换到 dev workspace
terraform plan
terraform apply
terraform output summary            # 检查部署资源

terraform workspace new staging     # 创建 staging Workspace 并部署
terraform plan
terraform apply
terraform output summary

terraform workspace new prod         # 创建并切换到 prod workspace
terraform plan
terraform apply
terraform output summary

terraform workspace select prod      # 手动切换环境

## 删除资源
terraform workspace select prod
terraform destroy

terraform workspace select staging
terraform destroy

terraform workspace select dev
terraform destroy

## 删除 Workspace(State 清空后才能删除)

terraform workspace select default
terraform workspace delete prod
terraform workspace delete staging
terraform workspace delete dev


terraform workspace list    # 确认只剩 default 后, 再删除

不同环境下的资源差异处理

差异 1: 如果只是规则不同

locals {
  # 获取当前环境
  env = terraform.workspace

  # 根据不同环境, 定义服务器类型
  server_type = {
    default = "t3.micro"
    dev     = "t3.small"    # dev 环境新增的服务类型
    prod    = "t3.large"
  }

}


resource "aws_instance" "my_server" {
  # 使用 lookup 函数, 找不到时使用 default 值, 优雅降级
  instance_type = lookup(local.server_type, local.env, local.server_type["default"])
}

差异 2: 结构性差异, 通过创建特性开关来处理

# locals.tf
locals {
  env = terraform.workspace

  # 定义哪些环境需要这个特殊的"缓存服务"
  enable_redis_cache = {
    dev  = true   # 只在 dev 环境创建
    prod = false
    staging = false
  }

  # 决定是否创建
  should_create_redis = lookup(local.enable_redis_cache, local.env, false)
}

# 只有当 should_create_redis 为 true 时, count 才等于 1, 从而创建资源
resource "aws_elasticache_cluster" "dev_only_cache" {
  count = local.should_create_redis ? 1 : 0

  cluster_id = "dev-cache-cluster"
  engine     = "redis"
  node_type  = "cache.t3.micro"
  num_cache_nodes = 1

  tags = {
    Environment = local.env
    Note        = "This is a DEV-only service"
  }
}

这样在 prod 或 staging 环境下运行 plan 时,
Terraform 会显示这个资源被忽略(0 to add), 不会产生影响, 保证了安全性

Terraform最佳实践

chenwx716@139.com — Sat, 20 Sep 2025 12:30:00 +0800

规范

使用 required_version 限制 Terraform 版本
使用远程 state 存储
保持 provider 配置统一
遵循团队命名规范
定期运行 plan 监测漂移, 如果发现不一致, 自动报警

多环境管理

不同分支对应不同环境
不同目录结构对应不同环境; 推荐

# 文件
main.tf
variables.tf
outputs.tf

.gitignore

.terraform/
*.tfstate
*.tfstate.backup
*.tfvars
.terraform.lock.hcl
terraform.tfvars

cicd

开发者提交 PR
CI 工具自动运行 plan, 并将结果以评论形式反馈到 PR
架构师 / 运维负责人审核 Plan 结果后 Merge
main 合并后自动触发 terraform apply

terraform plan -out=tfplan
terraform apply tfplan

# 状态码监测: 0 没变更, 1 出错, 2 有变更
terraform plan -detailed-exitcode

资源命名规范

{project}-{environment}-{resource_type}-{purpose}

示例:
myproject-prod-vpc
myproject-prod-subnet-public-a
myproject-prod-nat-1
myproject-prod-sg-default
myproject-prod-igw

模块化

自定义模块应该是业务资源的抽象, 避免对已有资源的重复定义

技术要点回顾

模块化设计: 一套代码支持多环境部署, 减少重复
状态管理: 使用远程后端, 启用锁机制, 确保团队协作安全
渐进式部署: 先 dev, 再 staging, 最后 prod
成本意识: 开发环境精简配置, 生产环境保证高可用

版本锁定

terraform {
  required_version = ">= 1.5.0, < 1.7.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.0"
    }
  }
}

1
2
3

~> 5.0: 允许 5.x 的任何版本, 不允许升到 6.0
~> 5.36.0: 允许 5.36.x 的任何版本, 不允许升到 5.37
>= 5.0, < 6.0: 允许 5.0 及以上, 6.0 以下

敏感信息传递

通过环境变量传递 provider 所需要的认证信息

1
2

export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"

Vault

1
2

# env 传递
export TF_VAR_db_password="your-secret-password"

使用 ssm

variable "db_password" {
  description = "Database password"
  type        = string
  sensitive   = true
}

data "aws_ssm_parameter" "db_password" {
  name = "/prod/db/password"
}

生命周期管理

resource "aws_rds_cluster" "main" {

  # 防止被意外删除
  lifecycle {
    # 生产核心资源必须加
    # 当 plan 结果包含删除这个资源, Terraform 会直接报错, 不会执行
    prevent_destroy = true
  }

  lifecycle {
    # 对于需要替换的资源, 先创建再删除
    create_before_destroy = true
  }


  lifecycle {
    # 忽略某些状态的变化, 如密码用户等, 自动扩缩容相关的动态属性
    ignore_changes = [desired_capacity, cidr_ip]

    # 特殊情况下 也可以忽略全部字段的变更
    ignore_changes = all
  }

}

依赖管理

会自动识别依赖关系
通过 depends_on = [] 手动指定依赖

导入资源状态

手写基础配置
导入

1
2

terraform import aws_vpc.existing vpc-0abc12345
terraform plan

重建资源

`1`	`terraform apply -replace=aws_instance.web`

状态引用

跨模块引用 output

# 在 RDS 模块里引用 VPC 模块的输出
resource "aws_db_subnet_group" "main" {
  name       = "prod-db-subnet"
  subnet_ids = module.vpc.private_subnet_ids
}

跨状态文件引用

data "terraform_remote_state" "vpc" {
  backend = "s3"
  config = {
    bucket = "my-org-terraform-state"
    key    = "prod/network/terraform.tfstate"
    region = "ap-northeast-1"
  }
}

resource "aws_db_subnet_group" "main" {
  subnet_ids = data.terraform_remote_state.vpc.outputs.private_subnet_ids
}

最佳实践 Checklist

[ ] 项目分层: modules/, environments/, providers/ 分离;
[ ] 状态后端用远程(不用 local), 加锁, 加密;
[ ] 变量用 variable 块定义, 敏感变量标记 sensitive, 机密使用 ephemeral
[ ] 资源命名规范: {project}-{env}-{role}-{instance};
[ ] 统一标签: Environment, ManagedBy, Project, CostCenter, Owner;
[ ] 模块化: 业务模块和基础设施模块分开;
[ ] 版本约束: required_version, required_providers, module.version;

[ ] terraform fmt 统一格式;
[ ] terraform validate 静态检查;
[ ] tflint 静态检查(社区 linter);
[ ] checkov / tfsec 安全扫描;

[ ] 关键资源加 prevent_destroy;
[ ] 漂移检测: 定时 plan / driftctl;
[ ] CI 集成: plan → review → apply 流程;
[ ] plan 输出已经仔细审查
[ ] 敏感信息用 Vault / KMS, 不进代码;
[ ] Policy as Code: OPA / Conftest 阻断违规;
[ ] 成本监控: Infracost / 账单分析;
[ ] 文档: 每个 module 有 README, 说明 inputs / outputs / 用途
[ ] 状态备份
[ ] 有回滚方案
[ ] 有通知机制

基于服务健康的 Provider 配置

一些 Provider 可以根据服务健康情况动态调整配置

例如 Consul Service Health Check, 在服务不可用时跳过某些资源创建

资源管理

资源重命名

先修改 tf 文件内的名字
state mv

删除资源

配置文件内删除, 然后 terraform apply
state rm 只删除状态文件内配置
只是移除纳管, 云上保留, 使用 removed{}, 可保留记录

removed {
  from = alicloud_eip.example

  lifecycle {
    destroy = false     # 明确不要销毁真实资源
  }
}

操作项目内部分资源

-target 参数指定操作资源
模块化拆分, 生产级做法
功能开关变量

功能开关变量(适合同一项目内控制) - 不推荐

在模块内通过传入的开关参数来决定是否启用某资源或特性

variable "create_nat_gateway" {
  description = "是否创建 NAT 网关"
  type        = bool
  default     = false
}

resource "alicloud_nat_gateway" "main" {
  count = var.create_nat_gateway ? 1 : 0  # 条件创建

  vpc_id = alicloud_vpc.main.id
}

`1`	`terraform apply -var="create_nat_gateway=false"`