Terraform状态锁定迁移指南：告别DynamoDB

如果你使用Terraform已有一段时间，可能在你的基础设施代码库中散布着类似这样的后端配置。我就曾经如此。如果你像我一样，可能错过了HashiCorp的一个相当重要的公告，这将影响我们未来处理状态锁定的方式。

让我为你节省未来的麻烦：基于DynamoDB的状态锁定正在被弃用。

当我第一次听说这个消息时，也有同样的反应。在多年为状态锁配置DynamoDB表之后，HashiCorp正在逐步淘汰它，转而支持原生S3状态锁定。好消息是？新方法实际上更简单，并从你的基础设施堆栈中消除了整个AWS资源。

实际发生了什么变化？

多年来，在AWS中管理Terraform状态的标准实践如下所示：

1
2
3
4
5
6
7
8


terraform {
  backend "s3" {
    bucket         = "my-terraform-state-prod"
    key            = "network/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-lock-table"
  }
}

我们会专门为状态锁定创建一个DynamoDB表，使用正确的容量设置配置它，并在后端配置中引用它。它工作正常，但总是感觉像是我们必须维护的额外基础设施，只是为了支持我们的基础设施即代码工具。

HashiCorp认识到了这个摩擦点，并直接将原生锁定构建到S3后端中。新的配置更简洁：

1
2
3
4
5
6
7
8


terraform {
  backend "s3" {
    bucket         = "my-terraform-state-prod"
    key            = "network/terraform.tfstate"
    region         = "us-east-1"
    use_lockfile   = true
  }
}

注意到缺少了什么吗？不再有DynamoDB表引用。S3后端现在使用直接存储在S3中的锁文件内部处理锁定。

这对你的团队为何重要

这不仅仅是一个表面上的变化。理解和采用这种新方法有真正的操作优势：

降低基础设施复杂性：你为状态锁定配置的每个DynamoDB表都是另一个需要监控、付费和管理的资源。使用原生S3锁定，你完全消除了这种依赖。更少的移动部件意味着更少的潜在故障点。

简化入职流程：当将新工程师引入你的平台团队时，你不再需要解释状态管理的DynamoDB组件。心智模型变得更简单：状态存在于S3中，锁定由S3处理，所有东西都在一个地方。

成本优化：DynamoDB对读写容量单元收费。即使在按需定价的情况下，这些成本在支持不同Terraform项目的多个表中也会累积。S3锁定使用标准的S3 API调用，在规模上通常更便宜。

更好地与AWS最佳实践对齐：AWS一直在推动S3作为具有日益复杂功能的集中式数据存储。原生S3锁定利用了这些改进，而不是需要单独的数据库服务。

如何迁移现有基础设施

我最近在我们组织的大约40个不同的Terraform项目中经历了这个迁移。以下是对我们有效的操作手册：

步骤1：更新后端配置

从你的非生产环境开始。更新后端配置以移除DynamoDB表引用并添加use_lockfile参数：

1
2
3
4
5
6
7
8
9


terraform {
  backend "s3" {
    bucket         = "mycompany-terraform-state-dev"
    key            = "vpc/terraform.tfstate"
    region         = "us-west-2"
    use_lockfile   = true
    encrypt        = true
  }
}

注意我保留了encrypt = true。始终加密你的状态文件。始终如此。

步骤2：重新初始化后端

运行terraform init -reconfigure以迁移到新的锁定机制。此命令告诉Terraform重新配置后端，而不尝试迁移状态（因为状态位置本身没有改变）：

1

terraform init -reconfigure

你将看到指示Terraform正在重新配置后端的输出。此操作是安全的，不会修改你的实际基础设施。

步骤3：测试锁定机制

在广泛推出之前，验证锁定是否实际工作。打开两个终端窗口，尝试同时在两者中运行terraform plan。第二个命令应该等待，并显示有关状态被锁定的消息：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Error: Error acquiring the state lock

Error message: state is locked
Lock Info:
  ID:        abc123-def456-ghi789
  Path:      mycompany-terraform-state-dev/vpc/terraform.tfstate
  Operation: OperationTypePlan
  Who:       your-username@hostname
  Version:   1.6.0
  Created:   2025-11-04 15:23:41.123456789 +0000 UTC

