如何在Terraform中实现迁移到支持原生状态锁定的S3存储方案

预期的输出结果如下：

正在初始化后端配置…
后端“s3”已成功配置！除非后端配置再次发生变化，否则Terraform会自动使用这个后端。
 
正在初始化插件…
- 从依赖关系锁文件中重新使用先前版本的hashicorp/aws插件
 
Terraform已成功初始化！

如果在这里看到错误：最常见的原因是S3桶上的对象锁定功能没有成功启用。请先重新执行步骤2中的验证操作，然后再继续下一步。

步骤5：验证迁移结果

运行terraform plan命令，以确认Terraform是否能够正确地使用新的后端配置：

terraform plan

规划结果应该满足以下条件：

• 操作成功完成

• 显示的结果与步骤1中运行的规划结果相同（没有变化，或者变化内容与之前一致）

• 输出结果中绝对不能出现与DynamoDB相关的任何信息

为了确认锁定机制确实是在使用S3而不是DynamoDB，可以打开第二个终端，在第一个终端运行terraform plan命令的同时，在第二个终端中也运行这个命令。你会看到第二个终端的输出中会出现与S3锁定相关的语句，而不会提到DynamoDB：

╷
│ 错误：获取状态锁时出现错误
│
│ 错误信息：操作失败，原因是在执行S3的PutObject请求时出现了错误，响应码为409，
│ 请求ID：……，错误原因是该键已经被其他进程锁定。
│
│ 锁定信息：
│   ID：        a1b2c3d4-e5f6-7890-abcd-ef1234567890
│   路径：      your-existing-bucket/path/to/terraform.tfstate.tflock
│   操作类型：OperationTypePlan
│   执行者：    user@hostname
│   版本：     1.10.0
│   创建时间： 2026-05-06 14:22:01 UTC
│   其他信息：
╵

Path字段显示的文件名为.tfstate.tflock，这个文件保存在你的S3桶中，而不是DynamoDB数据库中。这一结果证明了锁定机制现在完全由S3来处理。

步骤6：清理DynamoDB表

在确认迁移过程正常进行，并且您的团队已经使用新的后端至少完成了一次成功的计划制定和应用操作之后，就可以删除DynamoDB表了。

如果你们使用了CI/CD流程，或者有多名团队成员参与这项工作，请至少等待24到48小时再删除DynamoDB表。这样就能有足够的时间确保所有相关流程都已经更新为使用新的后端配置。

准备就绪后，可以执行以下命令来删除DynamoDB表：

aws dynamodb delete-table \
  --table-name your-dynamodb-lock-table

确认表已被成功删除后，可以再次执行以下命令：

aws dynamodb describe-table \
  --table-name your-dynamodb-lock-table

预期的输出结果应该是：

调用DescribeTable操作时出现了错误（ResourceNotFoundException）：
请求的资源未找到

如果出现这种错误，说明表确实已经被删除了，迁移工作已经完成。

如果您是通过Terraform来配置DynamoDB表的（这是推荐的做法），请先从Terraform配置中移除该资源，然后运行terraform apply命令，通过Terraform而非CLI直接删除该资源。这样就能保持配置的整洁性：

# 从您的Terraform配置中删除以下代码块：
resource "aws_dynamodb_table" "terraform_state_lock" {
  name         = "terraform-state-lock"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"
 
  attribute {
    name = "LockID"
    type = "S"
  }
}

删除完该代码块后，运行以下命令：

terraform apply

Terraform会检测到DynamoDB表资源已被从配置中移除，然后自动删除该表。

如何验证锁定机制是否正常工作

无论您是完成了新的配置设置，还是完成了迁移工作，都可以使用以下方法来独立验证锁定机制是否正常运作。

方法1：在操作过程中观察锁定文件

在一个终端中，针对包含大量资源的配置文件执行长时间运行的计划制定操作：

terraform plan

在计划执行期间，在另一个终端中检查S3存储桶中是否出现了锁定文件：

aws s3 ls s3://your-bucket/path/to/ | grep tflock

你应该会看到类似这样的文件：

2026-05-06 14:22:01        512 terraform.tfstate.tflock

当计划制定操作完成后，再次运行上述命令，此时.tflock文件应该已经消失了。

方法2：读取锁定文件的内容

当某个计划正在运行时，可以下载并查看该锁文件的内容：

aws s3 cp \
  s3://your-bucket/path/to/terraform.tfstate.tflock \
  /tmp/current.lock && cat /tmp/current.lock

预期的输出结果（为便于阅读而进行了格式化）如下：

