Terraform 远程状态和锁定

FreeGuideOnline 最新 2026-07-09

Terraform 远程状态与状态锁定

Terraform 的状态文件（terraform.tfstate）是基础设施真实状态的唯一记录。它将代码中的资源定义与云上实际资源进行映射。在团队协作中，将状态文件存储在本地会立刻引发两类严重问题：

  • 状态冲突：两人同时运行 terraform apply 会导致状态文件互相覆盖，甚至破坏基础设施。
  • 安全与持久性：本地文件容易丢失，且无法安全地共享敏感信息（如数据库密码）。

远程状态（Remote State）和状态锁定（State Locking）正是为解决这些问题而设计的。

1. 为什么需要远程状态

1.1 团队协作

将状态文件存储在共享的远程后端（如 AWS S3、Azure Storage、Terraform Cloud 等）后，所有团队成员都读写同一份权威状态。任何修改都会立刻对其他成员可见，彻底消除了“哪个状态是最新的”这类疑问。

1.2 安全存储

远程后端通常提供：

  • 服务端加密（SSE）与传输加密（TLS）
  • 细粒度的访问控制（IAM 策略、RBAC）
  • 状态文件不再需要被手动分发给使用者，也无需提交到版本控制系统（这本身就是一种安全反模式）。

1.3 自动化流水线

CI/CD 流水线（如 GitHub Actions、GitLab CI）在运行时同样需要访问远程状态。没有远程后端，自动化作业要么无权访问本地状态，要么只能通过临时手段共享，极易出错。

2. 状态锁定：防止竞态条件

状态锁定是一种互斥机制：同一时间只允许一个进程修改状态。当某个用户或流水线正在执行 terraform apply 时，Terraform 会自动锁定远程状态；其他并发操作会被阻塞，直到锁定释放。

2.1 没有锁定的破坏场景

假设两位工程师 Alice 和 Bob 同时触发 apply：

  1. Alice 和 Bob 读取同一份本地状态。
  2. Alice 创建了一台 EC2 实例，状态文件被更新。
  3. Bob 创建了另一个安全组，状态文件也被更新，但 Bob 执行的写入会覆盖 Alice 的更改。
  4. Alice 的资源“幽灵”般地存在于云上，但状态文件中没有记录 —— 下次 plan 会显示资源将被销毁或产生偏差。

远程锁定可彻底避免这种情况。

2.2 支持锁定的后端

并非所有远程后端都原生支持锁定。最常用的生产级组合是 S3 后端 + DynamoDB 表，这也是 AWS 官方推荐的方案。

  • S3：存储状态文件
  • DynamoDB：提供强一致性、自动过期的锁定记录

其他支持锁定的后端：Terraform Cloud/Enterprise、AzureRM（使用 Storage Account 的租约机制）、Google Cloud Storage（通过对象锁）等。

3. 实战：配置 S3 远程后端与 DynamoDB 锁定

以下示例演示如何从零开始配置一个安全的远程状态环境。

3.1 前置条件

  • AWS CLI 已安装并配置好凭证
  • Terraform ≥ 1.0
  • 一个 S3 存储桶（用于状态）和一个 DynamoDB 表（用于锁定）—— 你可以通过 Terraform 创建它们，但建议先手动创建，避免循环依赖。

3.2 创建 S3 存储桶与 DynamoDB 表

使用 AWS CLI 快速创建基础资源：

# S3 存储桶（启用版本控制，以防状态误删）
aws s3api create-bucket \
    --bucket my-terraform-states \
    --region us-east-1

aws s3api put-bucket-versioning \
    --bucket my-terraform-states \
    --versioning-configuration Status=Enabled

# DynamoDB 表（分区键为 LockID，类型为字符串）
aws dynamodb create-table \
    --table-name terraform-locks \
    --attribute-definitions AttributeName=LockID,AttributeType=S \
    --key-schema AttributeName=LockID,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST \
    --region us-east-1

3.3 在后端配置块中声明远程状态

在你的 Terraform 根模块目录下，创建或修改 backend.tf：

terraform {
  backend "s3" {
    bucket         = "my-terraform-states"
    key            = "prod/network/terraform.tfstate"   # 任意路径，用于组织多项目
    region         = "us-east-1"
    encrypt        = true                              # 启用 SSE-S3 加密
    dynamodb_table = "terraform-locks"                # 关联锁表
  }
}
  • key：状态对象在存储桶内的路径。可以为不同环境/项目使用不同的 key（如 dev/app/terraform.tfstate）。
  • encrypt：强烈建议开启，避免状态文件以明文存储。

