Terraform to OpenTofu Migration Analysis

Analyze Terraform configurations to determine if they can safely migrate to OpenTofu. Identifies incompatible features, recommends appropriate OpenTofu versions, and provides migration guidance.

Context: Terraform Cloud's legacy free tier reaches end-of-life on March 31, 2026, driving many organizations to consider OpenTofu migration.

Migration Analysis Workflow

Step 1: Understand the Scope

Ask the user about their deployment setup:

•How are deployments automated? (GitHub Actions, GitLab CI, TFC/TFE, other TACOS, manual)
•Single configuration or multiple interdependent configurations?
•Current Terraform version in use?

Understanding automation is critical - TACOS platforms provide the easiest migration path.

Step 2: Analyze Configuration Files

Read the Terraform configuration and identify key features:

Basic configuration:

•Provider configurations and versions
•Backend configuration (S3, Terraform Cloud, etc.)
•Use of terraform_remote_state data sources (signals multi-config)

Search for Terraform-exclusive advanced features:

bash

# Search for recent Terraform-exclusive features
grep -r "resource.*action\s*{" .  # Actions (Terraform 1.14+)
grep -r "query\s*{" .              # Declarative resource search (Terraform 1.14+)
grep -r "identity\s*=" .           # Import via identity attribute (Terraform 1.12+)
grep -r "write_only\s*=" .         # Write-only attributes (Terraform 1.11+)

Look in .tf files for:

•action blocks for day-two operations
•query blocks for declarative resource search
•Provider blocks with identity-based imports
•Variable/resource attributes marked write_only

Identify TACOS (Terraform Automation & Collaboration Software):

Check for TACOS usage - if present, migration should use the TACOS:

bash

# Check backend configuration
grep -r "backend\s*\"" . | grep -E "(cloud|remote)"
cat .terraform/terraform.tfstate | jq '.backend.type' 2>/dev/null

# Check for Spacelift provider (Infrastructure-as-Code managed stacks)
grep -r "provider \"spacelift\"" . --include="*.tf"
grep -r "spacelift_stack" . --include="*.tf"

TACOS platforms:

•
Spacelift (preferred - native OpenTofu support)
- •If using Spacelift provider: See references/spacelift-migration.md for detailed guide
- •Must update terraform_workflow_tool attribute to "OPEN_TOFU"
- •Consider stack dependency order for migration
•Terraform Cloud/Enterprise (TFC/TFE)
•env0
•Scalr
•Atlantis

Important: Most TACOS platforms do not support BUSL Terraform (v1.6+), only pre-BUSL versions (≤1.5.x).

If using a TACOS, note the platform - migration strategy will differ significantly.

Step 3: Cross-Reference with Compatibility Matrix

Always read references/compatibility-matrix.md and compare configuration features:

•✅ Parity/OpenTofu Exclusive - Safe to migrate
•⚠️ Version Check Needed - Ensure OpenTofu version includes feature
•❌ Terraform Exclusive - Blocks migration

Key compatibility facts:

•OpenTofu forked from Terraform v1.5.7
•Terraform ≤ v1.5.x: direct migration to OpenTofu v1.6+
•Terraform ≥ v1.6.x: assess features against matrix

CRITICAL: Provider Namespace Configuration

DO NOT change provider sources during migration:

