Develop Terraform Locally

How to run Terraform or OpenTofu locally when you need to debug or inspect remote state managed by Bluebricks

Use this guide when you need to run terraform plan or tofu plan locally against infrastructure managed by Bluebricks, for debugging or state inspection.

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

Before you begin

• At least one blueprint is deployed to a Bluebricks environment. If you haven't deployed one yet, follow the Quick Start tutorial

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

• You have access to the git repository containing the Terraform or OpenTofu source code

This procedure works against your live remote state. Review all planned changes carefully before applying anything. Use this for debugging and inspection, not production changes.

Step-by-step

1

Navigate to the source code directory

Clone or open your artifact's git repository and navigate to the directory containing your .tf files:

.                          <-- Artifact root directory
├── bricks.json
└── src
    └── terraform          <-- Navigate here
        ├── locals.tf
        ├── main.tf
        ├── outputs.tf
        ├── variables.tf
        └── vpc.tf

2

Run bricks bp state-config

Replace <ENVIRONMENT_SLUG> with your environment's slug (visible in the Bluebricks app on the environment page):

bricks bp state-config <ENVIRONMENT_SLUG>

This generates two files in your current directory:

• backend.tf: remote state backend configuration (contains a temporary JWT)

• bbx-terraform-temp.auto.tfvars: properties from the last successful run (if applicable)

3

Review the generated files

Open backend.tf and bbx-terraform-temp.auto.tfvars and confirm they match your expectations before proceeding.

4

Initialize and plan

Run terraform init (or tofu init) followed by terraform plan (or tofu plan):

terraform init
terraform plan

Confirm your local environment matches the deployed state before making any changes.

5

Clean up before publishing

The backend.tf file contains your personal JWT token. Remove it before publishing the artifact:

rm backend.tf

To prevent accidental publishing, add backend.tf to the .bricksignore file in the artifact root directory:

echo "backend.tf" >> .bricksignore

Troubleshooting

Resources keep being recreated: your local environment settings (region, project, or account) likely differ from your Terraform configuration. Make sure local environment variables match. For example, set the AWS region:

export AWS_REGION=eu-north-1

Or add explicit provider configuration:

provider "aws" {
  region = var.aws_region
}

bricks bp state-config fails to create files: the CLI is not authenticated. Run bricks login and try again.

JWT expired during a long session: the token in backend.tf expires after a period. Re-run bricks bp state-config <ENVIRONMENT_SLUG> to generate a fresh token.

Related

• Terraform/OpenTofu overview (Docs)

• Bricks CLI Overview (Docs)

• Packages & Blueprints Troubleshooting