Terraform State Migration Guide

This guide provides a detailed, step-by-step process for migrating the Terraform state into Bluebricks. By following these instructions, you'll ensure a seamless and hassle-free migration of the old infrastructure state into Bluebricks managed state.

Best Practices Before You Begin

• Always create a backup of your existing tfstate file before migration

• Use terraform plan to validate each step and identify potential discrepancies

Migration Steps

It’s highly recommended to review the Quick Start tutorial before starting a migration. ✅

Before beginning the migration, confirm the following:

• Terraform/OpenTofu is installed on your system

• The Terraform code that is about to migrate is functional, and there are no drifts with the state

• You have a backup of your existing state file

Migration Workflow

Prepare the Current Terraform Environment

1. Open the terminal and navigate to the folder that contains the code to be migrated.

cd ~/path/to/terraform

1. Initialize the Terraform Directory

terraform init

1. Validate Current State

terraform plan

Ensures no pending changes exist in the current configuration. An exit code of 0 indicates no modifications are required.

1. Removes the .terraform directory to facilitate a fresh initialization

rm -rf .terraform

Prepare State File for Migration

1. Exports the entire Terraform state file to a local JSON file for reference

terraform state pull > terraform.json

1. Create a new terraform.tfstate file and copy the resources that match the module to be migrated from terraform.json.

Migrating multiple resources of the same type/package is not supported.

1. Validate the created terraform.tfstate file by running the following command:

terraform plan

Confirm the output shows no planned changes.

1. Validate the syntax of the state

terraform show -json terraform.tfstate

1. After copying and validation are complete, remove the terraform.json file

rm terraform.json

Convert Module to an Artifact

1. Navigate to the parent folder

cd ..

1. Create an Artifact by running the following command:

bricks bp prepare --source=./terraform --output=./artifact --bricks-only

1. Change directory to artifact and publish the created Artifact

bricks bp publish --state

If you're adding a state to an existing Artifact, bump the version before publishing by running bricks bp bump

Validate Artifact

1. Test Artifact by initiate a plan-only installation

bricks install <package_name> --plan-only

Verify no unexpected changes occur during deployment.

Cleanup Artifact

1. Remove temporary files

• Delete the migrated terraform.tfstate file

• Remove state_path entry from bricks.json

Finalize Deployment

1. Increment Artifact version

bricks bp bump

1. Publish final changes

bricks bp publish