在重新应用之前，先运行验证、捕获针对性的调试日志并隔离故障范围，可以让 Terraform 故障排除更快。

本指南适用于初学者到中级 Terraform 用户，他们需要在基础设施上拥有可重复的调试工作流程。它专注于您可以在实时项目中立即运行的操作，而不是抽象的故障排除理论。

您将在运行 apply 之前验证配置质量，启用并解释 TF_LOG 输出，诊断 terraform apply 故障，并使用依赖图解决循环错误。您还将调和漂移的状态，使用生命周期控制进行更安全的更新，并修复阻止初始化或规划的 provider 版本冲突。

最终，您将拥有一个以检查清单驱动的 Terraform 错误调试流程，减少猜测和重复失败的 apply 操作。

• 在每次 apply 之前运行 terraform fmt -recursive 和 terraform validate，以尽早捕获格式、语法和类型错误。
• 在诊断故障时设置 TF_LOG=DEBUG 和 TF_LOG_PATH=./terraform.log，以便将 provider API 调用和错误响应捕获到一个文件中。
• 按顺序阅读 terraform apply 错误：资源地址、provider 响应和源文件引用，然后使用 terraform plan 确认变更路径。
• 使用 terraform graph 识别循环依赖，并通过移除相互引用或将共享值移入 locals 来打破循环。
• 在使用 state rm 或 import 之前，使用 terraform state list 检查已跟踪的资源，并使用 terraform apply -refresh-only 安全地调和漂移。
• 使用 lifecycle 设置，如 ignore_changes 和 create_before_destroy，以实现受控行为；避免使用隐藏真实漂移的通用抑制模式。
• 通过在 required_providers 中固定约束并使用 terraform init -upgrade 重新解析来解决 provider 版本冲突，然后提交 .terraform.lock.hcl。

• 一个 Personal Access Token，您可以通过 Control Panel 创建。相关说明可在产品文档 How to Create a Personal Access Token 中找到。
• 在本地机器上安装 Terraform，并使用 provider 设置了一个项目。完成 How To Use Terraform with 教程的步骤 1 和 步骤 2，并确保将项目文件夹命名为 terraform-troubleshooting，而不是 loadbalance。在步骤 2 中，不要包含 pvt_key 变量和 SSH key resource。
• 对 terraform init、terraform plan 和 terraform apply 的基本熟悉。

在运行 apply 之前执行格式化和静态验证，这样可以在调用 provider API 之前捕获本地问题。

运行 terraform fmt 捕获格式错误

使用 terraform fmt 来标准化项目中的 HCL 格式，这样审阅者和自动化工具在 planning 或 applying 之前就能看到一致的配置。

terraform fmt -recursive

该命令会重写不符合 Terraform 规范样式的文件。常见的修复包括块内的缩进和对齐。

# 之前
resource "_droplet" "web" {
image="ubuntu-22-04-x64"
name   =   "web-1"
 region="nyc3"
size= "s-1vcpu-1gb"
}

# 之后
resource "_droplet" "web" {
  image  = "ubuntu-22-04-x64"
  name   = "web-1"
  region = "nyc3"
  size   = "s-1vcpu-1gb"
}

如果所有文件都已经格式化，terraform fmt -recursive 不会打印任何文件路径并成功退出。如果文件被重写，Terraform 会打印每个更新的路径。

Output
terraform fmt -recursive
droplets.tf
variables.tf

运行 terraform validate 捕获语法和逻辑错误

运行 terraform validate 来检查配置语法、参数名称和类型约束，在调用 provider 之前进行验证；它不会验证 API 级别的条件，如凭证、配额或区域可用性。

terraform validate

验证失败通常会精确指出资源、参数和文件位置。这个例子显示 Droplet 资源缺少必需参数：

Output
terraform validate
╷
│ Error: Missing required argument
│
│   on droplets.tf line 1, in resource "_droplet" "web":
│    1: resource "_droplet" "web" {
│
│ The argument "size" is required, but no definition was found.
╵

修正资源后再次运行验证：

resource "_droplet" "web" {
  image  = "ubuntu-22-04-x64"
  name   = "web-1"
  region = "nyc3"
  size   = "s-1vcpu-1gb"
}

Output
terraform validate
Success! The configuration is valid.

当变量输入可能漂移到无效值时，添加显式的验证规则。这种模式可以在 planning 之前阻止无效值：

variable "test_ip" {
  type    = string
  default = "8.8.8.8"

  validation {
    condition     = can(regex("\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}", var.test_ip))
    error_message = "The provided value is not a valid IP address."
  }
}

regex() 函数测试模式，can() 将函数成功转换为布尔值，Terraform 可以在验证期间强制执行。

当 terraform apply 失败并显示出错原因但未说明为什么时，TF_LOG 是下一个要使用的工具。它暴露了 Terraform core 和 provider 之间的完整对话，包括每个 API 调用、每个响应码以及每个内部评估步骤。没有它，你只能看到错误摘要；有了它，你就能看到完整的对话记录。

TF_LOG 日志级别详解

TF_LOG 控制 Terraform 在命令执行期间发出的最低日志详细程度。

如果你将 TF_LOG 设置为任何未识别的值，Terraform 将默认使用 TRACE。TF_LOG 设置的是最低详细程度下限，而不是严格过滤器。例如，设置 DEBUG 仍然会显示 INFO、WARN 和 ERROR 行。

设置 TF_LOG_PATH 将日志写入文件

对于大型配置，将日志写入文件，这样输出保持可搜索，并且避免在终端滚动缓冲区中丢失上下文。

export TF_LOG=DEBUG
export TF_LOG_PATH=./terraform.log

捕获所需的日志后，取消设置这两个变量，让正常运行保持安静：

unset TF_LOG
unset TF_LOG_PATH

解读 TF_LOG 输出：需要关注的内容

首先关注 API 状态码、请求目标，以及失败发生时 Terraform 正在创建的资源。

Output
2024-06-18T10:42:11.223Z [INFO]  Terraform version: 1.8.5
2024-06-18T10:42:11.971Z [DEBUG] provider.terraform-provider-_v2.38.1: POST https://api.example.com/v2/droplets
2024-06-18T10:42:12.214Z [DEBUG] provider.terraform-provider-_v2.38.1: Response code: 401
2024-06-18T10:42:12.215Z [ERROR] provider.terraform-provider-_v2.38.1: Error creating droplet: POST https://api.example.com/v2/droplets: 401 Unable to authenticate you
Error: Error creating droplet: POST https://api.example.com/v2/droplets: 401 Unable to authenticate you

分解每行告诉你什么信息：启动时的 [INFO] 行确认运行的是哪个 Terraform 二进制文件，这可以排除版本不匹配问题，避免浪费时间。第一个 [DEBUG] 行显示 provider 调用的确切 HTTP 方法和端点，让你知道 Terraform 是否到达了 API。第二个 [DEBUG] 行在 Terraform 将其格式化为人类可读错误之前给出原始响应码，这在格式化消息模糊不清时很有用。[ERROR] 行是需要采取行动的那一行：它包含 provider 的确切失败原因，在本例中是 401，表示请求到达了但身份验证失败。

当看到 401 时，解决方案是验证你的 token 是否已导出且具有正确的 scopes：

echo $_TOKEN

如果没有输出，则当前 shell 会话中该变量未设置。重新导出它并重新运行命令。如果输出了值但 401 仍然存在，则 token 存在但缺少你正在管理的资源类型的写入权限。从 Control Panel 生成一个具有完整读/写权限的新 token。

对于滚动不实际的大型日志文件，通过搜索第一个 ERROR 行来缩小输出范围到失败窗口，并阅读其上方的 DEBUG 行：

grep -n "\[ERROR\]" terraform.log

-n 标志会打印行号。将该编号赋值给变量并查看周围上下文：

LINE=150  # 用 grep 输出中的行号替换
sed -n "$((LINE-10)),$((LINE+2))p" terraform.log

这会给你失败前面的十行 DEBUG 行，这几乎总能提供足够的上下文来识别根本原因。

使用快速扫描仅提取日志文件中的警告和错误行：

grep -E "\[ERROR\]|\[WARN\]" terraform.log

将失败的 apply 视为一个结构化的信号，然后在重试前缩小失败的范围。

阅读 terraform apply 错误输出

首先从失败块中提取四个关键字段：resource address、error type、provider response 和 source file reference。

Output
terraform apply -var "do_token=${DO_PAT}"
_droplet.web: Creating...
╷
│ Error: Error creating Droplet: POST https://api.example.com/v2/droplets: 422 (request "9c2fbb70-xxxx"): You specified an invalid region.
│
│   with _droplet.web,
│   on droplets.tf line 1, in resource "_droplet" "web":
│    1: resource "_droplet" "web" {
│
╵

在这里，_droplet.web 是 resource address，422 表示无效的请求数据，provider response 说明 region 无效，而 droplets.tf line 1 指明了需要修正的确切块。

使用 terraform plan 隔离问题

在重新尝试 apply 之前运行 terraform plan，以确认 Terraform 打算进行的更改，并检查是否存在隐藏的 drift 或冲突。

terraform plan -var "do_token=${DO_PAT}"

一个有用的 plan 输出模式是针对您未打算更改的 resource 的意外 replacement 或冲突：

Output
Terraform will perform the following actions:

  # _droplet.web must be replaced
  -/+ resource "_droplet" "web" {
      ~ region      = "nyc3" -> "sfo3" # forces replacement
        id          = "412345678"
        name        = "web-1"
        # ... truncated ...
    }

Plan: 1 to add, 0 to change, 1 to destroy.

如果 replacement 不是预期的，您需要确定更改是源于您的 configuration 还是 state file。请按顺序检查以下三个来源：

首先，检查变量值是否发生了变化。如果 region 是从带有默认值的变量读取的，请验证默认值未被修改，并且没有 -var 标志或 terraform.tfvars 文件将其覆盖为不同的值。

其次，检查 resource 是否在 Terraform 外部被修改。打开 Control Panel 并将 resource 的当前属性与您的 configuration 声明进行比较。如果它们不同，则 drift 是原因。运行 terraform apply -refresh-only 来更新 state，然后重新运行 plan。

第三，检查 provider version 是否发生了变化。某些 provider 升级会重命名或重组 resource 参数，这可能导致 Terraform 看到意图上不存在的 diff。如果您最近更新了 lock file，请参阅步骤 7 获取完整的 provider 升级验证工作流程。

使用 -target 应用单个 resource

仅在已知良好的一个 resource 必须继续前进，而您将损坏的依赖推迟到单独修复时，才使用 -target 进行恢复。

terraform apply -target=_droplet.web -var "do_token=${DO_PAT}"

通过移除循环引用来打破循环错误，从而使 Terraform 能够计算出线性的执行顺序。

什么是 Terraform 循环错误

Error: Cycle: resource_a, resource_b 表示 Terraform 检测到一个无法解析的循环依赖。两个或多个资源直接相互引用，或通过输出和 locals 间接相互引用，因此图评估无法确定哪个资源应该先创建。

如何使用 terraform graph 检测循环错误

生成依赖图并检查边以定位相互引用：

terraform graph | dot -Tsvg > graph.svg

dot 命令是 Graphviz 的一部分。在 Ubuntu 上可以通过以下命令安装：

sudo apt install graphviz

在生成的 graph.svg 中，查找双向连接的节点，这表示 Terraform 报告的循环路径。如果 Graphviz 不可用，可以运行 terraform graph 并直接阅读原始 DOT 输出：

terraform graph

在 DOT 输出中，循环表现为两个资源各自在单独的行上将对方列为依赖：

输出
digraph {
  compound = "true"
  "[root] _droplet.web_a (expand)" ->
    "[root] _droplet.web_b (expand)"
  "[root] _droplet.web_b (expand)" ->
    "[root] _droplet.web_a (expand)"
}

当你看到两个资源像这样相互指向时，这对就是循环。DOT 输出中的资源名称与 Terraform 在 Error: Cycle 消息中报告的地址匹配。

如何修复 Terraform 循环错误

修复方法取决于资源实际共享的内容。如果两个资源需要相同的静态配置字符串，将该字符串移到 locals 块中，使每个资源从单一真相来源读取，而不是相互读取。在这个例子中，两个 Droplet 通过 user_data 传递相同的 cloud-init 脚本名称。循环引用存在是因为它们相互读取，而不是从共享的 local 读取。

如果依赖的是运行时属性，例如资源创建后才存在的 IP 地址，则无法使用 locals 解决循环。在这种情况下，架构本身需要改变：只有一个资源可以引用另一个，且引用必须单向流动。被引用的资源必须先创建，这意味着完全移除反向引用，而不是移动它。

# 修改前：循环依赖
resource "_droplet" "web_a" {
  image     = "ubuntu-22-04-x64"
  name      = "web-a"
  region    = "nyc3"
  size      = "s-1vcpu-1gb"
  user_data = _droplet.web_b.ipv4_address
}

resource "_droplet" "web_b" {
  image     = "ubuntu-22-04-x64"
  name      = "web-b"
  region    = "nyc3"
  size      = "s-1vcpu-1gb"
  user_data = _droplet.web_a.ipv4_address
}

# 修改后：共享值移到 locals，无循环引用
locals {
  shared_config = "cloud-init-bootstrap"
}

resource "_droplet" "web_a" {
  image     = "ubuntu-22-04-x64"
  name      = "web-a"
  region    = "nyc3"
  size      = "s-1vcpu-1gb"
  user_data = local.shared_config
}

resource "_droplet" "web_b" {
  image     = "ubuntu-22-04-x64"
  name      = "web-b"
  region    = "nyc3"
  size      = "s-1vcpu-1gb"
  user_data = local.shared_config
}

状态漂移发生在您的实际基础设施和 Terraform 的状态文件描述不同的事物时。在 DigitalOcean 上，漂移通常由通过 Control Panel 手动进行的更改、在 Terraform 之外调整大小或添加标签的资源，以及由 Terraform 未发起的自动化进程重建或替换的 Droplets 导致。

第一个信号通常是 terraform plan 输出，显示了您未在配置中进行的更改提案。如果计划显示您未触及的属性存在差异，并且您未更改相应的变量或默认值，则状态漂移很可能是原因。在进一步调查之前，先运行 terraform apply -refresh-only，以便 Terraform 重新读取基础设施的当前状态并更新其状态文件以匹配。只有在刷新之后，您才应决定是接受漂移、在 Control Panel 中修正它，还是让 Terraform 在下一次 apply 时调和它。

运行 terraform state list 检查状态文件

使用 terraform state list 打印状态中当前跟踪的所有资源地址，尤其是在执行任何 state rm 或 import 操作之前。

terraform state list

示例输出：

Output
_droplet.web
_loadbalancer.public
_domain.example

首先确认确切的地址可以防止意外移除或导入错误的对象。

如果您期望看到的资源在列表中缺失，则意味着 Terraform 没有记录管理它。这发生在资源在 Control Panel 中手动创建时、使用 terraform state rm 从状态中移除时，或之前的 terraform apply 中途失败且资源创建从未记录时。在这种情况下，导入该资源，以便 Terraform 今后能够管理它：

terraform import _droplet.web <droplet-id>

将 <droplet-id> 替换为来自 Control Panel 或 API 的数字 ID。导入后，运行 terraform plan 以确认 Terraform 在导入的状态和您的配置之间未看到差异。如果计划显示更改，请在应用之前更新配置以匹配实际的资源属性。

使用 terraform refresh 调和状态与实际基础设施

从 Terraform 0.15 开始，独立的 terraform refresh 命令已被弃用，转而推荐使用仅刷新模式的应用：

terraform apply -refresh-only -var "do_token=${DO_PAT}"

预期的提示和输出：

Output
Terraform will perform the following actions:
  ~ update in-place _droplet.web

Do you want to perform these actions?
  Terraform will write these changes to the state without modifying any real infrastructure.
  Only 'yes' will be accepted to approve.

Enter a value: yes

Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

手动从状态中移除损坏的资源

当状态条目损坏或您打算在受控条件下重新导入对象时，从状态中移除资源。

terraform state rm _droplet.web

使用生命周期控制来减少可避免的失败，同时保持漂移可见且可管理。

在 lifecycle 块中使用 ignore_changes

当资源的某个属性被外部进程修改，而你不希望 Terraform 在每次 apply 时将其回滚时，请设置 ignore_changes。例如，tags 是一个常见的例子。如果你的团队通过 Control Panel 或 Terraform 之外的标记自动化工具为 Droplets 添加 tags，那么每次后续的 terraform plan 都会将这些 tags 显示为意外漂移，并建议移除它们。将 tags 添加到 ignore_changes 中，会告诉 Terraform 停止跟踪该属性，而不影响它对资源其他部分的的管理。

resource "_droplet" "web" {
  image  = "ubuntu-22-04-x64"
  name   = "web-1"
  region = "nyc3"
  size   = "s-1vcpu-1gb"

  lifecycle {
    ignore_changes = [tags]
  }
}

ignore_changes 接受特定属性或 all。在生产环境中避免使用 all，因为它会隐藏所有漂移，包括你必须检测和审查的变更。

使用 create_before_destroy 避免删除错误

对于无法容忍删除和替换之间存在间隙的资源，请启用 create_before_destroy。默认情况下，Terraform 会在创建替换资源之前销毁现有资源，这意味着旧资源在新的可用之前就已经消失。对于引用 TLS 证书的负载均衡器来说，这个时间窗口会导致请求在没有有效证书的情况下被服务。

resource "_certificate" "tls" {
  name    = "example-cert"
  type    = "lets_encrypt"
  domains = ["example.com"]

  lifecycle {
    create_before_destroy = true
  }
}

一个常见情况是替换负载均衡器使用的 _certificate。首先创建替换证书可以避免没有有效证书附着的窗口。

理解 terraform 在 apply 时忽略错误

Terraform 不提供原生标志来忽略 apply 时的所有错误。

当人们搜索“terraform ignore errors on apply”时，他们通常需要使用 ignore_changes 进行选择性漂移抑制，或使用 -target 进行部分恢复。另一个有用的调试控制是降低并行度，它会顺序应用资源，从而确定性地暴露第一个失败的资源：

terraform apply -parallelism=1 -var "do_token=${DO_PAT}"

降低并行度会减慢执行速度，但它使大型配置中许多并发操作的失败顺序更容易追踪。

明确固定 provider 和 CLI 版本，确保在不同环境中初始化时保持可重现性。

在 terraform.required_providers 中检查所需 Provider 版本

在 required_providers 和 required_version 中定义约束，以避免意外升级和不匹配错误。

terraform {
  required_providers {
     = {
      source  = "/"
      version = "~> 2.0"
    }
  }
  required_version = ">= 1.5"
}

Terraform 支持多种版本约束运算符：

• ~> 允许在指定边界内进行 patch 或 minor 更新。例如：~> 2.0 接受 2.0、2.1、2.38，但不接受 3.0。
• > 和 < 强制执行严格的大于或小于边界。例如：> 2.30, < 3.0。
• >= 和 <= 包含指定的边界版本。例如：>= 1.5, <= 1.8.5。
• != 排除已知的有问题的发布版本。例如：>= 2.0, != 2.34.0, < 3.0。

您可以使用逗号组合多个组，Terraform 要求每个组都匹配后才会选择版本。

运行 terraform init -upgrade 以解决 Provider 版本不匹配

当 .terraform.lock.hcl 固定了一个不再满足配置中更新约束的 provider 版本时，运行 terraform init -upgrade。

terraform init -upgrade

典型的输出包括 provider 重新解析和锁文件更新：

Output
Initializing the backend...
Initializing provider plugins...
- Finding / versions matching "~> 2.0"...
- Installing / v2.38.1...
- Installed / v2.38.1 (signed by HashiCorp)

Terraform has made some changes to the provider dependency selections recorded
in the .terraform.lock.hcl file.

成功初始化后，提交更新的 .terraform.lock.hcl，以确保每个团队成员和 CI 作业使用相同的已解析 provider 版本。

提交前，通过针对非生产工作区或代表性配置运行 plan 来验证升级的 provider 是否引入了破坏性变更：

terraform plan -var "do_token=${DO_PAT}"

审查 plan 输出，检查是否存在升级前不存在的意外资源替换或属性变更。Provider 的变更日志发布在 provider releases 页面。 在生产环境中应用前，请检查您升级到的版本的变更日志。

Q: terraform apply 失败时，首先检查什么？

运行 terraform validate 以确认配置没有语法错误，然后重新运行 terraform plan 来隔离确切的资源和错误，然后再尝试 apply。首先检查 plan 输出可以防止重新触发相同的失败并浪费 API 配额。此序列还将调查范围缩小到配置问题与 provider/API 问题之间。

Q: 如何在 Terraform 中启用调试日志？

在运行任何 Terraform 命令之前设置 TF_LOG=DEBUG。对于大型配置，使用 TF_LOG_PATH 将日志写入文件而不是 stdout，这样终端输出更容易扫描。完成后取消设置这两个变量，以避免后续运行时的性能开销。

Q: Terraform 循环错误是什么原因引起的，如何修复？

当两个或多个资源相互引用时，会发生循环错误，从而创建 Terraform 无法解析为有序执行计划的循环依赖。运行 terraform graph 来可视化依赖树，然后通过重构资源参数或将共享值提取到 local 中来移除循环引用。重构后，重新运行 terraform plan 以验证 Terraform 是否能构建有效的执行图。

Q: Terraform 能在 apply 时忽略错误吗？

Terraform 不支持在 apply 期间忽略所有错误的标志。使用 lifecycle { ignore_changes = [...] } 来抑制特定属性的漂移，或者使用 -target 只应用已知良好的资源，同时推迟问题资源。对于顺序故障隔离，设置 -parallelism=1。

Q: 如何修复 Terraform 状态锁错误？

如果之前的 apply 被中断且锁未释放，运行 terraform force-unlock LOCK_ID，将 LOCK_ID 替换为错误消息中打印的 ID。在强制解锁之前确认没有其他 apply 进程正在运行，因为释放活动锁可能会损坏状态文件。在团队环境中，还需检查 CI 管道以确保没有远程运行仍在活动。

Q: 如何排查 Terraform 中的 provider 版本冲突？

检查 required_providers 块中的版本约束，并验证它们与您的 Terraform 版本兼容。运行 terraform init -upgrade 来重新解析并更新锁文件。如果约束过于严格，则放宽版本范围并重新运行 init。

Q: terraform state list 做什么用，何时使用？

terraform state list 打印当前状态文件中跟踪的所有资源地址。在运行 terraform state rm、terraform import 或 terraform refresh 之前使用它，以确认确切的资源地址并避免操作错误的资源。它在事件响应中也很有用，当您需要快速库存 Terraform 当前认为它管理的资源时。

Q: 如何针对 具体调试 Terraform？

在运行针对 资源的任何 Terraform 命令之前，设置 TF_LOG=DEBUG 和 TF_LOG_PATH=./terraform.log。在日志文件中搜索 API 返回的 HTTP 状态码：401 表示 token 缺失或无效，422 表示请求负载被拒绝（常见于错误的 region slug 或无效大小），429 表示您已达到 API 速率限制，应减少 -parallelism 或添加重试延迟。有关完整演练步骤，请参阅本教程的第 2 步。

现在您可以使用可重复的过程来排查 Terraform 问题：在 apply 前验证配置，启用并阅读调试日志，诊断 apply 和循环错误，安全检查和修复状态，应用 lifecycle 弹性模式，并通过受控升级解决 provider 版本冲突。遵循此序列可以减少重复失败并提高日常基础设施变更的可靠性。

接下来阅读：How To Use Terraform with 、How To Manage Infrastructure with Terraform（系列）、How To Structure a Terraform Project、How To Import Existing Assets into Terraform，以及 How To Use Terraform with Spaces。