Migrate Terraform state to Bluebricks

Migrate an existing Terraform deployment into Bluebricks without recreating infrastructure

Overview

This guide explains how to migrate an existing Terraform deployment into Bluebricks without recreating infrastructure. You will publish your Terraform package, create a Blueprint, upload your existing state file, and verify that Bluebricks detects no drift. This workflow lets you transition safely to Bluebricks-managed plans and applies while preserving existing resources.

Prerequisites

Before starting, ensure the following:

• Your Terraform configuration is working and applied

• You can run tofu state pull successfully (See: OpenTofu docs)

• The bricks command line is installed and authenticated

• You have an organization API token

Migration guide

1

Publish the package

1. Navigate to your Terraform codebase directory

2. Run:

bricks bp publish

This creates a versioned package in Bluebricks.

Why this matters

State uploads are version-scoped. The uploaded state must reference a specific package version. If you skip this step, state upload will fail.

2

Create a blueprint

1. In the Bluebricks app, create a new blueprint:

   • Go to Packages

   • Click Create blueprint

2. The blueprint should reference your newly published package

The blueprint defines how the package will be instantiated into a deployment.

Need help creating a blueprint? Check out creating blueprints.

3

Pull existing Terraform state

From your existing environment:

terraform state pull > terraform.tfstate

This exports the current remote state to a local file.

Uploading mismatched state can cause drift or destructive changes.

4

Upload the state to Bluebricks

Upload the state via the Bluebricks API:

curl -X POST "https://api.bluebricks.co/api/v1/envs/<ENVIRONMENT_SLUG>/states" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -F "packageVersion=<PACKAGE_VERSION>" \
  -F 'states=[{"package_id": "<PACKAGE_ID>", "state_file": "terraform.tfstate"}]' \
  -F "terraform.tfstate=@./terraform.tfstate;type=application/json"

Replace:

<ENVIRONMENT_SLUG>	Add your environment slug
<YOUR_TOKEN>	Add your token
<PACKAGE_VERSION>	The packageVersion must match the version you published in step 1
<PACKAGE_ID>	The package_id must match the package used in the blueprint

Important

• The state file must be valid JSON

If these values are inconsistent, future plans may show full recreation.

5

Install the blueprint

Install the blueprint into a deployment:

bricks install <blueprint>@<version> \
  --collection devops-pocs \
  --slug <deployment_slug>

This associates the blueprint with a deployment in Bluebricks.

6

Run a plan and verify zero drift

Run a plan in Bluebricks.

You should see no resource changes.

If the plan shows creates or destroys:

• The uploaded state does not match the configuration

• The package version differs from the original Terraform code

• Variables or provider configuration changed

Do not apply until drift is resolved.

Troubleshooting

Plan shows full recreate

Check:

• Package version matches the original Terraform code

• Variables are identical

• Provider configuration did not change

• The correct state file was uploaded

API upload fails

Verify:

• Token is valid

• packageVersion exists

• package_id is correct

• State file is valid JSON

Environment slug not found

Confirm:

• Blueprint was installed successfully

• Environment slug matches the one used during install