基础设施即代码 / 知识点
Terraform CLI 与 HCL 速查手册
初始化与校验
terraform init [options]在新项目、克隆仓库或后端与 Provider 配置变化后初始化工作目录,下载模块和 Provider;执行计划或应用变更前通常应先完成此步骤。
初始化工作目录
在首次运行 Terraform、克隆已有配置,或修改 Provider、模块来源和后端配置后使用 terraform init。它准备当前工作目录、初始化后端并获取配置依赖,使后续 terraform validate、terraform plan 和 terraform apply 可以正常工作。
基本语法
terraform init [options]最常用的初始化直接在根模块目录执行:
terraform init预期输出
Terraform has been successfully initialized!成功时会出现以上完成信息;此前的模块、后端和 Provider 初始化明细会随当前配置而变化。
常用参数
| 参数 | 什么时候用 |
|---|---|
-upgrade |
重新检查模块和 Provider 的允许版本范围,而不是优先沿用当前已选版本 |
-reconfigure |
后端配置已改变,并明确要忽略此前保存的后端设置重新配置 |
-migrate-state |
切换后端并需要尝试把现有状态迁移到新后端 |
-input=false |
CI 等非交互环境,不允许 Terraform 等待人工输入 |
-backend=false |
明确需要跳过后端初始化的特殊流程;普通项目通常不使用 |
Provider 或模块版本约束改变后,需要重新初始化时可执行:
terraform init -upgrade预期输出
Terraform has been successfully initialized!-upgrade 可能选择约束范围内更新的依赖版本,因此执行后应检查 .terraform.lock.hcl 的变化,再运行计划确认影响。
后端变更
后端地址、类型或关键配置变化后,普通 terraform init 可能要求明确选择重新配置还是迁移状态。两者目的不同:-reconfigure 接受新的后端配置但不执行已有状态迁移,-migrate-state 则用于尝试把状态复制到新的后端。
排障清单
初始化失败时优先检查 Provider Registry、模块源和后端是否能从当前网络访问,以及认证凭据是否有效。若错误明确提示配置发生变化并要求重新初始化,应根据实际变更重新执行 terraform init,不要通过删除状态文件绕过问题。
.terraform 保存当前工作目录的本地初始化数据,通常不应提交版本库;.terraform.lock.hcl 用于记录 Provider 版本选择,团队项目通常应提交并审查其变化。
terraform fmt [options] [target...]递归格式化当前目录及子模块中的 Terraform 配置文件,统一标准代码风格;适合提交前、本地检查以及 CI 中的格式门禁。
格式化配置
使用 terraform fmt -recursive 将当前目录及子目录中的 Terraform 配置统一为 Terraform 的规范格式。它适合提交前自动整理代码,也可以配合 -check 在 CI 中只检查格式而不修改文件。
基本语法
terraform fmt [options] [target...]当前目录及全部子目录直接执行:
terraform fmt -recursive预期输出
main.tf
modules/network/main.tf命令默认会直接改写需要格式化的文件,并列出发生修改的文件名;如果所有文件原本已经符合格式要求,可能没有输出。
常用参数
| 参数 | 作用 |
|---|---|
-recursive |
同时处理子目录中的配置文件 |
-check |
只检查,不写回文件;存在格式差异时返回非零退出码 |
-diff |
显示格式化前后的差异 |
-write=false |
禁止覆盖源文件 |
-list=false |
不列出存在格式差异的文件名 |
本地开发通常使用 terraform fmt -recursive 自动修正;CI 更适合只做检查:
terraform fmt -check -recursive预期输出
modules/network/main.tf出现文件名并返回非零退出码,表示至少有文件需要格式化。所有文件格式正确时退出码为 0,通常不输出文件名。
查看差异
希望先查看 Terraform 会怎样调整,而不修改工作区时使用:
terraform fmt -check -diff -recursive预期结果
main.tf
--- old/main.tf
+++ new/main.tf
@@ <ID> @@
<DIFF>实际 diff 行号和内容取决于文件;该组合适合 CI 日志或提交前检查,因为 -check 会阻止写回源文件。
风险与边界
terraform fmt 是格式化工具,不等价于配置正确性检查。它能够重写排版,但不能替代 terraform validate 对配置结构和引用关系的校验,更不能替代 terraform plan 对目标工作区实际变更的检查。
Terraform 不提供用于自定义 fmt 排版规则的选项,而且规范格式可能随 Terraform 版本出现小幅调整。升级 Terraform 后如果产生集中格式变化,建议单独提交格式化结果,避免与基础设施逻辑修改混在一起。
terraform validate检查配置语法、类型和内部引用是否一致,不负责验证实际远端资源;适合模块开发和 CI 检查,执行前应完成所需初始化。
验证配置
terraform validate 用于检查 Terraform 配置的语法、类型和内部一致性,适合开发阶段、代码提交前和 CI 校验。它不会访问远端资源状态或调用 Provider API,因此不能替代真实变更前的 terraform plan。
前置条件与基本语法
执行验证前,通常需要先初始化工作目录,让 Provider 和模块依赖可用。如果只需要离线检查配置结构,可以关闭 backend 初始化。
terraform init -backend=false
terraform validate预期输出:
Terraform has been successfully initialized!
Success! The configuration is valid.基本语法为 terraform validate [options]。自动化环境通常使用 -json 获取结构化诊断,避免解析人类可读文本。
CI 中读取诊断结果
在流水线中,可以使用 JSON 输出判断配置是否有效。
terraform validate -json预期结果:
{
"format_version": "1.0",
"valid": true,
"error_count": 0,
"warning_count": 0,
"diagnostics": []
}重点关注 valid、error_count 和 diagnostics。警告不会让 valid 变为 false,但 CI 可以根据团队规则决定是否阻断提交。
常见失败处理
如果提示 Provider 或模块不可用,优先重新执行 terraform init,不要误判为 HCL 语法错误。配置通过 validate 后,仍需要使用 terraform plan 检查变量、状态和远端资源是否能形成预期变更。
计划与执行
terraform plan -out=tfplan计算配置、状态与实际基础设施之间的变更并保存计划文件,便于先审查新增、修改和销毁动作;推荐用于生产变更和审批流程。
生成执行计划
terraform plan 用于计算 Terraform 将要执行的新增、修改和销毁动作。它读取配置和状态,并根据 Provider 返回的信息生成变更方案;默认情况下只生成计划,不修改基础设施。

