ContextQMD
Back to Opentofu

Migration Guide

website/docs/intro/migration/migration-guide.mdx

1.12.03.1 KB
Original Source

Migration Guide

This guide walks you through migrating from Terraform to OpenTofu. It is designed to be safe and reversible, allowing you to test OpenTofu without disrupting your existing infrastructure.

:::note Do you have multiple Terraform configurations to migrate?

Some systems are built from multiple Terraform configurations that propagate data using the terraform_remote_state data source, which typically requires some additional care during migration.

For more information, refer to Migrating interdependent configurations. :::

Prerequisites

  • An existing Terraform configuration
  • Access to your Terraform state files
  • Ability to run both terraform and tofu commands during the migration

Step 1: Back up your infrastructure

Before starting the migration, create backups of:

  1. Your Terraform state files

    • For local state: Copy your terraform.tfstate and terraform.tfstate_backup files
    • For remote state: Follow your backend's backup procedures (e.g., S3 versioning, snapshot your state bucket)

  2. Your Terraform configuration files

    • Commit all changes to version control
    • Consider creating a migration branch

Step 2: Install OpenTofu

Follow the installation guide to install OpenTofu on your system. Verify the installation:

bash
tofu --version

Step 3: Initialize OpenTofu

In your Terraform project directory, initialize OpenTofu:

bash
tofu init

This command will:

  • Download required providers from the OpenTofu registry
  • Initialize your backend configuration
  • Prepare your working directory

Step 4: Verify your configuration

Run a plan to ensure OpenTofu can read your state and configuration:

bash
tofu plan

Expected result: You should see "No changes" or the same plan output you would see with Terraform.

If you see unexpected changes:

  1. Do not apply the changes
  2. Investigate the differences
  3. Consider rolling back (see below)

Step 5: Apply with OpenTofu

Once you've verified the plan shows no unexpected changes, run:

bash
tofu apply

Even if there are no infrastructure changes, this ensures OpenTofu updates the state file format if needed.

Step 6: Test with a small change

Make a small, non-critical change to your configuration (e.g., add a tag to a resource) and run:

bash
tofu plan
tofu apply

This verifies that OpenTofu can successfully manage your infrastructure going forward.

Rolling back to Terraform

If you encounter issues during migration, you can safely roll back:

  1. Stop using OpenTofu immediately
  2. Restore from your backups (if any state changes were made)
  3. Run Terraform commands:
    bash
    terraform init
terraform plan
  4. Verify no unexpected changes appear in the plan
  5. Continue using Terraform as before

Getting help

If you encounter issues during migration: