Develop Terraform Locally

Best practices for developing Terraform or OpenTofu locally with Bluebricks remote state, including state retrieval and safe collaboration.

Developing Terraform or OpenTofu locally is essential for creating Artifacts. The process should be fast, accurate, and reliable to ensure high-quality infrastructure before publishing.

Bluebricks offers best practices for local Terraform/OpenTofu development with a remote state, ensuring safe collaboration. It preserves the locking mechanism to prevent conflicts and enable real-time teamwork.

Where's my state?

Bluebricks' core capability is Separation of Concerns (SoC), allowing organizations to split infrastructure states into granular components called Environments. This enables independent life cycles, minimizes the blast radius, and improves scalability and maintainability.

In Bluebricks, each Blueprint environment has a unique slug, which identifies the state location.

A slug tags a specific implementation of a Blueprint, aka Environment. Within each Blueprint, an Artifact is identified by a unique ID, ensuring a distinct artifact instance and maintaining a unique namespace for its state.

The environment slug

Artifact unique ID is defined within the bricks.json

This structure preserves consistency, traceability, and isolation across environments and enables Bluebricks to dynamically generate a Terraform backend.

Eliminating the need for hardcoded associations between Terraform code and its live configuration ensures greater flexibility, portability, and maintainability.

How to get the backend configuration of an Environment

To retrieve the backend configuration of an Artifact, developers can use the Get Backend Config API or run the following bp state-config command from the Artifact folder.

The state-config Command

The bricks bp state-config command retrieves the Environment slug associated with the Artifact that needs modification.

For example, to modify the @zest/aws_vpc Artifact from the given screenshots, the developer should run:

bricks bp state-config latam-01-network

• The command generates a backend.tf file in the current directory, containing the remote state configuration.

• In addition, the command generates a temporary variables file (bbx-temp-terraform.auto.tfvars) containing properties from the last successful environment run.

Step-by-Step Guide

End to End Demo

The local work is executed against the actual remote state. Make changes with caution to avoid unintended modifications to deployed infrastructure. Always review planned changes before applying them.

Prerequisites

• Deploy at least one Blueprint to Bluebricks. If you haven’t deployed one yet, follow the Bluebricks Quick Start tutorial to get started.

• Access to your organizational Terraform or OpenTofu git repository

Steps

1. Navigate to the Artifact directory. If you don’t have access to an Artifact, clone your git repository holding the Terraform / OpenTofu code

2. Navigate to the source code directory

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

1. Run the following command, replacing <environment_slug> with the actual environment slug:

bricks bp state-config <environment_slug>

The command will generate a backend.tf file in the current directory, containing the remote state configuration. This allows Terraform/OpenTofu to connect to the correct backend without manual setup.

terraform {
  backend "http" {
    address        = "https://api.bluebricks.co/api/v1/environments/4cf06f98-.....-8cb88788888/my-sqs-prod/state"
    lock_address   = "https://api.bluebricks.co/api/v1/environments/4cf06f98-.....-8cb88788888/my-sqs-prod/lock"
    password       = "your-personal-jwt"
    unlock_address = "https://api.bluebricks.co/api/v1/environments/4cf06f98-.....-8cb88788888/my-sqs-prod/lock"
    username       = "your-temp-access-token"
  }
}

In addition, if applicable, the command will generate a temporary Terraform/OpenTofu variables file (e.g., bbx-terraform-temp.auto.tfvars) containing properties from the last successful environment run, ensuring the latest configuration is available for updates.

collection = "prod"
app_name = "my-sqs-topic"
region = "us-west-2"

1. Review the generated files (backend.tf and bbx-terraform-temp.auto.tfvars, if applicable) to ensure they match your expectations before making any modifications.

2. Use the generated backend.tf and bbx-terraform-temp.auto.tfvars files to work locally with the same settings as the deployed environment

3. Run terraform init and terraform plan to ensure your local environment matches the deployed state before making changes.

IMPORTANT: Before publishing the Artifact, ensure you remove the backend.tf file, as it contains your personal JWT.

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

echo "backend.tf" >> .bricksignore

This ensures sensitive credentials are not exposed in the registry.

Notes

• The backend.tf file will overwrite any existing backend.tf file in the current directory. Back up existing files if necessary before running the command to avoid losing important configurations.

• The bbx-terraform-temp.auto.tfvars file is ignored by default, so no additional action is required to exclude it from publishing.

• The temporary Terraform/OpenTofu variables file (e.g., bbx-terraform-temp.auto.tfvars) is only created if the environment configuration includes a variables map.

• Ensure that your local Terraform/OpenTofu version is compatible with the configuration in the generated files.

Troubleshoot

My resources are keep being recreated

Resources may be recreated unexpectedly if your local environment settings (e.g., region, project, or account) differ from those in your Terraform configuration. To prevent this, ensure your local environment variables match your configuration settings. For example, set the AWS region by running:

export AWS_REGION = eu-north-1

Or add the following provider config:

provider "aws" {
  region = var.aws_region
} 

bp state-confg failed to create the backend and variable files

The state-config command requires the CLI to be authenticated with your Bluebricks account. Make sure that you're authentication by running:

bricks login