基本语法与常用参数
常用形式如下:
terraform plan -out=tfplan常见参数:
| 参数 | 用途 | 注意事项 |
|---|---|---|
-out=FILENAME |
保存计划文件 | 可交给后续 terraform apply 执行 |
-var-file=FILENAME |
使用变量文件 | 自定义 tfvars 文件需要显式指定 |
-detailed-exitcode |
区分无变化、错误和存在变化 | 适合 CI 判断 |
-refresh=false |
跳过远端刷新 | 可能导致计划不完整 |
-target=ADDRESS |
聚焦指定资源 | 只适合特殊恢复场景 |
生成并审查计划
生产流程通常先生成计划,再人工或自动化审核:
terraform plan -out=tfplan
terraform show -no-color tfplan预期输出:
Terraform will perform the following actions:
# <RESOURCE_ADDRESS> will be updated in-place
Plan: 0 to add, 1 to change, 0 to destroy.
Saved the plan to: tfplan审查时重点关注资源动作符号、替换操作和销毁数量。执行 terraform apply tfplan 时,Terraform 会直接使用已保存计划,因此计划文件本身应视为发布审批产物。
风险与边界
计划文件可能包含输入变量、资源属性和敏感信息,不应提交 Git 或公开 CI 制品库。生产环境应限制访问,并在发布完成后清理临时计划文件。
-refresh=false 会忽略部分远端变化,可能产生错误判断;-target 可能隐藏整体配置问题,不适合作为日常发布方式。
terraform apply tfplan执行已经审查并保存的计划文件,使实际变更与审批内容保持一致;生产环境优先采用先保存 plan、再执行 apply 的方式。
应用已保存计划
用于把已审查的执行计划原样落地。terraform apply tfplan 不会重新规划,也不会再次询问是否批准;传入已保存计划本身就表示批准,适合生产发布和 CI/CD 的“计划—审批—执行”流程。
前置条件
先用目标环境的后端、工作区、变量和锁定的 Provider 版本生成计划,并在审批后保留同一个计划文件。执行前建议再次用 terraform show 确认文件内容,避免拿错环境或拿错构建产物。
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan预期输出(节选)
Saved the plan to: tfplan
...
Apply complete! Resources: <ADD_COUNT> added, <CHANGE_COUNT> changed, <DESTROY_COUNT> destroyed.<ADD_COUNT> 等数量取决于计划内容;最终的 Apply complete! 表示计划中的操作已经执行完成。若中途发生 Provider、权限或远端 API 错误,命令会以非零状态退出,不能只根据最后一行之前的资源日志判断成功。
执行语义
保存计划已经包含规划时的配置快照、输入变量和变更决策,因此应用时不能再用 -var、-var-file、-target、-replace、-destroy 或 -refresh-only 改写计划。需要改变任一规划条件时,应重新运行 terraform plan -out=tfplan 并重新审批。
-auto-approve 对已保存计划没有实际作用,因为提供计划文件已经被 Terraform 视为批准。自动化流水线应把“谁能生成计划”和“谁能执行已批准计划”作为权限边界,而不是依赖交互确认。
风险与边界
保存的计划文件可能包含敏感值,即使终端展示时已被隐藏,计划文件本身仍应按敏感制品处理。不要提交到版本库,也不要长期留在共享目录;使用受控 artifact 存储、最小权限和短保留周期。
如果计划生成后目标 state 已被其他执行更新,原计划可能变为 stale 并被拒绝。此时不要绕过检查,应基于最新 state 重新生成计划并重新审批。
兼容性
计划文件是 Terraform 的不透明格式,并记录生成它的 Terraform 版本。规划和执行阶段应固定同一 Terraform CLI 版本及对应 Provider 锁文件,避免跨版本传递计划文件。
HCL 编写与复用
variable "environment" {
type = string
default = "dev"
}通过 variable 块为模块声明显式输入接口并约束类型,避免把环境差异硬编码到资源中;适合可复用模块和多环境配置。
声明输入变量
variable 块用于定义 Terraform 模块输入接口。通过类型、默认值和验证规则约束输入,可以减少环境差异导致的配置错误。
基本语法
下面声明一个环境变量,并限制允许值范围:
variable "environment" {
type = string
default = "dev"
description = "Deployment environment"
nullable = false
validation {
condition = contains(["dev", "staging", "prod"], var.environment)
error_message = "environment must be dev, staging, or prod."
}
}
output "environment" {
value = var.environment
}default 存在时变量可选,没有默认值时调用方必须提供。nullable = false 可以禁止整个变量被设置为 null。
验证与传值
可以使用命令行参数覆盖默认值:
terraform init -backend=false
terraform validate
terraform plan -var='environment=prod'预期输出:
Success! The configuration is valid.
Changes to Outputs:
+ environment = "prod"根模块还可以通过变量文件传值。Terraform 会自动加载 terraform.tfvars、terraform.tfvars.json 和匹配规则的 *.auto.tfvars、*.auto.tfvars.json 文件;普通自定义文件如 prod.tfvars 不会自动加载,需要通过 -var-file=prod.tfvars 指定。
常用约束
生产模块建议明确声明 type,例如 string、number、bool、list(string)、map(string) 或 object。类型约束负责基础校验,业务规则再通过 validation 表达。
敏感信息可以使用 sensitive = true 隐藏 CLI 输出,但它不会自动从 state 或 plan 文件中移除。
风险与边界
变量默认值不能依赖其他资源或变量。如果需要根据多个输入计算结果,应使用 locals。
module "network" {
source = "./modules/network"
}通过 module 块调用本地或远程模块复用基础设施组件,并以输入输出建立边界;适合网络、计算、监控等重复能力的统一封装。
调用模块
用 module 块把一组 Terraform 配置作为可复用单元调用。调用方通过输入变量传值,通过输出值读取结果;本地模块适合仓库内复用,远程模块适合跨项目共享。
基本语法
下面是一个可运行的最小本地模块。根模块调用 ./modules/network,模块根据输入生成输出值,便于验证调用边界。
main.tf:
module "network" {
source = "./modules/network"
environment = "prod"
}
output "network_name" {
value = module.network.name
}modules/network/variables.tf:
variable "environment" {
type = string
}modules/network/outputs.tf:
output "name" {
value = "${var.environment}-network"
}验证:
terraform init -input=false >/dev/null
terraform apply -auto-approve -input=false >/dev/null
terraform output network_name预期输出:
"prod-network"读取时通过 module.<模块名>.<output 名> 访问模块输出;这里对应 module.network.name。
常用写法
本地模块的 source 通常使用 ./ 或 ../ 相对路径。Registry 模块应同时声明 source 和 version;Git 等 VCS 来源应通过 ref 固定标签或提交,而不是长期跟随分支头部。
模块输入只能使用该模块声明的变量,输出也必须由模块显式声明。调用方不要依赖模块目录内部的资源实现细节。
风险与边界
修改模块名、来源或路径可能改变模块地址或实际代码来源。已有状态时先检查计划;仅做地址重命名时优先使用 moved 块迁移,避免被 Terraform 识别为删除后重建。
排障清单
Module not installed:执行terraform init;修改source后重新初始化。Unsupported argument:传入了模块未声明的变量,核对模块variable定义。Unsupported attribute:读取了模块未声明的output,核对输出名。- 远程模块拉取失败:检查网络、凭据以及来源和版本引用是否可访问。
速查:模块边界只通过变量与输出传递数据,生产环境的远程来源应固定版本。
for_each = toset(["web", "api"])使用 map 或 set 的稳定键批量创建资源或模块实例并按键寻址;当实例集合会增删时,通常比依赖位置序号的 count 更易维护。
使用 for_each 创建实例
for_each 用稳定键批量创建资源或模块实例。实例地址包含键值,例如 resource.type.name["key"],因此键设计会直接影响资源生命周期管理。
基本语法
for_each 接受 map 或 set(string)。资源内部通过 each.key 获取键,map 场景还可以通过 each.value 获取对应值。
terraform {
required_version = ">= 1.4.0"
}
resource "terraform_data" "service" {
for_each = toset(["web", "api"])
input = each.key
}验证生成的实例:
terraform init -input=false
terraform apply -auto-approve -input=false
terraform state list | sort预期输出:
terraform_data.service["api"]
terraform_data.service["web"]高频用法
需要同时保存多个属性时,通常使用 map:
locals {
services = {
web = 8080
api = 9000
}
}
resource "terraform_data" "service" {
for_each = local.services
input = {
name = each.key
port = each.value
}
}此时 each.key 表示实例身份,each.value 表示该实例配置。
风险与边界
toset 会去重,因此重复字符串只会创建一个实例。如果对象本身没有稳定唯一键,应改用 map。
for_each 的 key 必须在 plan 阶段已知,不能依赖 apply 后才产生的值,否则会出现 Invalid for_each argument。
与 count 的选择
count 使用数字索引,适合固定数量资源;for_each 使用业务键,更适合成员会增删且需要保持身份稳定的集合。
状态与风险操作
terraform state list [options] [address...]列出当前工作区状态中由 Terraform 管理的资源地址,用于确认资源寻址、迁移和状态排障对象;该操作只读取状态,不修改资源。
列出状态资源
用 terraform state list 查看当前状态记录的资源地址,适合确认 Terraform 实际管理了哪些对象、查找模块内资源,以及为 state show、状态迁移等后续操作确定准确地址。该命令读取状态,不会创建、修改或销毁基础设施。
基本语法
terraform state list [options] [address...]未指定地址时列出状态中的全部资源;指定资源或模块地址时只返回匹配项。
常用选项:
| 选项 | 用途 |
|---|---|
-id=<ID> |
按远程资源 ID 查找对应的 Terraform 资源地址 |
-state=<PATH> |
指定本地状态文件;这是仅适用于 local backend 的旧式选项 |
高频用法
先确认当前工作区,再列出状态资源,避免在相邻环境中误判对象:
terraform workspace show
terraform state list预期输出:
production
aws_instance.web
module.network.aws_subnet.private[0]
module.network.aws_subnet.private[1]实际资源地址取决于当前状态。第一行来自 workspace show,后续各行是可直接用于其他状态命令的资源地址。
过滤某个模块时可直接传模块地址:
terraform state list module.network预期输出:
module.network.aws_subnet.private[0]
module.network.aws_subnet.private[1]如果已知云平台资源 ID,可反查它在 Terraform 状态中的地址:
terraform state list -id=<ID>预期输出:
module.network.aws_security_group.app仅当状态中存在与 <ID> 匹配的对象时才会输出对应地址,否则可能没有输出。
风险与边界
terraform state list 本身不修改状态或远程资源,但结果完全取决于当前工作目录、backend 和 workspace。连接到错误的远程状态时,会得到另一个环境的资源列表,后续若据此执行 state rm、state mv 或销毁操作可能造成严重误操作。
排障清单
没有输出时,优先检查当前 workspace 是否正确、backend 是否已初始化,以及该状态是否确实包含资源。远程 backend 报认证或访问错误时,应修复 backend 凭据或权限,而不是改用另一个状态文件绕过问题。
资源地址包含 for_each 键时,在 Shell 中传给后续命令通常应整体引用,例如 terraform state show 'aws_instance.web["api"]',避免引号或方括号被 Shell 错误解释。
terraform destroy [options]销毁当前配置和工作区管理的基础设施,属于高风险操作;仅在确认工作区、后端和目标环境后使用,生产环境应先审查销毁计划。
销毁基础设施
terraform destroy 会按照当前配置和状态销毁 Terraform 管理的资源。它适合清理临时环境,生产环境执行前必须确认 workspace、backend、变量和目标账号均正确。
基本语法
terraform destroy [options]该命令会生成销毁计划并要求确认。交互提示不能替代审批流程,生产环境应优先生成可审查的销毁计划。
安全执行流程
推荐先创建销毁计划:
terraform workspace show
terraform plan -destroy -out=destroy.tfplan
terraform show destroy.tfplan预期输出:
production
Plan: 0 to add, 0 to change, <N> to destroy.确认资源范围后,再执行保存的计划:
terraform apply destroy.tfplan预期结果:
Apply complete! Resources: 0 added, 0 changed, <N> destroyed.风险与保护边界
Terraform 自身也提供 lifecycle.prevent_destroy 保护。例如资源配置中启用该规则后,Terraform 会拒绝生成对应销毁计划:
resource "example_resource" "database" {
lifecycle {
prevent_destroy = true
}
}预期结果:
Error: Instance cannot be destroyed
Resource has lifecycle.prevent_destroy setprevent_destroy 属于 Terraform 配置级保护,不是独立安全机制。删除或修改该配置后保护可能消失,因此不能替代云侧删除保护、备份和权限边界。
常见注意事项
-auto-approve 会跳过人工确认,不应作为生产安全措施。-target 只能用于特殊恢复场景,长期局部销毁可能造成配置和实际资源状态不一致。
执行前发现计划包含未知资源时,应停止操作,重新核对 workspace、变量文件、backend 和身份凭据。