name: terraform-upgrade-assistant description: 指导Terraform版本升级，包括识别弃用语法、更新提供者版本和迁移重大更改。此技能应在用户需要升级Terraform或提供者版本、修复弃用警告或将配置迁移到新语法时使用。

Terraform 升级助手

此技能帮助安全升级Terraform和提供者版本。

何时使用

在以下情况使用此技能：

升级Terraform CLI版本
更新提供者版本
修复弃用语法警告
迁移到新提供者功能
准备主要版本升级

升级过程

1. 检查当前版本

# 检查Terraform版本
terraform version

# 检查使用的提供者版本
terraform providers

# 检查可用更新
terraform init -upgrade

2. 审查升级指南

升级前，审查：

Terraform 升级指南
提供者更新日志（例如，AWS提供者发布）
重大更改文档

3. 升级策略

增量方法（推荐）：

一次升级一个次要版本
在升级之间彻底测试
主要升级前修复弃用警告

示例路径： 1.0 → 1.1 → 1.2 → 1.3 → 1.4 → 1.5

4. 更新版本约束

# 之前
terraform {
  required_version = ">= 1.0"
  
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

# 之后
terraform {
  required_version = ">= 1.5"
  
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

处理弃用警告

识别警告

# 运行计划以查看警告
terraform plan

# 示例输出：
# 警告：参数已弃用
#   请使用 aws_s3_bucket_acl 资源替代

升级清单

升级前

[ ] 备份状态文件
[ ] 审查目标版本的升级指南
[ ] 检查提供者更新日志
[ ] 首先在非生产环境中测试
[ ] 确保团队知晓升级

升级期间

[ ] 更新代码中的版本约束
[ ] 运行 terraform init -upgrade
[ ] 运行 terraform plan 并审查更改
[ ] 修复任何弃用警告
[ ] 使用新版本更新CI/CD管道

升级后

[ ] 运行 terraform plan（应无更改显示）
[ ] 在开发环境中测试应用
[ ] 更新文档
[ ] 提交版本约束更改
[ ] 监控问题

故障排除

状态文件兼容性

# 如果状态文件与提供者源不兼容
terraform state replace-provider \
  registry.terraform.io/-/aws \
  registry.terraform.io/hashicorp/aws

提供者插件问题

# 清除提供者缓存并重新初始化
rm -rf .terraform/
rm .terraform.lock.hcl
terraform init -upgrade

版本约束最佳实践

# 良好 - 允许补丁更新，防止重大更改
terraform {
  required_version = "~> 1.5.0"  # 仅 1.5.x
  
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # 仅 5.x
    }
  }
}

# 过于限制
required_version = "= 1.5.0"  # 仅精确版本

# 过于宽松
required_version = ">= 1.0"  # 可能在主要更新时中断