Iac on IT 运维小秋

vault-集合

chenwx716@139.com — Fri, 20 Feb 2026 12:30:00 +0800

HashiCorp Vault 金库

Vault 是 HashiCorp 推出的企业级秘密管理工具, 专为集中保护, 控制和审计敏感信息访问而设计

源代码开源(source-available) + 商业授权模式

OpenBao(开源版 Vault)

如果可以, 推荐应用直接通过 SDK 直接访问 Vault 来获取密钥

特性

集中化秘密存储:
安全管理 API 密钥, 数据库密码, SSL 证书等敏感信息
替代分散在代码或配置文件中的明文存储, 从源头降低泄露风险

细粒度访问控制:
基于策略(Policy)实现"最小权限"管理,
支持多身份认证(Token, LDAP, OAuth2, MFA 等), 确保只有授权实体能访问特定秘密;

动态凭证生成:
为数据库, 云服务等自动生成短期有效, 自动过期的临时凭证, 大幅降低长期凭证泄露的安全隐患;

全链路审计追踪:
记录所有秘密访问, 修改, 删除操作, 生成不可篡改的审计日志, 满足合规审计需求(如等保, SOC2);

可以为数据库 /SSH/Consul/AWS/Nomad/PKI/RabbitMQ 等多种平台生成和管理访问密钥
可以与 Cousul, Chef, Ansible 等运维工具集成起来共同使用

密钥:

静态 Secret: 密钥是固定的
动态 Secret:
请求时会到后端应用去创建一个临时账号(有效期), 并处理权限;
然后将临时账号给到到前端应用, 应用侧自己需要能处理租约到期

数据存储

内存: 临时存储, 配置内存锁定
文件存储: 开发环境使用
分布式存储: etcd, consul 等
aws s3, nosql

应用身份认证方式

应避免硬编码 token 的方式

AppRole: 为应用分配一个 role_id 和 secret_id, 适用于服务器端应用

Kubernetes Auth Method: 针对运行于 Kubernetes 上的服务;
SDK 会利用 Pod 的 ServiceAccount 自动与 Vault 完成认证

云平台认证: 对于运行在 AWS, Azure, GCP 上的应用, 可以使用云平台的原生认证
即 IAM 身份进行认证

JWT/OIDC:
利用外部 OAuth2 提供者进行用户认证;

k8s 集成

方式 1: Vault Secrets Operator 同步创建 Secrets
方式 2: Sidecar 模式, pod 附加一个容器, 即 Vault Agent Sidecar 容器负责与 Vault 通信, 并创建文件挂载
方式 3: Vault CSI Driver 卷挂载模式, 挂载为 Pod 的临时卷

主流方式 1

但方式 2 和 3 无 Secret, 所有密钥不会在命名空间内, 即也不会存储到 etcd 中, 适合安全性非常高的场景

Raft 集群

2/3 可用

Leader 节点宕机, 会进行选举;
Follower 节点, 系统无感知

# 查看成员健康度
vault operator raft list-peers

Node     Address       State     Voter
----     -------       -----     -----
node1    vault:8201    leader    true

运行模式

seal 密封模式
Auto-Unseal 自动解封模式

需要注意 seal密封模式和 Recovery 恢复模式是互斥的;

seal密封模式会生成 5 个解封密钥片段;
密钥有两个用途: 解封 + 授权(重大操作的授权)

自动解封模式时, 解封密钥实际是由 kms/HSM 管理, 此时生成的是5个恢复密钥;
密钥只有 1个用途: 授权(重大操作的授权)

dev 模式

dev 模式下 Vault 会在内存中自动完成初始化和解封
数据没有持久化, 仅用于本地开发调试;

没有解封密钥, 只有一个 rootToken

1
2

# 如果指定了这个变量, 会强制运行在开发模式下, 没有持久化
VAULT_DEV_ROOT_TOKEN_ID=

seal 密封模式

需要手工初始化和解封

初始化
集群模式下, 只需要 init 一个节点, 其他节点只需要加入集群;

docker exec -it vault-server sh
export VAULT_ADDR=http://127.0.0.1:8200;

# 会生成 5 个 unseal key 和 1 个 root token, 务必保存
vault operator init

unsealKey: 解封所需要的密钥分片;

当节点重启后, Vault 启动后处于"密封"状态, 需要 5 个 unsealKey 密钥分片中的至少 3 个才能解封;

1
2

# 解封 - 并按提示输入任意 3 个 unsealKey
vault operator unseal

Auto-Unseal 自动解封

初始化时, Vault 会直接把解封密钥存入 KMS;
节点重启时, 会调用云 kms 接口进行自动解封;

权限控制变成了对"谁能调用 KMS 接口"的阿里云 RAM 权限管理;
ECS 实例或运行 Vault 的环境拥有调用 kms:Decrypt 和 kms:Encrypt 的权限

在 Vault 的配置文件中定义 seal 部分

seal "alicloudkms" {
  region     = "cn-hangzhou"
  access_key = "ak"
  secret_key = "sk"
  kms_key_id = "KMS 主密钥 ID"
}

Recovery Keys 恢复密钥

是一个专门用于授权和恢复操作的安全机制, 区别于常规的解封密钥(Unseal Keys);

只有当 Vault 使用了自动解封(Auto Unseal), 例如集成了云厂商的 KMS 或硬件安全模块(HSM)时, 才会用到它;

Vault 的解封过程由 KMS/HSM 自动完成, 不再需要人来输入解封密钥; 因此没有解封密钥(Unseal Keys);

Recovery Keys 是一个纯人工授权的机制, 它的核心功能是授权, 而不是解密

用于关键操作授权需要人工批准

如生成根令牌 generate-root
执行重新加密 rekey 等
更改迁移 KMS 配置

需要达到设定的阈值(threshold)数量的密钥持有者同意, 操作才能继续

初始化生成:
使用 HSM 或 KMS 初始化 Vault 时, 系统会生成一个内部的 Recovery Key,
并将其拆分成多个密钥碎片(Key Shares), 返回给操作者;