•Keep using hashicorp/aws, hashicorp/azurerm, hashicorp/google, hashicorp/random, etc.
•DO NOT change to opentofu/* namespace
•HashiCorp providers remain MPL-2.0 licensed (not affected by Terraform's BUSL change)
•OpenTofu team maintains forks only for building; binaries are identical to HashiCorp's
•See references/migration-guide.md Step 3 for detailed explanation

Step 4: Determine Migration Feasibility

✅ Safe to Migrate: No Terraform-exclusive features, all features have parity or are in OpenTofu

⚠️ Version Consideration Needed: Uses features in later OpenTofu versions, recommend specific version

❌ Migration Blocked: Uses Terraform-exclusive features, list blocking features and alternatives

Step 5: Identify Migration Strategy

If using a TACOS (preferred migration path):

Migrate using the TACOS platform to minimize disruption:

•
Spacelift (recommended): Native OpenTofu support, switch runtime version in stack settings
- •UI-managed stacks: Change "Workflow Tool" to "OpenTofu" in stack settings
- •Provider-managed stacks: Update spacelift_stack resource terraform_workflow_tool to "OPEN_TOFU"
- •
  See references/spacelift-migration.md for complete guide including:
  - •Stack dependency ordering for migrations
  - •Bulk migration via Terraform provider (for_each pattern)
  - •Provider configuration examples
  - •Runtime configuration (.spacelift/config.yml)
- •Test with plan before applying
- •Minimal state migration needed - Spacelift handles compatibility
- •Note: Spacelift doesn't support BUSL Terraform (v1.6+), only pre-BUSL (≤1.5.x), making OpenTofu migration natural
•
Terraform Cloud/Enterprise (TFC/TFE): OpenTofu support uncertain
- •As of 2026, TFC/TFE OpenTofu support is unclear
- •Recommend migrating to alternative TACOS with confirmed OpenTofu support (Spacelift, env0, Scalr)
- •
  If staying with TFC/TFE, may need to:
  - •Export state from TFC/TFE workspaces
  - •Migrate to local/S3 backend temporarily
  - •Consider long-term TACOS alternative
•
env0: Native OpenTofu support
- •Switch runtime version in environment settings
- •Like Spacelift, doesn't support BUSL Terraform, making OpenTofu migration straightforward
•
Scalr: Native OpenTofu support
- •Update workspace configuration to use OpenTofu runtime
- •Test with plan before applying
•
Atlantis: Self-hosted, full control
- •Update atlantis.yaml to use tofu binary instead of terraform
- •If using Docker: Build custom image with OpenTofu (v1.10+ not directly runnable)
- •Install OpenTofu in Atlantis container via installation script or package manager

If using CI/CD (GitHub Actions, GitLab CI, etc.):

Update pipeline configuration to use OpenTofu:

•
GitHub Actions:
- •Update setup action: hashicorp/setup-terraform → opentofu/setup-opentofu
- •Replace terraform with tofu in run commands
•
Docker-based CI (GitLab CI, CircleCI, etc.):
- •Important: OpenTofu v1.10+ doesn't support direct Docker run
- •
  Options:
  1. •Build custom image from ghcr.io/opentofu/opentofu:1-minimal
  2. •Use installation script in container
  3. •Install via package manager (apt/yum) in CI
- •See https://opentofu.org/docs/intro/install/docker/ for Dockerfile examples
•
Replace all terraform commands with tofu in pipeline files
•
Test in non-production environment first
•
See references/migration-guide.md for detailed CI/CD update steps

If using manual deployments:

Single configuration:

•Follow references/migration-guide.md
•Standard workflow: Backup → Install → Initialize → Verify → Apply → Test

Multiple configurations with terraform_remote_state:

•Read references/multi-config-migration.md
•Recommend bottom-up migration (dependencies first)
•Create dependency graph

Step 6: Provide Migration Recommendation

Deliver clear recommendation with:

•Migration Feasibility: Safe / Conditional / Blocked
•Deployment Method: TACOS / CI/CD / Manual - critical for migration approach
•Recommended OpenTofu Version: Minimum version needed
•Identified Risks: Specific concerns or features to watch
•Migration Approach: TACOS-based / CI/CD update / Manual migration
•Next Steps: Specific to deployment method

Example output format:

code

# Migration Analysis: Safe

**Current:** Terraform v1.5.x, Spacelift TACOS, 15 stacks (5 with dependencies)
**Deployment:** Spacelift with spacelift_stack provider resources detected
**Features:** Standard configuration, S3 backend via Spacelift
**Provider Usage:** Using spacelift_stack resources to manage stacks as code
**Assessment:** All features compatible

**Recommendation:** OpenTofu v1.11 via Spacelift provider updates
**Strategy:** TACOS-based migration using Spacelift provider
**Guide:** See references/spacelift-migration.md for complete process

**Critical:** Update spacelift_stack resources:
- Set terraform_workflow_tool = "OPEN_TOFU"
- Update terraform_version = "1.11.0"
- Consider stack dependency order (migrate leaf stacks first)

**Benefits:** Review references/opentofu-features.md for new capabilities:
- State encryption for compliance
- Early variable evaluation for dynamic configs
- Provider for_each for multi-region deployments
- Ephemeral resources for secure credential handling

**Next:**
1. Read references/spacelift-migration.md
2. Update spacelift_stack resources in provider configuration
3. Apply provider changes (respecting dependency order)
4. Verify each stack runs with OpenTofu
5. Explore references/opentofu-features.md for post-migration enhancements

Resources

Compatibility Data

references/compatibility-matrix.md - Feature compatibility matrix

•Auto-generated from cani.tf
•Shows version availability for each feature
•Always read this file when performing analysis

scripts/fetch_latest_compatibility.sh - Update compatibility data

•Fetches latest data from cani.tf/tools.json
•Run before major migrations or when new versions release

references/opentofu-features.md - OpenTofu features showcase

•Comprehensive feature catalog with practical use cases
•Features organized by category (State, Configuration, Providers, Security, Distribution, Operations)
•Version timeline (1.7 through 1.11)
•Comparison with Terraform for each feature
•Configuration examples and best practices

Migration Guides

references/migration-guide.md - Single-configuration migration

•Step-by-step process with backup/rollback procedures
•Common issues and solutions
•Post-migration enhancements (state encryption, breaking Terraform)

references/multi-config-migration.md - Multi-configuration strategy

•Bottom-up dependency-aware approach
•Handles terraform_remote_state dependencies
•Team coordination strategies

references/spacelift-migration.md - Spacelift-specific migration

•UI-managed vs provider-managed stacks
•terraform_workflow_tool attribute updates
•Stack dependency ordering for bulk migrations
•Bulk management via Terraform provider (for_each pattern)
•Runtime configuration (.spacelift/config.yml) for repository-level settings

Analysis Tips

•
Check for TACOS first - If using Spacelift/env0/Scalr, migration is simpler via platform
- •Spacelift provider detection: Look for spacelift_stack resources → use spacelift-migration.md
•Start with Terraform version - Quickest compatibility indicator
•Scan for Terraform-exclusive features - Actions, query blocks, write_only attributes
•Look for terraform_remote_state - Signals multi-config scenario
•Check backend type - Most compatible, some have caveats

Quick Decision Guide

Terraform Version	Action
≤ 1.5.7	Direct migration to OpenTofu 1.6+
1.6.x - 1.9.x	Check matrix for feature compatibility
≥ 1.10.x	Assess carefully, may need latest OpenTofu

Updating Compatibility Data

Refresh the matrix periodically:

bash

cd /path/to/skill
./scripts/fetch_latest_compatibility.sh

Update before: Major migrations, new version releases, or monthly

Licenses and Attribution

Tools:

•OpenTofu: MPL-2.0 (open source)
•Terraform: BUSL-1.1 (source-available with restrictions)

Data Sources:

•cani.tf: CC0-1.0 (https://cani.tf)
•OpenTofu Documentation: CC BY 4.0 (https://opentofu.org/docs/)

Note: License difference (MPL-2.0 vs BUSL-1.1) is often a key migration motivation.