名称: terraform-state-manager 描述: 管理 Terraform 状态操作，包括导入现有资源、在状态之间移动资源、从状态中移除资源以及迁移状态后端。当用户需要将基础设施导入 Terraform、重构资源地址、修复状态问题或迁移状态存储位置时，应使用此技能。

Terraform 状态管理器

此技能提供安全的 Terraform 状态操作和故障排除工作流程。

使用时机

在以下情况下使用此技能：

将现有基础设施导入 Terraform
将资源移动到不同地址（重命名）
从状态中移除资源而不销毁它们
在不同后端之间迁移状态（本地到 S3 等）
从状态损坏或冲突中恢复
拆分或合并状态文件

关键安全规则

在处理状态时，务必遵循这些规则：

先备份：在任何操作前创建状态备份
后计划：状态更改后运行 terraform plan 进行验证
一次一个：进行增量更改，而不是批量操作
在非生产环境测试：先在开发/测试环境中练习状态操作
版本控制：将代码更改与状态操作一起提交

常见操作

1. 导入现有资源

工作流程：

# 步骤 1：在 .tf 文件中编写资源配置
# 步骤 2：导入资源
terraform import <resource_address> <resource_id>

# 步骤 3：通过计划验证（应显示无更改）
terraform plan

示例 - 导入 AWS S3 桶：

# 1. 添加到 main.tf
resource "aws_s3_bucket" "existing" {
  bucket = "my-existing-bucket"
}

# 2. 导入
terraform import aws_s3_bucket.existing my-existing-bucket

# 3. 验证
terraform plan  # 应显示：无更改

提示：

在提供商文档中查找资源 ID 格式
一次导入一个资源
某些资源需要多次导入（桶 + 版本控制 + 加密）
使用 terraform show 查看导入的属性

2. 移动资源（重命名/重构）

工作流程：

# 将资源移动到新地址
terraform state mv <source> <destination>

# 验证
terraform plan  # 应显示：无更改

示例 - 重命名资源：

# 之前：aws_s3_bucket.bucket
# 之后：aws_s3_bucket.main

terraform state mv aws_s3_bucket.bucket aws_s3_bucket.main

示例 - 移动到模块：

# 将资源移动到模块中
terraform state mv aws_instance.web module.web_server.aws_instance.main

示例 - 在模块之间移动：

terraform state mv module.old.aws_db_instance.main module.new.aws_db_instance.main

提示：

在运行计划前更新 .tf 文件以匹配新地址
对于包含特殊字符的地址使用引号
一起移动相关资源（例如，桶 + 桶策略）

3. 从状态中移除

工作流程：

# 从状态中移除资源（保留实际资源）
terraform state rm <resource_address>

# 验证资源是否仍在云中存在
# 更新 .tf 文件以移除资源定义

示例 - 移除资源：

# 从 Terraform 管理中移除
terraform state rm aws_s3_bucket.temp

# 资源仍存在于 AWS 中，只是不由 Terraform 管理

使用场景：

将资源移交给另一个 Terraform 工作区
移除意外导入的资源
停止对遗留资源的 Terraform 管理

4. 迁移状态后端

本地 → S3 的工作流程：

# 步骤 1：创建 S3 桶和 DynamoDB 表用于锁定

# 步骤 2：添加后端配置
terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "project/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

# 步骤 3：初始化并迁移状态
terraform init -migrate-state

# 步骤 4：验证
terraform plan

后端迁移检查清单：

[ ] 备份当前状态文件
[ ] 创建新的后端资源（S3 桶等）
[ ] 更新代码中的后端配置
[ ] 运行 terraform init -migrate-state
[ ] 通过 terraform plan 验证
[ ] 测试状态锁定是否正常工作
[ ] 更新团队文档

5. 列出状态资源

查看状态中的所有资源：

# 列出所有资源
terraform state list

# 显示特定资源详情
terraform state show aws_s3_bucket.main

# 以 JSON 格式输出状态
terraform show -json

故障排除

状态锁定问题

# 如果状态被锁定且不应如此
terraform force-unlock <lock-id>

# 仅在确定没有其他操作运行时使用

状态漂移检测

# 检查状态与实际基础设施之间的漂移
terraform plan -refresh-only

# 更新状态以匹配实际情况（不更改基础设施）
terraform apply -refresh-only

损坏状态恢复

# Terraform 自动保持备份
ls terraform.tfstate.backup

# 从备份恢复
cp terraform.tfstate.backup terraform.tfstate

# 或从远程后端版本历史恢复（S3 版本控制）

操作前检查清单

在任何状态操作前：

[ ] 备份状态文件（cp terraform.tfstate terraform.tfstate.backup）
[ ] 确保没有其他操作正在运行
[ ] 了解确切的命令及其影响
[ ] 准备回滚计划
[ ] 先在非生产环境测试

操作后验证

在任何状态操作后：

[ ] 运行 terraform plan（应显示预期更改或无更改）
[ ] 验证资源是否仍在云控制台存在
[ ] 检查状态文件大小是否合理
[ ] 将更改提交到版本控制
[ ] 记录所做操作及原因