重新生成(Rekey):
在人员变动或合规要求下, 可以使用 rekey 命令来重新生成一套新的 Recovery Keys

PGP 加密:
可以使用在生成或重新生成 Recovery Keys 时使用 -pgp-keys 参数传入 pgp 公钥;

# 重新生成恢复密钥 - 需要多数旧的恢复密钥, Vault 会输出 5 个全新的 Recovery Keys
vault operator rekey -target=recovery

# 重新生成恢复密钥 - 到达阈值后才会有输出
vault operator rekey -init -key-shares=5 -key-threshold=3

避免单人掌握多数 unsealKey/RecoveryKey

官方方案: 使用 PGP 公钥加密

5 位密钥持有者每人提供一个 PGP 公钥, 初始化时需要传入这 5 个公钥;

vault operator init \
    -key-shares=5 \
    -key-threshold=3 \
    -pgp-keys="user1.asc,user2.asc,user3.asc,user4.asc,user5.asc"

终端会输出 5 段密文, 经 PGP 加密的 Base64 字符串, 只有对私钥持有者能解密出自己的那段密文;

alicloudkms

需要 alicloudkms 插件

在 Auto-Unseal 模式下, Vault 会利用 KMS 的"信封加密"技术,
自动产生一个 Recovery Key(恢复密钥),
并将真正用于加解密数据的 Root Key(根密钥) 存储在 KMS 中

每次重启 Vault 服务, 它会自动连接阿里云 KMS 完成解密并进入 unsealed(解封)状态
不在生成 5 个解封的 key, 而是 Recovery Keys

在阿里云控制台:

开通 KMS(密钥管理服务);
创建一个对称密钥(用户主密钥), 记录下它的 KeyId;
确保你的 ECS 实例或运行 Vault 的环境拥有调用 kms:Decrypt 和 kms:Encrypt 的权限(建议通过 RAM 角色授权);

config.hcl

ui = true

storage "file" {
  path = "/vault/data"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 1
}