{
  "ID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "Operation": "OperationTypePlan",
  "Info": "",
  "Who": "tolani@dev-machine",
  "Version": "1.10.0",
  "Created": "2026-05-06T14:22:01.123456789Z",
  "Path": "your-bucket/path/to/terraform.tfstate"
}

这就是Terraform在检测到锁被占用时所显示的相同信息。现在，这些锁信息是以JSON文件的形式存储在S3中，而不是保存在DynamoDB中。

如何处理无法解除的锁

在使用DynamoDB作为后端时，解决锁冲突意味着需要从DynamoDB表中删除相应的记录；而使用S3的原生锁定机制时，则只需删除S3中的.tflock文件即可。

以下是一些可能导致锁无法解除的情况：

• 当terraform apply或plan进程在执行过程中被中断时

• 当CI/CD流水线中的某个步骤在Terraform操作进行期间发生故障时

• 网络故障导致锁的释放操作无法完成时

以下是检查是否存在无法解除的锁的方法：

aws s3 ls s3://your-bucket/path/to/ | grep tflock

如果存在.tflock文件，且当前没有正在运行的Terraform操作，那么就说明存在无法解除的锁。

你还可以查看该锁文件的内容，从而了解是谁持有这个锁：

aws s3 cp \
  s3://your-bucket/path/to/terraform.tfstate.tflock \
  /tmp/stuck.lock && cat /tmp/stuck.lock

通过这些信息，你可以知道是哪个用户或进程持有这个锁，具体执行了什么操作，以及该锁是在什么时候被获取的。

如果你想强制解除这个锁，可以使用以下命令：

terraform force-unlock LOCK-ID

请将LOCK-ID替换为锁文件中显示的ID值。例如：

terraform force-unlock a1b2c3d4-e5f6-7890-abcd-ef1234567890

Terraform会提示你确认是否真的要强制解除锁：

您确定要强制解除锁吗？
Terraform将会删除远程状态上的锁。
这样，本地的Terraform命令就可以修改这个状态了，即使该状态可能仍在被其他进程使用中。
只有输入“yes”才能确认操作。
输入“yes”后，Terraform会成功解除锁。
另一种方法是通过CLI直接删除.tflock文件。如果terraform force-unlock命令无法使用（例如，因为在没有安装Terraform的CI环境中运行），可以直接删除该文件：
aws s3 rm s3://your-bucket/path/to/terraform.tfstate.tflock

只有当你确定当前没有任何Terraform操作正在运行时，才应该删除锁定文件。如果删除了某个仍被正在运行的操作所持有的锁定文件，那么就会允许另一个并发操作开始执行，而这正是锁定机制旨在防止的情况。
回滚计划：如果出现问题
如果在迁移后遇到了问题，你可以按照以下步骤将系统恢复到S3 + DynamoDB的配置状态。
步骤1：停止你团队以及CI/CD管道中所有的Terraform操作。

步骤2：如果你已经删除了DynamoDB表，请重新创建它：
aws dynamodb create-table \
  --table-name terraform-state-lock \
  --attribute-definitions AttributeName=LockID,AttributeType=S \
  --key-schema AttributeName=LockID,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

步骤3：将`backend.tf`文件恢复到之前的配置状态。
terraform {
  backend "s3" {
    bucket         = "your-existing-bucket"
    key            = "path/to/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-state-lock"   # 已恢复到之前的配置
    # 可以删除这一行：use_lockfile = true
  }
}

步骤4：重新初始化Terraform环境：
terraform init -reconfigure

步骤5：验证配置是否正确：
terraform plan

在回滚过程中，状态文件本身并不会被修改，因此数据也不会丢失。唯一会发生变化的，就是Terraform会使用哪种锁定机制来保护这些文件。
注意：即使在S3桶上启用了对象锁功能，也不会影响系统的回滚操作。对象锁与DynamoDB的锁定机制可以同时存在；在后端配置中指定`dynamodb_table`，就能确保无论桶是否启用了对象锁，Terraform都会使用DynamoDB来进行锁定。
状态桶的安全最佳实践
将系统迁移至支持原生锁定的S3存储服务时，正是检查状态桶整体安全配置的好时机。以下是所有生产环境中的Terraform状态桶都应该遵循的安全最佳实践：
必须启用版本控制功能
为了确保S3的原生锁定机制能够安全地发挥作用，版本控制功能是必不可少的。它能够保证在状态文件被意外覆盖或损坏的情况下，你可以恢复到之前的版本。
aws s3api put-bucket-versioning \
  --bucket your-state-bucket \
  --versioning-configuration Status=Enabled

