Migration Guide

Migrate your Terraform backends from other providers to FreeState with zero downtime. This guide covers migrations from Terraform Cloud, AWS S3, Azure Storage, and local backends.

Before You Start

Before migrating, ensure you have:

A FreeState account and API key
Access to your current backend
A backup of your current state file
Local copy of your Terraform configurations

💡 Migration Tip

Always create a backup of your state file before starting any migration process. This ensures you can restore if anything goes wrong.

Migration from Terraform Cloud

Step 1: Backup Current State

terraform state pull > terraform-cloud-backup.tfstate

Step 2: Update Backend Configuration

Replace your Terraform Cloud backend configuration:

# Before (Terraform Cloud)
terraform {
  cloud {
    organization = "my-org"
    workspaces {
      name = "my-workspace"
    }
  }
}

# After (FreeState)
terraform {
  backend "http" {
    address        = "https://api.freestate.cloud/terraform/state"
    username       = "your-workspace-id"
    password       = "your-api-key"
    lock_address   = "https://api.freestate.cloud/terraform/state/lock"
    lock_method    = "POST"
    unlock_address = "https://api.freestate.cloud/terraform/state/lock"
    unlock_method  = "DELETE"
  }
}

Step 3: Initialize Migration

terraform init -migrate-state

Migration from AWS S3

Step 1: Backup from S3

# Download current state
aws s3 cp s3://my-bucket/terraform.tfstate terraform-s3-backup.tfstate

Step 2: Update Configuration

# Before (S3)
terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "terraform.tfstate"
    region = "us-west-2"
  }
}

# After (FreeState)
terraform {
  backend "http" {
    address        = "https://api.freestate.cloud/terraform/state"
    username       = "your-workspace-id"
    password       = "your-api-key"
    lock_address   = "https://api.freestate.cloud/terraform/state/lock"
    lock_method    = "POST"
    unlock_address = "https://api.freestate.cloud/terraform/state/lock"
    unlock_method  = "DELETE"
  }
}

Migration from Local Backend

Step 1: Backup Local State

cp terraform.tfstate terraform-local-backup.tfstate

Step 2: Add Backend Configuration

# Add to your main.tf
terraform {
  backend "http" {
    address        = "https://api.freestate.cloud/terraform/state"
    username       = "your-workspace-id"
    password       = "your-api-key"
    lock_address   = "https://api.freestate.cloud/terraform/state/lock"
    lock_method    = "POST"
    unlock_address = "https://api.freestate.cloud/terraform/state/lock"
    unlock_method  = "DELETE"
  }
}

Post-Migration Verification

1. Verify State Integrity

# Check state is accessible
terraform state list

# Verify plan shows no changes
terraform plan

2. Test Operations

# Test refresh
terraform refresh

# Test a small change
terraform apply

3. Update CI/CD Pipelines

Update your automation to use the new FreeState backend configuration and credentials.

Common Migration Issues

State Lock Conflicts

If you encounter state lock issues during migration:

# Check lock status
terraform force-unlock LOCK_ID

Provider Version Mismatches

Ensure provider versions match between old and new backends:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~&gt; 5.0"
    }
  }
}

Network Connectivity

Ensure your network can reach FreeState endpoints:

# Test connectivity
curl -I https://api.freestate.cloud/health

Migration Checklist

Pre-Migration

□ Create state backup
□ Document current configuration
□ Set up FreeState workspace
□ Generate API keys

During Migration

□ Update backend configuration
□ Run terraform init -migrate-state
□ Verify successful migration
□ Test basic operations

Post-Migration

□ Update CI/CD pipelines
□ Update team documentation
□ Clean up old backend resources
□ Monitor for issues

Need Help?

If you encounter issues during migration:

Check our troubleshooting guide
Contact our support team
Join our community Discord

✅ Migration Complete!

Congratulations! Your Terraform state is now securely managed by FreeState. Explore our other documentation to learn about advanced features.