# 核心配置: 阿里云 KMS 自动解封
seal "alicloudkms" {
  region     = "cn-hangzhou"      # KMS 所在的地域
  access_key = "你的 AccessKeyId"   # 建议使用 RAM 角色, 此处可省略
  secret_key = "你的 AccessKeySecret"

  # 刚才在阿里云创建的密钥 ID
  kms_key_id = "bc4xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

初始化

不再输出 Unseal Key 1…5, 会输出 Recovery Key 1…5, 依然会输出 Initial Root Token

`1`	`vault operator init`

阿里云权限控制

方案1: 细化权限
禁止给非 Vault 服务器授予 Resource: * 的权限

{
  "Action": ["kms:Decrypt"],
  "Resource": ["*"],  // 禁止所有权限, 必须细化
  "Effect": "Allow"
}

每个业务系统细化权限

{
  "Action": ["kms:Decrypt"],
  "Resource": ["acs:kms:cn-hangzhou:12345:key/业务Key_ID_xxxx"], // 明确指定
  "Effect": "Allow"
}

方案2: 提供预设的字符串对进行双保险

seal "alicloudkms" {
  kms_key_id         = "你的ID"
  encryption_context = "{\"AppName\": \"Vault-Production-Cluster\"}"
}

方案3: 限制作用域, 这个权限只能在某个范围用

{
  "Action": "kms:Decrypt",
  "Resource": "acs:kms:cn-hangzhou:12345:key/Vault_Key_ID",
  "Effect": "Allow",
  "Condition": {
    "StringEquals": {
      "acs:SourceVpc": ["vpc-t4nxxxxxxxx"] # 只有这个 VPC 内的请求才有效
    }
  }
}

RootToken

初始化后会生成一个最高权限的 rootToken

最佳实践
撤销掉这个初始的 rootToken, 有必要时再进行临时创建(需要 5 个解封密钥)

1
2

# 撤销 token
vault token revoke <TOKEN_VALUE>

重新生成 rootToken

# 利用 Recovery Keys 重新生成 root token
# 系统会返回一个 Nonce 值和 OTP (One-Time Password)
vault operator generate-root -init

# 提供 Recovery Keys 签名, 需要多个管理员输入足够数量的 Recovery Keys
vault operator generate-root -recovery-key

# 解码获取新 Token:
# 最后一步会输出一个加密的 Token 字符串, 结合第 1 步的 OTP 即可解密出真实的 hvs.root-xxx

管理cli

export VAULT_ADDR='http://192.168.5.9:8200'
export VAULT_TOKEN='xxxxxxxxxxxxxewofoeiwoiieo'

vault status        # 运行状态

kv

# write
vault kv put secret/myapp/config \
    db_username="admin" \
    db_password="very-secret-password" \
    timeout="5s"

# read
vault kv get secret/myapp/config

# modify
vault kv patch secret/myapp/config timeout="10s"

vault kv metadata get secret/myapp/config       # 查看版本历史
vault kv get -version=1 secret/myapp/config     # 读取旧版本 (版本 1)

# 查看已经开启的认证方法
vault auth list
Path         Type        Accessor                  Description                Version
----         ----        --------                  -----------                -------
approle/     approle     auth_approle_f18cd096     n/a                        n/a
token/       token       auth_token_ecd6971e       token based credentials    n/a
userpass/    userpass    auth_userpass_42108dc7    n/a                        n/a

# token 是已经签发的token, 不能直接列出

vault write auth/userpass/users/user1 password=passw0rd

vault login -method=userpass username=bob password=foobar

vault list auth/userpass/users
vault list auth/approle/role/

业务集成

在 k8s 集群中

每个 Pod 都有一个挂载在 /var/run/secrets/kubernetes.io/serviceaccount/token 的 JWT 令牌;
交换 Token: 应用(或 Vault Agent)将这个 JWT 发给 Vault;
验证: Vault 调用 K8s API 确认: “这个 JWT 确实是 order-service 这个应用的;”
下发 Token: 验证通过, Vault 返回一个专门给该应用使用的, 权限受限的 VAULT_TOKEN

续签

Vault sdk 有续签机制
Vault Agent - Sidecar 模式

在虚拟机或物理机上

利用 AppRole; 这类似于 OAuth2;

应用持有一个 RoleID(类似用户名)和 SecretID(类似密码);

启动时调用 Vault API 换取 VAULT_TOKEN

最佳实践

云上优先考虑 Auto-unseal 自动解封, 节点漂移后方便自动解封;
云下部署考虑硬件密钥
app 通过sdk直接访问 vault 获取秘密信息
k8s集群可选通过 eso(ExternalSecretsOperator) 或者 vault-secrets-operator 将密钥更新到 k8s secrets
vault 最好在k8s集群外独立部署

vault-secrets-operator

将 vault 中的秘密同步到 k8s 集群中

原生支持动态秘密
认证集成: 深度利用 K8s Auth Method, 让 Pod 能够以原生的方式与 Vault 交互

helm repo add hashicorp https://helm.releases.hashicorp.com
helm repo update
helm install vault-secrets-operator hashicorp/vault-secrets-operator \
  --namespace vault-secrets-operator-system \
  --create-namespace

Vault 配置

在 Vault 侧配置, 需要启用 Kubernetes 认证, 并创建一个角色(Role), 这个角色会将特定的 Kubernetes ServiceAccount 和命名空间绑定到 Vault 的权限策略上
在 Kubernetes 侧配置: 通过创建 VaultAuth 资源来告诉 VSO 如何使用这个角色进行认证

# 示例: VaultAuth 资源
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultAuth
metadata:
  name: static-auth
  namespace: default
spec:
  method: kubernetes
  mount: kubernetes
  kubernetes:
    role: database   # 对应在 Vault 中创建的 role 名称
    serviceAccount: my-app-sa # VSO 将使用的 ServiceAccount

通过 VaultStaticSecret 资源从 Vault 拉取 Secret

# 示例: VaultStaticSecret 资源
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  name: myapp-static-secret
  namespace: default
spec:
  type: kv-v2                     # 使用 KV V2 引擎
  mount: secret                   # Vault 中的挂载路径
  path: myapp/config              # Vault 中的 Secret 路径
  destination:
    name: myapp-k8s-secret        # 生成的 Kubernetes Secret 名称
    create: true                  # 自动创建 Secret
  refreshAfter: 1h                # 定期从 Vault 拉取最新数据, 每小时同步一次

开启 instantUpdates 可以实现基于 Vault 事件(Event)的近实时同步

当 Secret 更新后, 可以通过在 VaultStaticSecret 中配置 rolloutRestartTargets,
让 VSO 自动触发关联的 Deployment 或 StatefulSet 滚动更新

数据转换:
如果 Vault 中的原始数据格式不适合应用,
还可以使用 transformation 字段, 通过 Go 模板对数据进行处理后再存入 Kubernetes Secret

动态密码-数据库

1
2

# 启用数据库引擎
vault secrets enable database

PostgreSQL

配置连接

vault write database/config/my-db \
    plugin_name=postgresql-database-plugin \
    allowed_roles="my-role" \
    connection_url="postgresql://{{username}}:{{password}}@localhost:5432/postgres?sslmode=disable" \
    username="postgres" \
    password="root-password"

定义角色与权限: 告诉 Vault 每次生成临时用户时执行什么 SQL

vault write database/roles/my-role \
    db_name=my-db \
    creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
    default_ttl="1h" \
    max_ttl="24h"

生成临时密码

`1`	`vault read database/creds/my-role`

得到一个全新的 username (如 v-token-my-role-xxx) 和 password
1小时后, Vault 会自动在数据库里删掉这个用户

java引入配置

引入 spring-cloud-starter-vault-config

bootstrap.yml

spring:
  cloud:
    vault:
      uri: http://localhost:8200
      token: ${VAULT_TOKEN}
      kv:
        enabled: true
        backend: secret
        default-context: myapp/config

API

# 查看状态, 是否封锁和解封
curl https://vault.services.wait/v1/sys/seal-status

# API 可用性验证
curl http://IP:8200/v1/sys/health  # 返回包含 initialized 和 sealed 状态的 JSON

approle

AppRole 代表一组 Vault 策略和登录约束, 必须满足这些策略才能使用这些策略获取令牌

面向应用程序

roleID - 角色ID
SecretID - 认证密钥

只产生 Vault Token, 解决你是谁的问题, 并不涉及权限
具体的权限要看绑定的 kv 或者 path 路径策略

1
2

# 开启 AppRole 认证
vault auth enable approle

token_type

service 默认类型; 存储在 Vault 的内存和磁盘中, 支持续期(Renew), 吊销(Revoke), 并会在 Vault 界面显示;
batch 类型; 类似 JWT, 所有的权限信息都加密编码在 Token 字符串本身;
极高性能, 减轻 Vault 存储后端的负担, 不可续期, 且一旦发出除非到期否则无法吊销;
适合短暂的自动化任务, 高并发的临时访问

role manager

vault delete auth/approle/role/terraform-role

# 创建角色并绑定策略 - auth/approle/role/terraform-role
vault write auth/approle/role/terraform-role \
    secret_id_ttl=0 \   # SecretID 自身的有效期
    secret_id_num_uses=0 \      # SecretID 使用次数限制
    token_type=service \        # 默认就是 service
    token_num_uses=0 \
    token_ttl=1h \      # Token 产生后的初始有效期
    token_max_ttl=3h \  # Token 允许被续期到的最长总时长, batch 类型的 Token 不可续期
    token_policies="admin-readonly"

# 获取 role-id
vault read auth/approle/role/homelab-app1/role-id

# 创建/获取 Secret ID
vault write -f auth/approle/role/homelab-app1/secret-id

登录并换取 Token


## 登录
vault write auth/approle/login \
    role_id="ae7830a4-ee10-3e84-b186-770b286b51b4" \
    secret_id="f8268b33-6b96-d08f-bcb7-0c959dcd09bd"

# 响应 json 里面有 client_token 字段
# 也可以通过 vault token lookup 查看认证和 token


curl \
    --request POST \
    --data '{"role_id":"ae7830a4-ee10-3e84-b186-770b286b51b4","secret_id":"f8268b33-6b96-d08f-bcb7-0c959dcd09bd"}' \
    https://vault.services.wait/v1/auth/approle/login

wait@ub05:~$ vault read auth/approle/role/homelab-app1/role-id
Key        Value
---        -----
role_id    3211340e-fe90-3236-36fe-ff7100763cf2
wait@ub05:~$
wait@ub05:~$ vault write -f auth/approle/role/homelab-app1/secret-id
Key                   Value
---                   -----
secret_id             b4d8c662-0042-040a-0527-dbbbe3acec90  # 密码
secret_id_accessor    b86c5e6d-880f-32e4-279b-eaf19151bc5b  # 访问器/工号
secret_id_num_uses    0
secret_id_ttl         0s

secret_id_accessor 即密钥的编号, 便于通过 secret_id_accessor 管理 secret, 例如删除

`1`	`vault write auth/approle/role/homelab-app1/secret-id-accessor/destroy accessor=b86c5e6dxxx`

CIDR绑定

在 Vault 的 AppRole 机制中, CIDR 绑定分为两个层级, 建议同时使用:

secret_id_bound_cidrs 限制谁能拿 SecretID 去登录
token_bound_cidrs 限制登录后拿到的 Token 只能在哪些 IP 使用

vault write auth/approle/role/homelab-node \
    secret_id_num_uses=0 \
    secret_id_ttl="0" \

    # 核心限制：只允许来自 指定 的 IP 请求登录, 多ip使用逗号分隔
    secret_id_bound_cidrs="192.168.1.5/32" \

    # 核心限制: 生成的 Token 也只能在 这个 ip 上使用
    token_bound_cidrs="192.168.1.5/32" \
    token_ttl="1h" \
    token_max_ttl="3h" \
    policies="pki-policy"           # 绑定某个策略

userpass

vault 内部的账号体系

可以通过 Vault 的 API, CLI 或 UI 来登录这个账号
Vault 验证密码正确后, 会现场生成一个 Token

vault auth enable userpass      # 开启 userpass 认证
vault auth list                 # 查看已经开启的认证方法
vault list auth/userpass/users  # 查看全部用户

# 新建一个用户, 增加策略也是这个命令
vault write auth/userpass/users/alice \
    password="foo" \
    policies="admin"            # 关联 admin 这个策略

# 登录时会自动获取 token
vault login -method=userpass username=admin

curl --request POST \
    --data '{"password": "user_password"}' \
    ${VAULT_ADDR}/v1/auth/userpass/login/admin


# 设置环境变量
export VAULT_TOKEN="hvs.xxx..."

vault login -method=userpass username=admin
Key                    Value
---                    -----
token                  hvs.CAESIKXoJd6k37JUxGEZZ5tHOdBydB4Y07Zfl0B3z8FrmpY-Gh4KHGh2cy5YT3FLaGNEbEJSeDJPYUdRcTFZN3R4aTg
token_accessor         jfy69OCJVuZXn6gjKfdWbsmg
token_duration         768h
token_renewable        true
token_policies         ["admin" "default"]
identity_policies      []
policies               ["admin" "default"]
token_meta_username    admin

# 查看 Token 详情, 验证权限
vault token lookup

Key                 Value
---                 -----
accessor            jfy69OCJVuZXn6gjKfdWbsmg
creation_time       1775833166
creation_ttl        768h
display_name        userpass-admin
entity_id           bebb8efc-3615-7fff-219d-78598cf87bb3
expire_time         2026-05-12T22:59:26.642334339+08:00
explicit_max_ttl    0s
id                  hvs.CAESIKXoJd6k37JUxGEZZ5tHOdBydB4Y07Zfl0B3z8FrmpY-Gh4KHGh2cy5YT3FLaGNEbEJSeDJPYUdRcTFZN3R4aTg
issue_time          2026-04-10T22:59:26.642342468+08:00
meta                map[username:admin]
num_uses            0
orphan              true
path                auth/userpass/login/admin
policies            [admin default]
renewable           true
ttl                 767h59m35s
type                service


# 用户登录后修改密码
vault write auth/userpass/users/alice/password password="NewSecurePassword"

engine

secret engine

Generic: KV, Kubernetes, LDAP, PKI Certificates, SSH, TOTP, Transit

Cloud: AliCloud AWS Azure Google Cloud Google Cloud KMS

Infra: Consul Databases Nomad RabbitMQ

Generic (通用类): 核心功能与加解密

引擎	作用
KV	Key-Value 存放静态密钥, api token 等
Transit	加密服务
PKI Certificates:	CA (证书颁发机构) 自动为内网服务签发 TLS 证书
SSH	生成临时的 SSH 登录凭证
TOTP	生成临时的动态两步验证码;
LDAP
Kubernetes	通常指机密引擎(为 K8s 生成 Service Account Token), 而不是登录认证;

Cloud: AliCloud / AWS / Azure / GCP
场景: 动态生成 IAM 角色账号
程序向 Vault 申请, Vault 调用云 API 临时创建一个只拥有特定权限的 AK

Google Cloud KMS / AWS KMS
密钥桥接; 让 Vault 利用云端的硬件安全模块(HSM)来保护自己的主密钥

Infra (基础设施类): 中间件动态授权

Databases: 支持 MySQL, Postgres, MongoDB, Redis 等
应用请求角色, Vault 会去数据库创建账号并赋权, 消除共享的 DB 账号

Consul / Nomad: 动态生成 Consul 的 ACL Token 或 Nomad 的调度权限

RabbitMQ: 动态管理消息队列的用户和权限(VHosts, Permissions)

cubbyhole
每个 token 都有的临时存储空间
仅当前 Token 可见

即使是 Root Token, 也无法看到其他 Token 的 cubbyhole
随 Token 销毁的, 一旦 Token 到期, 被撤销或注销, 该 Token 在 cubbyhole/ 下存储的所有数据会立即被永久物理删除

aws


vault secrets enable aws

# 写入一个高级权限的aws账号
vault write aws/config/root \
    access_key=AKIAZXN6JNH5D6ZSHS5V \
    secret_key=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 \
    region=us-east-1

# 创建一个角色(vpc)，让它可以操作 VPC
vault write aws/roles/vpc \
    credential_type=iam_user \
    policy_document=-<<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ec2:*",
      "Resource": "*"
    }
  ]
}
EOF

