opentofu-migration

用途

OpenTofu Migration 用于将基础设施即代码（IaC）从 HashiCorp Terraform 迁移到开源分支 OpenTofu。

适用场景（资料中列出的 When to Use This Skill）：

出于许可证（licensing）原因，从 Terraform 迁移到 OpenTofu
新建 IaC 项目并评估 OpenTofu 与 Terraform 的取舍
更新 CI/CD 流水线以使用 OpenTofu
配置 OpenTofu 的 Provider 注册表

前置条件（Prerequisites）：

已有 Terraform 代码库（0.13+）
已安装 OpenTofu CLI
具备状态后端访问权限（S3、GCS、Azure Blob 等）

主要能力

1. 安装 OpenTofu

资料给出了 macOS、Linux（Debian/Ubuntu、RPM）、Docker 的安装方式，并以 tofu --version 验证安装：

# macOS
brew install opentofu

# Linux (Debian/Ubuntu)
curl --proto '=https' --tlsv1.2 -fsSL https://get.opentofu.org/install-opentofu.sh \
  -o install-opentofu.sh
chmod +x install-opentofu.sh
./install-opentofu.sh --install-method deb
rm install-opentofu.sh

# Linux (RPM)
./install-opentofu.sh --install-method rpm

# Docker
docker run --rm -v $(pwd):/workspace -w /workspace \
  ghcr.io/opentofu/opentofu:latest init

# Verify installation
tofu --version

2. 迁移检查清单（Migration Checklist）

验证兼容性：OpenTofu 可直接读取 Terraform 状态文件，无需迁移；Terraform 版本需 ≤ 1.6.x 以获得完整兼容。先在现有状态上执行 tofu init 与 tofu plan。

替换 CLI 命令：资料给出命令对照表——terraform init/plan/apply/destroy/fmt/validate/state/import 分别对应 tofu init/plan/apply/destroy/fmt/validate/state/import。

更新 Provider 锁文件：删除 Terraform 锁文件并用 OpenTofu 重新生成，再校验 Provider 解析结果：

rm .terraform.lock.hcl
tofu init -upgrade
tofu providers

更新状态后端：状态文件兼容，无需迁移，仅需验证。资料给出的 backend.tf 示例（S3 后端，含 bucket、key、region、dynamodb_table、encrypt）在 OpenTofu 下工作方式一致，并用 tofu init、tofu state list 验证状态访问。

Provider 注册表：OpenTofu 使用自己的注册表，但镜像了大多数 Terraform Provider。资料给出 versions.tf 中 required_providers 的写法（aws、kubernetes、random，含 source 与 version）。

3. OpenTofu 特有功能

状态加密（Terraform 中不具备）：资料给出 terraform { encryption { ... } } 配置示例，使用 key_provider "pbkdf2" 与 method "aes_gcm"，可对 state 与 plan 强制加密。
早期变量/局部值求值：允许在 backend 配置与 module source 中使用变量，例如 bucket = var.state_bucket，资料注明这在 OpenTofu 中可用、在 Terraform 中不可用。

4. CI/CD 流水线更新

资料提供两套完整示例：

GitHub Actions（.github/workflows/tofu.yml）：使用 opentofu/setup-opentofu@v1，配合 AWS 凭证配置，执行 init/plan，并在 PR 中以 actions/github-script@v7 评论输出计划；apply 作业依赖 plan，仅在 main 分支、production 环境下运行。
GitLab CI（.gitlab-ci.yml）：分 validate/plan/apply 三阶段，使用 ghcr.io/opentofu/opentofu:${TOFU_VERSION} 镜像，plan 产出 tfplan 构件，apply 为手动触发且仅限 main 分支。

使用方式

安装 OpenTofu CLI 并验证版本。
在现有 Terraform 代码库上运行 tofu init 与 tofu plan 验证兼容性（Terraform 版本需 ≤ 1.6.x）。
按对照表将流水线或本地命令中的 terraform 替换为 tofu。
删除 .terraform.lock.hcl 并执行 tofu init -upgrade 重新生成锁文件。
确认状态后端配置有效（状态文件兼容），按需启用 OpenTofu 状态加密等特性。
更新 CI/CD 流水线配置。

双工具共存与排查

共存策略：可使用别名区分 terraform 与 tofu，或用 direnv 按项目设置 PATH，也可使用 wrapper 脚本依据 .use-opentofu 文件决定调用哪个工具。

资料给出的排查表包括：Provider 未找到（运行 tofu init -upgrade、检查 registry.opentofu.org）、状态锁冲突（与 Terraform 相同，检查 DynamoDB/blob lease）、版本约束错误（将 required_version 更新为 >= 1.6.0）、后端迁移（状态兼容，直接 tofu init）、缺少 Provider 凭证（相同的环境变量可用，如 AWS_、GOOGLE_、ARM_*）。

适用场景

需要从 Terraform 迁移到 OpenTofu、或在二者间做技术选型的 DevOps 团队；需要改造 IaC 相关 CI/CD 流水线的团队；需要配置 OpenTofu Provider 注册表或使用其状态加密能力的团队。

限制

资料未说明该技能的具体收费、许可条款、支持平台范围之外的信息、性能指标或实际迁移效果，以上内容暂未提供。资料中涉及的版本约束（如 Terraform ≤ 1.6.x、required_version >= 1.6.0、tofu_version 1.8.0）为示例性配置，实际取值请以官方文档为准。