# Migrate Terraform State to Bluebricks

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.

{% hint style="info" %}
For background on how Bluebricks manages Terraform state, see [Terraform/OpenTofu](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/packages/artifacts-overview/terraform-open-tofu) and [State Management](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/runs/state-management-and-history) in the main documentation.
{% endhint %}

## 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](https://bluebricks.co/docs/api/authenticate/authentication)

{% hint style="warning" %}
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.
{% endhint %}

## Step-by-step

{% stepper %}
{% step %}

#### Publish the package

Navigate to your Terraform codebase directory and publish:

```bash
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.
{% endstep %}

{% step %}

#### Create a blueprint

1. In the Bluebricks app, go to [**Packages**](https://app.bluebricks.co/packages)
2. Click **Create blueprint**
3. Add your newly published package to the blueprint

{% hint style="info" %}
For help creating blueprints, see [Creating Blueprints](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/packages/blueprints-overview/creating-blueprints) in the main documentation.
{% endhint %}
{% endstep %}

{% step %}

#### Pull existing Terraform state

From your current Terraform working directory:

```bash
terraform state pull > terraform.tfstate
```

This exports your current remote state to a local file.
{% endstep %}

{% step %}

#### Upload the state to Bluebricks

Upload the state file via the Bluebricks API:

```bash
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.
{% endstep %}

{% step %}

#### Install the blueprint

Install the blueprint into a collection:

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

{% endstep %}

{% step %}

#### 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.
{% endstep %}
{% endstepper %}

## 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](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/packages/artifacts-overview/terraform-open-tofu) (Docs)
* [State Management and History](https://docs.bluebricks.co/bluebricks-documentation/core-concepts/runs/state-management-and-history) (Docs)
* [API Authentication](https://bluebricks.co/docs/api/authenticate/authentication) (Docs)
* [Deployments & Runs Troubleshooting](https://bluebricks.co/docs/help/troubleshooting/deployments)