# 获取 access_key 和 secret_key, 这里获取到的是 aws 的;
# Vault 中把动态生成的机密信息关联了一个 lease 租约, 默认 768h 可用
vault read aws/creds/vpc

# 手动吊销租约, 会删除 aws iam 账号
vault lease revoke aws/creds/vpc/w8OTDxIri80TCkGtoZPkc6Qc

# 设置生成的 Key 的有效时间
vault secrets tune -default-lease-ttl=30m aws/

alicloud

# 开启阿里云认证插件
vault auth enable alicloud

# 配置 Vault 访问阿里云的凭证(建议给这个 RAM 用户最小权限: Action: "sts:GetCallerIdentity")
vault write auth/alicloud/config \
    access_key="YOUR_ACCESS_KEY" \
    secret_key="YOUR_SECRET_KEY"

# 创建 Vault 角色并绑定 RAM 角色
# 这一步是建立 RAM 角色 (ARN) 与 Vault 策略 之间的映射关系

# 创建一个 Vault 角色, 绑定到特定的阿里云 RAM 角色 ARN
vault write auth/alicloud/role/homelab-gpu-node \
    arn="acs:ram::1234567890:role/my-gpu-instance-role" \
    policies="pki-policy,kv-readonly" \
    ttl="1h"

# 只有拥有 my-gpu-instance-role 这个 RAM 角色的实例, 才能登录这个 Vault 角色