3.4 初始化并迁移现有状态

如果当前目录已有本地状态，运行 init 时 Terraform 会询问是否将状态迁移到远程后端：

terraform init -migrate-state

输入 yes 确认后，本地状态会被上传到 S3，之后的任何操作不再依赖本地文件。如果这是全新配置，直接 terraform init 即可。

3.5 验证锁定机制

打开两个终端窗口，同时执行以下命令（确保在同一个模块目录）：

终端 1：

terraform apply -auto-approve

在 apply 执行期间，进入终端 2 并运行：

terraform plan

终端 2 的输出会显示：

Acquiring state lock. This may take a few moments...
Error: Error acquiring the state lock
...

只有当终端 1 完成并释放锁后，终端 2 的操作才能继续。在 DynamoDB 表内查看，会发现一条 LockID 对应的锁定记录。

4. 远程状态管理与组织最佳实践

4.1 按环境隔离存储桶与 Key

  • 方案 A（推荐）：使用独立存储桶区分生产与非生产环境（如 prod-tfstate 和 dev-tfstate），IAM 策略严格控制。
  • 方案 B：共用一个存储桶，通过不同的 key 前缀区分环境，例如 prod/vpc/terraform.tfstate、dev/vpc/terraform.tfstate。

无论哪种方案，确保每个环境的凭证权限最小化，杜绝开发人员意外修改生产状态。

4.2 使用版本控制保护状态历史

S3 版本控制不是可选项，而是必需品。它能让你回溯到某个历史状态，在状态发生灾难性损坏时快速恢复。注意：恢复时必须谨慎，避免回滚后实际基础设施与状态再次不匹配。

4.3 禁止手动修改远程状态

所有更改都通过 terraform apply 和标准的 CLI 命令完成。严禁直接下载、编辑、重新上传状态文件，这会导致锁定机制被绕过，且 S3 的 MD5 校验会破坏后续操作。

4.4 状态文件导入策略

若某些资源未在 Terraform 中管理，使用 terraform import 将资源引入状态，而非手动拼接状态 JSON。

4.5 数据源的跨状态引用

当需要在多个项目之间共享输出（如一个项目创建的 VPC ID 被另一个项目引用）时，使用 terraform_remote_state 数据源：

data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = "my-terraform-states"
    key    = "prod/network/terraform.tfstate"
    region = "us-east-1"
  }
}

resource "aws_instance" "web" {
  subnet_id = data.terraform_remote_state.network.outputs.public_subnet_id
}

更解耦的现代替代方案是使用 数据源查询云 API 或 Terraform Cloud 的变量集，但 terraform_remote_state 依然是简单场景下最直接的方式。

5. 常见故障排查

5.1 状态锁未释放（遗留锁）

如果某个操作异常中断（如网络断开），DynamoDB 中可能残留锁记录。Terraform 会提示：

Error: Error acquiring the state lock
Lock Info: ...

强行解锁（务必确认没有其他合法操作正在运行）：

terraform force-unlock <LOCK_ID>

LOCK_ID 可从错误信息中直接复制。也可以手动在 DynamoDB 表中删除对应条目。

5.2 后端配置变更失败

如果修改了 backend 块的配置（如更换 bucket），再次 terraform init 可能会拒绝运行。使用 -migrate-state 或 -reconfigure：

  • 迁移到新后端：terraform init -migrate-state
  • 完全切换后端而不迁移：terraform init -reconfigure（会忽略旧状态，通常用于开发环境）

5.3 访问拒绝（403）

检查：

  • S3 存储桶策略或 IAM 角色是否允许 s3:GetObject、s3:PutObject、s3:DeleteObject 以及 s3:ListBucket
  • DynamoDB 表权限：dynamodb:GetItem、dynamodb:PutItem、dynamodb:DeleteItem
  • KMS 密钥权限（如果使用了 SSE-KMS）

6. 总结

  • 远程状态 消除了本地状态的单点故障和共享难题，是所有生产级 Terraform 工作流的基石。
  • 状态锁定 是并发安全的最后一道防线，必须与远程状态配合使用。
  • S3 + DynamoDB 是 AWS 生态中最成熟、成本最低的远程后端方案。
  • 永远启用版本控制、加密和最小权限策略，让状态管理真正健壮可靠。

掌握远程状态与锁定，是迈向基础设施即代码团队协作的关键一步。立即将你的个人项目迁移到远程后端，体验丝滑的多人协同。