这就是你想看到的。这意味着锁定机制正常工作。

步骤3：更新CI/CD流水线

不要忘记你的自动化！你的Jenkins、GitLab CI或GitHub Actions工作流也需要更新。这是一个更新的Jenkinsfile阶段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


stage('Terraform Init') {
  steps {
    sh '''
      terraform init \
        -backend-config="bucket=${TF_STATE_BUCKET}" \
        -backend-config="key=${TF_STATE_KEY}" \
        -backend-config="region=${AWS_REGION}" \
        -backend-config="use_lockfile=true"
    '''
  }
}

stage('Terraform Plan') {
  steps {
    sh 'terraform plan -out=tfplan'
  }
}

stage('Terraform Apply') {
  when {
    branch 'main'
  }
  steps {
    input message: "Deploy to production?"
    sh 'terraform apply tfplan'
  }
}

这里的关键是确保你的CI系统具有适当的IAM权限以将锁文件写入S3。

关键补充：S3桶版本控制

我艰难地学到了这一课。几个月前，一个terraform apply操作由于网络超时在半途失败。状态文件损坏了，我们没有启用版本控制。恢复该状态涉及通过将AWS控制台输出与我们的Terraform配置交叉引用，手动重建资源关系。花了四个小时和很多咖啡。

不要像过去的我一样。启用版本控制：

1
2
3
4
5
6
7


resource "aws_s3_bucket_versioning" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  versioning_configuration {
    status = "Enabled"
  }
}

启用版本控制后，对你的状态文件的每个更改都会被保留。如果出现问题，你可以直接从S3控制台或AWS CLI检索以前的版本：

1
2
3


aws s3api list-object-versions \
  --bucket my-terraform-state-prod \
  --prefix network/terraform.tfstate

这为你提供了状态更改的完整历史，允许你在需要时回滚到任何以前的版本。这就像你的基础设施状态的git历史。

新锁定机制的IAM权限

你的Terraform执行角色需要特定的S3权限来使用原生锁定功能。这是一个涵盖状态管理和锁定的最小IAM策略：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::my-terraform-state-prod/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketVersioning"
      ],
      "Resource": "arn:aws:s3:::my-terraform-state-prod"
    }
  ]
}

注意我们不再需要任何DynamoDB权限。这是少了一个需要维护和审计的策略语句。

现有DynamoDB表会发生什么？

你可能想知道是否需要立即删除你的DynamoDB状态锁表。简短的回答是：不，但你应该为此做计划。

在将所有Terraform项目迁移到使用原生S3锁定后，你的DynamoDB表将停止接收流量。它们将闲置在那里，累积最少的成本。我建议在迁移后保留它们一两周，以防你需要回滚任何配置更改。

一旦你确信使用新的锁定机制一切正常，你可以安全地删除这些表。只要确保你已经首先更新了每个Terraform项目。一个被遗忘的仍然引用旧DynamoDB表的仓库将在有人尝试使用它时导致神秘的失败。

更大的图景

这种弃用是Terraform生态系统中更广泛模式的一部分：简化和整合。HashiCorp一直在稳步减少外部依赖，并将更多功能直接构建到核心提供程序中。

我们在向原生Terraform Cloud状态管理的转变中看到了类似的情况，这甚至消除了S3依赖。趋势是明确的：基础设施工具的基础设施开销更少。

对于我们这些大规模管理Terraform的人来说，这些变化是受欢迎的。每个简化意味着更少的认知负荷，更少的潜在故障点，以及为新的团队成员更容易的入职。

你团队的行动项

如果你当前正在使用基于DynamoDB的状态锁定，以下是我推荐的：

审计你的Terraform仓库，以识别所有使用DynamoDB表的后端配置。
更新你的文档以反映使用原生S3锁定的新推荐方法。
如果尚未启用，在所有状态桶上启用S3桶版本控制。
创建一个迁移计划，优先考虑非生产环境。
更新你的CI/CD流水线以使用新的后端配置。
在迁移完成后安排DynamoDB表的清理。

迁移本身是直接的，但跨团队的规划和协调需要时间。尽早开始，清晰沟通，并在较低环境中彻底测试。

Terraform状态管理的未来更简单，这正是我们需要的，因为基础设施复杂性在其他地方继续增长。