kv

v1 版本比较简单, 没有多版本
v2 支持多版本

1
2

# 启用 v1
vault secrets enable -version=1 kv

vault kv put kv/my-secret my-value=s3cr3t

vault kv get kv/my-secret

vault kv delete kv/my-secret

vault kv list homelab/infra/
vault kv get homelab/infra/aliyun
vault kv list homelab/infra/ssh-keys/


vault kv put secret/test db_password=123456   # 创建秘密
vault kv get secret/test                      # 读取秘密(应显示 db_password:123456)

Transit 加密服务

自身不存储数据
只负责提供加解密数据的api, 即只执行不存储;

支持的加密方式 (算法)

类型	算法
对称加密	AES-GCM (默认), AES-CBC, ChaCha20-Poly1305
非对称加密	RSA (2048/4096), ECDSA (P-256/384/521), Ed25519
哈希	SHA-2 (224/256/384/512)
HMAC	SHA-2 (256/384/512)

性能: 标准4核主机, AES-GCM 这种硬件加速算法每秒可以处理约万次请求

关键特性: 收敛加密 (Convergent Encryption)
Vault 支持一种模式, 使得相同的明文和上下文在加密后产生相同的密文, 这在数据库脱敏后的"等值查询"中非常有用

信封加密

Vault 端: 仅生成一个数据密钥 (Data Encryption Key, DEK);
应用端使用这个 DEK 对数据进行加密和解密
应用向 Vault 请求用"主密钥"加密这个 DEK, 并将加密后的 DEK 连同密文一起存入数据库
应用重启后需要先向将 DEK 的密文给 vault 解密, 然后用 DEK 去解密业务数据;

优点: 只有获取 / 加密 DEK 时调用一次 Vault, 实际大数据量的加解密在本地 CPU 完成

ssh

原理: ssh 服务器通过信任CA根证书的方式允许可信客户端登录

vault 是 ca 签署者
签署用户的 ssh 公钥后生成证书文件
用户使用 ssh 私钥 + 证书文件登录服务器

# 开启 SSH 秘密引擎
vault secrets enable -path=ssh-client-signer ssh

# 配置 Vault 生成自己的 CA 私钥和公钥
# 注意: Vault 会安全地保存私钥, 只把公钥给你
vault write ssh-client-signer/config/ca generate_signing_key=true

需要获取 Vault 的 CA 公钥, 并把它放到你所有服务器 /etc/ssh/trusted-user-ca-keys.pem
并在 sshd_config 里引用它

# 获取公钥并保存
curl -o /etc/ssh/ssh_ca.pub $VAULT_ADDR/v1/ssh-client-signer/public_key

示例

创建 Vault 角色 (Role)
创建一个名为 ops-role 的角色, 它强制要求证书中必须包含 ops 这个勋章, 并且限制有效期为 1 小时

vault write ssh-client-signer/roles/ops-role \
    key_type=ca \
    allow_user_certificates=true \
    allowed_users="ops" \           # 为证书里的角色名
    default_extensions="permit-pty,permit-port-forwarding" \
    allow_user_key_ids=true \
    key_id_format="{{token_display_name}}" \
    max_ttl="1h" \
    ttl="1h"


# key_id_format: 这会自动把登录 Vault 的用户名(如 alice)填入证书的 Key ID (-I)

用户申请签名

用户生成自己的ssh公私钥

ssh-keygen -t ed25519 -f ~/.ssh/vault_temp -N ""

# 提交自己的公钥进行签名 - 获取到证书文件
vault write -field=signed_key ssh-client-signer/sign/ops-role \
    public_key=@$HOME/.ssh/vault_temp.pub > ~/.ssh/vault_temp-cert.pub

# 登录目标系统的公共账号 ops-runner, 会自动引用 vault_temp-cert.pub 文件
ssh -i ~/.ssh/vault_temp ops-runner@192.168.5.x

PKI

tls 证书管理

是 CA, 还负责身份校验, 权限控制和短期证书颁发
Vault 维护动态的 CRL(证书撤销列表)

组合

Root CA: 可以在 Vault 内部生成
Intermediate CA: 由根 CA 签发, 专门用于处理日常请求
Role(角色): 你可以定义一个角色 homelab-dot-com, 限制它只能签发 *.homelab.com, 有效期最长 24h