必须禁止所有公共访问
你的状态文件中包含了资源ARN、IP地址，以及可能通过Terraform变量传递的敏感信息。因此，这些文件绝对不能被公开访问。
aws s3api put-public-access-block \
  --bucket your-state-bucket \
  --public-access-block-configuration \
    "BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true"

启用服务器端加密
务必对静态状态文件进行加密。最低要求是使用AES256算法；如果您的组织需要使用KMS进行密钥管理，可以执行以下操作：
aws s3api put-bucket-encryption \

  --bucket your-state-bucket \

  --server-side-encryption-configuration '{

    "Rules": [

      {

        "ApplyServerSideEncryptionByDefault": {

          "SSEAlgorithm": "aws:kms",

          "KMSMasterKeyID": "arn:aws:kms:us-east-1:123456789012:key/your-kms-key-id"

        },

        "BucketKeyEnabled": true

      }

    ]

  }'


应用最小权限IAM策略
Terraform用于访问状态存储桶的角色或用户应仅拥有其所需的权限。以下是针对S3原生加密功能的最小权限配置示例：
{

  "Version": "2012-10-17",

  "Statement": [

    {

      "Sid": "TerraformStateAccess",

      "Effect": "Allow",

      "Action": [

        "s3:ListBucket",

        "s3:GetObject",

        "s3:PutObject",

        "s3:DeleteObject"

      ],

      "Resource": [

        "arn:aws:s3:::your-state-bucket",

        "arn:aws:s3:::your-state-bucket/*"

      ]

    },

    {

      "Sid": "TerraformStateLocking",

      "Effect": "Allow",

      "Action": [

        "s3:GetObjectLegalHold",

        "s3:PutObjectLegalHold",

        "s3:GetObjectRetention",

        "s3:PutObjectRetention"

      ],

      "Resource": "arn:aws:s3:::your-state-bucket/*.tflock"

    }

  ]

}


请注意：此配置中并未包含访问DynamoDB的权限。这样的权限设置比旧方法更为简洁、所需权限也更少。
启用访问日志记录功能
在CloudTrail或S3服务器访问日志中记录对状态存储桶的所有访问操作。这样就可以追踪每次状态数据被读取、写入或被锁定时的详细情况：
aws s3api put-bucket-logging \

  --bucket your-state-bucket \

  --bucket-logging-status '{

    "LoggingEnabled": {

      "TargetBucket": "your-logging-bucket",

      "TargetPrefix": "terraform-state-access/"

    }

  }'


总结
使用AWS S3的原生状态锁定功能，无需在Terraform后端环境中配置DynamoDB表。这样一来，基础设施结构会更加简洁，所需的IAM权限也会减少，在团队管理的所有环境中，都需要配置、监控和付费的服务数量也会相应减少。
以下是您所完成的工作的总结：


了解了什么是状态锁定机制，以及为什么它对于确保Terraform操作的安全性至关重要


比较了S3原生锁定功能与原有的S3 + DynamoDB组合方案


使用S3原生锁定功能配置了新的Terraform后端环境，并设置了正确的存储桶参数


成功地将现有的基于S3 + DynamoDB的后端环境迁移到了新方案中


学会了如何验证锁定状态、处理锁住的情况，以及在必要时进行回滚操作


为状态存储桶应用了安全最佳实践


这种利用S3原生锁定机制的方法，是今后在AWS上创建所有新的Terraform项目时所推荐的方案。如果你负责管理包含多个Terraform后端的庞大基础设施系统，可以考虑通过编写脚本或使用Terraform模块来自动化这一迁移过程，从而确保这一机制能够应用于你所有的状态存储桶中。
如果你正在为一家初创企业构建或优化云基础设施，并且需要一份关于可供生产环境使用的Terraform模块、CI/CD流水线配置方案以及基础设施运维指南的完整参考资料，请查看 《初创企业DevOps实战指南》。该指南涵盖了从初始设置到确保系统具备生产环境可靠性的整个AWS基础设施生命周期管理流程。
参考资料


HashiCorp：S3后端配置中的lockfile使用方法


HashiCorp：Terraform 1.10版本发布说明


AWS文档：S3对象锁定功能概述


AWS文档：PutObjectLockConfiguration API接口说明


AWS文档：S3条件写入功能介绍


HashiCorp：后端状态锁定机制


HashiCorp：terraform force-unlock命令使用说明


AWS文档：如何启用S3版本控制功能


AWS文档：S3服务器端加密功能介绍