Migrating from Terraform Cloud to FreeState

Moving your Terraform infrastructure from Terraform Cloud to FreeState is straightforward and can be done with zero downtime. This guide walks you through the entire process.

Prerequisites

Before starting the migration:

• Access to your current Terraform Cloud workspace
• FreeState account and API key
• Local copy of your Terraform configurations
• Backup of your current state file (recommended)

Step 1: Backup Your Current State

First, let's create a backup of your current state:

\\\`bash

Download current state from Terraform Cloud

terraform state pull > terraform-cloud-backup.tfstate

\\\`

Step 2: Prepare FreeState Backend Configuration

Create a new backend configuration for FreeState:

\\\`hcl

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 the New Backend

\\\`bash

Initialize with the new backend

terraform init -migrate-state

\\\`

Terraform will prompt you to confirm the migration. Type "yes" to proceed.

Step 4: Verify the Migration

After migration, verify everything is working correctly:

\\\`bash

Check that the state is accessible

terraform plan

Verify state integrity

terraform state list

\\\`

Step 5: Update Your CI/CD Pipelines

Update your automation to use the new FreeState backend:

GitHub Actions Example

\\\`yaml

• name: Setup Terraform

uses: hashicorp/setup-terraform@v2

with:

terraform_wrapper: false

• name: Terraform Init

env:

TF_HTTP_USERNAME: \$\{\{ secrets.FREESTATE_WORKSPACE_ID \}\}

TF_HTTP_PASSWORD: \$\{\{ secrets.FREESTATE_API_KEY \}\}

run: terraform init

\\\`

Common Migration Issues

State Lock Conflicts

If you encounter state lock issues:

\\\`bash

Force unlock if needed (use with caution)

terraform force-unlock LOCK_ID

\\\`

Provider Version Mismatches

Ensure your provider versions are compatible:

\\\`hcl

terraform {

required_providers {

aws = {

source = "hashicorp/aws"

version = "~> 5.0"

}

}

}

\\\`

Benefits After Migration

Once migrated to FreeState, you'll enjoy:

• Faster Operations: Optimized backend performance
• Better Security: Enhanced encryption and access controls
• Cost Savings: Competitive pricing compared to Terraform Cloud
• Simplified Management: Unified dashboard for all your workspaces

Need Help?

If you encounter any issues during migration:

• Check our troubleshooting guide
• Contact our support team
• Join our community Discord for peer assistance

Migration is typically completed in under 30 minutes with zero downtime to your infrastructure!