与 cert-manager 组合
cert-manager 只是证书的搬运工, 自身不生成证书

安装 cert-manager, 配置一个 Issuer 类型为 vault

cert-manager 自动向 Vault 申请证书
Vault 验证 K8s 的 ServiceAccount
Vault 返回证书, cert-manager 将其存入 Secret 供 app 使用

# 配置 PKI 角色, 限制只能申请特定的域名, 有效期 24 小时
vault write pki_int/roles/homelab-node \
    allowed_domains="homelab.local" \
    allow_subdomains=true \
    max_ttl="24h" \
    generate_lease_with_token=true

客户端脚本

#!/bin/bash
set -e

# --- 配置区 ---
VAULT_ADDR="https://vault.services.wait"
ROLE_NAME="homelab-node"
COMMON_NAME="ub05.homelab.local"   # 当前机器的域名
CERT_DIR="/etc/ssl/vault"
RESTART_COMMAND="systemctl reload nginx" # 或者 traefik

# AppRole 凭证 (建议通过环境变量或受保护的文件读取)
ROLE_ID="你的 -role-id"
SECRET_ID="你的 -secret-id"

# --- 1. 登录 Vault 获取临时 Token ---
echo "Logging into Vault..."
LOGIN_TOKEN=$(vault write -field=token auth/approle/login \
    role_id="$ROLE_ID" secret_id="$SECRET_ID")

export VAULT_TOKEN=$LOGIN_TOKEN

# --- 2. 申请新证书 ---
echo "Requesting new certificate for $COMMON_NAME..."
CERT_DATA=$(vault write -format=json pki_int/issue/$ROLE_NAME \
    common_name="$COMMON_NAME" ttl="24h")

# --- 3. 解析并保存证书, 私钥和 CA 链 ---
mkdir -p $CERT_DIR
chmod 700 $CERT_DIR

echo "$CERT_DATA" | jq -r '.data.certificate' > $CERT_DIR/cert.pem
echo "$CERT_DATA" | jq -r '.data.private_key' > $CERT_DIR/key.pem
echo "$CERT_DATA" | jq -r '.data.issuing_ca' > $CERT_DIR/ca.pem

# 合并证书链 (很多 Web 服务需要这个)
cat $CERT_DIR/cert.pem $CERT_DIR/ca.pem > $CERT_DIR/fullchain.pem

echo "Certificates updated in $CERT_DIR"

# --- 4. 重载服务 ---
echo "Reloading service..."
$RESTART_COMMAND

echo "Done!"

安全

# 强制启用 TLS 加密
listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 0
  tls_cert_file = "/vault/certs/cert.pem"  # 挂载证书目录
  tls_key_file  = "/vault/certs/key.pem"
}

# 使用分布式存储(替代文件存储)
storage "consul" {  # 或 etcd/raft
  address = "consul:8500"
  path    = "vault/"
}

1
2
3


# 启用审计日志
vault audit enable file file_path=/vault/logs/audit.log  # 登录后执行

创建子 token 和限制策略
vault policy write mysql-readonly readonly-policy.hcl

# 创建带限制的子 Token
# 创建一个有效期 24 小时, 只能用 10 次, 绑定该策略的子 Token
# 得到一个以 hvs. 开头的 Token, 它只能执行策略定义的读取操作
vault token create -policy="mysql-readonly" -ttl="24h" -use-limit=10

轮换 KMS 主密钥 (底层加密)

在阿里云 KMS 侧, 可以手动触发主密钥(CMK)的轮换, 或者开启"自动轮换"功能(如每 365 天一次);

效果: KMS 会生成一个新的密钥版本(Key Version);

对 Vault 的影响: Vault 无需重启;
它下次加密数据时会使用新版本, 解密旧数据时 KMS 会自动识别并使用旧版本;
这是对业务无感的最佳方案;

policy策略

权限 / 策略

允许访问 Vault 中哪些路径;
策略可以附加到 token 或角色

Vault 采用一组具有优先级的判定规则来决定最为具体的路径匹配;
如果一个匹配模式被多个策略使用并能匹配上给定路径, Vault 会取其能力的并集

如果一个路径能被多个策略定义的不同的匹配模式所匹配, 那么只有最高优先级的匹配会被采用

如果 P1 中第一个 + 或是 * 出现的位置早于 P2, 那么采用 P2
如果 P1 以 * 结尾, 而 P2 不是, 那么采用 P2
如果 P1 包含更多的 + 段, 那么采用 P2
如果 P1 更短, 那么采用 P2
如果 P1 得到的字典序更小, 那么采用 P2
仅允许 * 出现在模式的末尾

一旦令牌被签发, 其关联的策略无法再被修改; 必须吊销旧令牌并申请新令牌才能得到更新后的关联策略

令牌关联的策略内容是实时解析的, 也就是说, 如果更新了策略内容,
附加此策略的令牌下次的请求就会按照新策略内容进行权限检查

path "secret/foo" {
  capabilities = ["read"]
  required_parameters = ["bar", "baz"]  # 必须指定的参数

  # 针对指定路径允许操作的键值对的白名单, 非空时只能使用列表中限定的值
  allowed_parameters = {
    "bar" = []
  }

  # 键值对的黑名单，优先级高于 allowed_parameters
  denied_parameters = {
    "bar" = []
  }


  min_wrapping_ttl = "1s"       # 客户端可以指定的响应封装有效期的最小值
  max_wrapping_ttl = "90s"      # 允许设置的响应封装有效期的最大值

}

path

五个核心板块: 身份与认证(Auth), 系统管理(Sys), 身份实体(Identity), 秘密引擎(KV & PKI)

认证相关路径 (Auth & AppRole)

控制用户如何进入 Vault 以及如何管理登录方式

