Migrate Terraform State to Bluebricks

How to migrate an existing Terraform deployment into Bluebricks when you want to adopt Bluebricks without recreating infrastructure

Use this guide when you have existing Terraform-managed infrastructure and want to bring it under Bluebricks management without destroying and recreating resources. You will publish your Terraform package, upload your existing state file via the API, and verify zero drift.

For background on how Bluebricks manages Terraform state, see Terraform/OpenTofu and State Management in the main documentation.

Before you begin

• Your Terraform configuration is working and applied

• You can run terraform state pull (or tofu state pull) successfully

• The Bricks CLI is installed and authenticated (bricks whoami returns your user)

• You have an organization API token

Uploading a state file that does not match your configuration can cause drift or destructive changes on the next plan. Verify that your package version and state file correspond to the same Terraform code before uploading.

Step-by-step

1

Publish the package

Navigate to your Terraform codebase directory and publish:

bricks bp publish

This creates a versioned package in Bluebricks. Note the package version number from the output.

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

2

Create a blueprint

1. In the Bluebricks app, go to Packages

2. Click Create blueprint

3. Add your newly published package to the blueprint

For help creating blueprints, see Creating Blueprints in the main documentation.

3

Pull existing Terraform state

From your current Terraform working directory:

terraform state pull > terraform.tfstate

This exports your current remote state to a local file.

4

Upload the state to Bluebricks

Upload the state file via the Bluebricks API:

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

Replace:

Placeholder	Value
<ENVIRONMENT_SLUG>	Your environment slug (visible in the Bluebricks app)
YOUR_API_TOKEN	Your organization API token
<PACKAGE_VERSION>	The version you published in step 1
<PACKAGE_ID>	The package ID used in the blueprint

The state file must be valid JSON.

5

Install the blueprint

Install the blueprint into a collection:

bricks install <blueprint>@<version> \
  --collection <collection_name> \
  --slug <ENVIRONMENT_SLUG>

6

Run a plan and verify zero drift

Run a plan in the Bluebricks app. You should see no resource changes.

If the plan shows creates or destroys, do not apply. See the troubleshooting section below.

Troubleshooting

Plan shows full recreate: check that the package version matches the original Terraform code, variables are identical, provider configuration has not changed, and the correct state file was uploaded. Re-upload the matching state file if needed.

API upload fails: verify that your API token is valid, the packageVersion exists, the package_id is correct, and the state file is valid JSON.

Environment slug not found: confirm the blueprint was installed successfully and the slug matches the one used during installation.

Related

• Terraform/OpenTofu overview (Docs)

• State Management and History (Docs)

• API Authentication (Docs)

• Deployments & Runs Troubleshooting