path	用途
auth/approle/login	这是 AppRole 登录的端点
auth/*	所有认证方法(如 Userpass, GitHub, LDAP)的配置接口
sys/auth/*	用于管理"挂载点"

如果需要程序通过 RoleID 和 SecretID 获取 Token, 必须拥有 auth/approle/login 路径的 create 或 update 权限;

开启一个新的认证方式或关闭已有的, 就需要访问 sys/auth/

系统管理与审计 (Sys)

是 Vault 服务器级别的底层控制路径

path	用途
sys/health	返回 Vault 节点状态(是否初始化, 解封, 主节点)
sys/audit	审计日志管理
sys/leases/*	租约管理, 可以续期和撤销
sys/mounts/*	秘密引擎管理

例如手动执行的 vault secrets enable, 本质上就是在操作sys/mounts路径, 决定在哪个路径挂载哪种秘密存储

策略管理 (Policies)

path	用途
sys/policies/acl/*	管理所有的 ACL 策略, 即 hcl 策略文件
sys/policies/acl/admin	专门指代名为 admin 的策略;

通常在 CI/CD 或权限分配时, 会限制用户只能读取而不能修改这个特定的admin管理员策略

身份模型 (Identity)

是 Vault 的核心, 它把不同的登录方式(Alias)统一到一个"人"(Entity)身上
每个 Entity 代表一个真实的用户或机器

alias 别名: 它负责把 userpass 里的 admin 和 github 里的 wait 映射到同一个 Identity Entity 上;

path	用途
identity/entity/*	管理"身份实体"
identity/entity-alias/*	管理"别名"
identity/entity/id	通过 ID 精确查询某个身份的信息
identity/entity/name	通过名称精确查询某个身份的信息

秘密引擎路径 (KV & PKI)

KV-V2 (Key-Value)

kvv2/data/
KV-V2 的路径中必须包含 data/ 才能读写实际数据
kvv2/data/prod/*
kvv2/data/dev/*

PKI (证书颁发机构)

path	用途
pki_int/issue/*	签发证书; 通过请求此路径并指定 Role, Vault 会动态生成私钥和证书;
pki_int/revoke	吊销证书; 将证书序列号加入吊销列表(CRL);
pki_int/tidy	清理操作; 删除过期的证书以释放存储空间, 保持 Vault 性能;
pki/config/urls	配置证书的下载地址和 CRL 分发点;

Capabilites 动作

create(POST/PUT)        # 允许在指定路径创建数据
read(GET)               # 允许读取指定路径的数据
delete(DELETE)          # 允许删除指定路径的数据

# 允许修改指定路径的数据; 对多数 Vault 部件来说, 这隐含了在指定位置创建初始值的能力
update(POST/PUT)

# 允许列出指定路径的所有键;
# 要注意的是, 经由 list 操作返回的键是未经策略过滤的;
# 请勿在键名中编码敏感信息; 不是所有后端都支持 list 操作
list(LIST)

# 允许访问需要根权限保护的路径;
# 除非拥有 sudo 能力, 否则令牌被禁止与这些路径交互(对这种路径的操作可能同时需要其他能力, 例如 read 或 delete)
# 例如, 修改审计日志后端配置就需要令牌具有 sudo 特权;
sudo

# 不允许访问;
# 该定义总是优先于其他能力定义, 包括 sudo, 只要能力中存在 deny, 就不允许执行任何操作
deny

管理cli

vault policy list                   # 列出策略
vault policy read <policy-name>     # read
vault read sys/policy               # 列出所有已注册的策略

# create
vault policy write policy-name policy-file.hcl

# update
vault write my-existing-policy updated-policy.json

vault delete sys/policy/policy-name


# 关联策略

## 创建用户时关联策略
vault write auth/userpass/users/user1 \
    password="s3cr3t!" \
    policies="dev-readonly,logs"

vault login -method="userpass" username="user1"

## 创建令牌时附加策略
vault token create -policy=dev-readonly -policy=logs

示例

# 允许对 secret/foo 路径进行读
path "secret/foo" {
  capabilities = ["read"]
}

# 允许访问
path "secret/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}


# 拒绝访问, 拒绝的优先级最高
path "secret/super-secret" {
  capabilities = ["deny"]
}

# 允许创建, 但是只能是限定值
path "secret/restricted" {
  capabilities = ["create"]
  allowed_parameters = {
    "foo" = []
    "bar" = ["zip", "zap"]
  }
}

# 模糊匹配
path "secret/zip-*" {
  capabilities = ["read"]
}

# + 代表路径中一个段内任意长度的字符
path "secret/+/teamb" {
  capabilities = ["read"]
}

# 除 bar 外可以对任意 key 设置任意值
path "secret/foo" {
  capabilities = ["create"]
  allowed_parameters = {
    "bar" = ["zip", "zap"]
    "*"   = []
  }
}

path "secret/foo" {
  capabilities = ["create"]
  denied_parameters = {
    "bar" = ["zip", "zap"]
  }
}

path "secret/foo" {
  capabilities = ["create"]
  denied_parameters = {
    "*" = []
  }
}

# 允许读取特定路径下的秘密
path "secret/data/mysql/*" {
  capabilities = ["read"]
}

# 允许列出秘密列表
path "secret/metadata/mysql/*" {
  capabilities = ["list"]
}

内置策略

Vault 有两个内建策略: default 和 root

default

默认情况下, 它被附加到所有令牌上, 但可以通过使用身份验证方式创建令牌时显式排除

该策略包含了基础的功能, 例如准许令牌查询有关自身的数据以及使用 Cubbyhole 数据

# 创建令牌时排除 default 策略
vault token create -no-default-policy

curl \
  --request POST \
  --header "X-Vault-Token: ..." \
  --data '{"no_default_policy": "true"}' \
  https://vault.hashicorp.rocks/v1/auth/token/create

root

任何关联了该策略的用户都将是根用户;
强烈建议在生产环境中使用 Vault 前首先吊销所有的根令牌

# 吊销根令牌
vault token revoke "<token>"

curl \
  --request POST \
  --header "X-Vault-Token: ..." \
  --data '{"token": "<token>"}' \
  https://vault.hashicorp.rocks/v1/auth/token/revoke

插件

Ethereum Secrets Engine 插件

Vault 变成一个远程签名机(Remote Signer):
私钥永远不出 Vault 内存, 你只需发送交易摘要给 Vault, 它返回签名后的结果

存储: 私钥经过 Vault 的主密钥加密后存入 Raft
计算: 签名操作在 Vault 内部完成

访问: 你的 Sepolia 节点或应用通过 AppRole 获取一个短期的 Token, 仅能调用 /sign 接口

# 第一步: 启用插, 进入容器执行, 或配置好本地 VAULT_ADDR 后执行
vault secrets enable ethereum

# 第二步: 创建钱包(私钥)

# 让 Vault 生成新钱包, 这会返回一个以太坊地址(如 0xabc...), 但不会返回私钥
vault write ethereum/accounts/my-sepolia-wallet

# 方法 2: 导入现有私钥
vault write ethereum/accounts/import-wallet \
    private_key="你的十六进制私钥"


## 第三步: 请求签名(交易)
# 当你的 Sepolia 节点需要发送一笔交易时, 应用构造好交易 RLP 编码或交易 JSON, 发送给 Vault:
# Vault 会返回一个 signed_transaction, 直接将其广播到以太坊网络即可
```bash
vault write ethereum/accounts/my-sepolia-wallet/sign \
    transaction='{"to":"0x...","value":"1000000000000000000","gas":21000,"gas_price":"20000000000"}'

分层确定性钱包 (HD Wallet)

Vault 支持 BIP-32/BIP-44

在 Vault 中存储一个助记词 (Mnemonic)
通过不同的路径衍生出无数个地址(如 m/44’/60’/0’/0/1)
只需要备份一次 Vault, 就能管理整个钱包矩阵

deploy

准备镜像

`1`	`docker pull hashicorp/vault:1.21`

https://hub.docker.com/r/hashicorp/vault

dev 模式

不持久化

注意: 添加 VAULT_DEV_ROOT_TOKEN_ID 后会强制为开发模式

services:
  vault:
    image: hashicorp/vault:1.21
    container_name: vault
    restart: always
    environment:
      VAULT_DEV_ROOT_TOKEN_ID: xxxxxxxxxxxxxewofoeiwoiieo
      VAULT_ADDR: "=http://0.0.0.0:8200"
      TZ: Asia/Shanghai
      LANG: en_US.UTF-8
    cap_add:
      - IPC_LOCK
    ports:
      - 8200:8200/tcp

`1`	`docker exec -it vault-dev sh vault status # 输出 Sealed: false 即正常`

单节点-持久化

mkdir -p /opt/vault/{config,data,logs}
chown -R 100:100 /opt/vault/    # Vault 默认用户 ID 是 100

docker run -d --name vault-dev \
  -p 8200:8200 \
  -v /opt/vault/config:/vault/config \
  -v /opt/vault/data:/vault/data \
  --cap-add=IPC_LOCK \
  hashicorp/vault:latest \
  server

vault.hcl

api_addr = "http://127.0.0.1:8200"
cluster_addr = "http://127.0.0.1:8201"
ui = true

storage "raft" {
  path    = "/vault/data"
  node_id = "node1"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 1       # 开发环境禁用 TLS
}

单节点-持久化-compose

volumes:
  vault_volume:
    name: vault_volume

services:
  vault:
    image: hashicorp/vault:1.21
    container_name: vault
    restart: always
    environment:
      VAULT_ADDR: "=http://0.0.0.0:8200"
      TZ: Asia/Shanghai
      LANG: en_US.UTF-8
    cap_add:
      - IPC_LOCK

    networks:
      - core
    ports:
      - 8200:8200/tcp
    volumes:
      - vault_volume:/vault
      - ./vault.hcl:/config/vault.hcl:ro
    command:
      - "server"
      - "-config=/config/vault.hcl"
    labels:
      - "service_name=vault"
    logging:
      options:
        labels: "service_name"

vault.hcl

ui = true                       # 启用 Web UI
default_lease_ttl = "168h"      # 默认租约 7 天
max_lease_ttl     = "720h"      # 最大租约 30 天

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 1
}

storage "file" {
  path = "/vault/file"
}

三节点模式

Storage: 使用 Raft;

Networking: 节点间通过 8201 端口同步数据;

Auto-Unseal: 建议配合云厂商的 KMS 使用(如阿里云 KMS, AWS KMS)

初始化
会生成 5 个 Unseal Keys

`1`	`docker exec -it vault-1 vault operator init`

解封
每个节点都需要, 输入3/5个分片密钥

`1`	`vault operator unseal`

docker-compose.yml

services:
  vault-1:
    image: hashicorp/vault:latest
    container_name: vault-1
    volumes:
      - ./vault-1/config:/vault/config
      - ./vault-1/data:/vault/data
    cap_add:
      - IPC_LOCK
    command: server
    ports:
      - "8200:8200"
    environment:
      VAULT_ADDR: 'http://127.0.0.1:8200'

  vault-2:
    image: hashicorp/vault:latest
    container_name: vault-2
    volumes:
      - ./vault-2/config:/vault/config
      - ./vault-2/data:/vault/data
    cap_add:
      - IPC_LOCK
    command: server
    ports:
      - "8202:8200"

  vault-3:
    image: hashicorp/vault:latest
    container_name: vault-3
    volumes:
      - ./vault-3/config:/vault/config
      - ./vault-3/data:/vault/data
    cap_add:
      - IPC_LOCK
    command: server
    ports:
      - "8203:8200"

vault-1.hcl

api_addr = "http://vault-1:8200"        # 业务可用地址
cluster_addr = "http://vault-1:8201"    # 节点通信地址
ui = true

listener "tcp" {
  address     = "0.0.0.0:8200"
  cluster_address = "0.0.0.0:8201"
  tls_disable = 1
}

storage "raft" {
  path    = "/vault/data"
  node_id = "vault-1"

  # 初始启动时指定其他节点地址, 或者通过 retry_join 自动发现
  retry_join {
    leader_api_addr = "http://vault-2:8200"
  }
  retry_join {
    leader_api_addr = "http://vault-3:8200"
  }
}

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"`