Terraform State Management

IaCConsole eliminates state config boilerplate by generating unique, isolated backend paths automatically for every deployment.

No more sharing state files between environments. No more manually managing backend key values. IaCConsole CLI infers the correct state path from your org, dimensions, and unit — every time.

How It Works

When you run any iacconsole-cli exec command, the CLI:

1. Constructs a unique state path from your org name, dimension key-value pairs, and unit name.
2. Injects backend config into the OpenTofu/Terraform init call automatically using -backend-config flags.
3. Exposes backend values as var.iacconsole_backend_config inside your HCL for use in remote state data sources.

State Path Formula

$iacconsole_state_path = [org_<org>/]dimKey1_dimVal1/dimKeyN_dimValN/<unitName>.tfstate

Example: Running the following command:

iacconsole-cli exec -o demo-org -d account:prod -d datacenter:us-east-1 -u vpc -- apply

Generates the state path:

account_prod/datacenter_us-east-1/vpc.tfstate

Note: The org_ prefix is added only when no org-specific bucket is set in .iacconsolerc. If a dedicated bucket is configured for the org, the prefix is omitted to keep paths clean.

Configuration

Backend config is defined in .iacconsolerc under the defaults (or org-specific) section:

defaults:
  backend:
    bucket: default-tfstates
    key: $iacconsole_state_path # ← auto-replaced at runtime
    region: us-east-2

# Org-specific override — uses a dedicated bucket, no org_ prefix in path
demo-org:
  backend:
    bucket: demo-org-tfstates
    key: $iacconsole_state_path

The $iacconsole_state_path placeholder is replaced at runtime with the computed path.

Supported Backends

Any backend supported by OpenTofu / Terraform works with IaCConsole. The most common:

Backend	Required Unit Config
AWS S3	backend "s3" {} in versions.tf
Google Cloud Storage	backend "gcs" {} in versions.tf
Azure Blob Storage	backend "azurerm" {} in versions.tf
PostgreSQL	backend "pg" {} in versions.tf

AWS S3 Example

In your unit’s versions.tf:

terraform {
  backend "s3" {}
}

In .iacconsolerc:

defaults:
  backend:
    bucket: my-tfstates
    key: $iacconsole_state_path
    region: us-east-1

Google Cloud Storage Example

In your unit’s versions.tf:

terraform {
  backend "gcs" {}
}

In .iacconsolerc:

gcp-org:
  backend:
    bucket: gcp-tfstates
    prefix: $iacconsole_state_path

Cross-Unit Remote State (Data Sources)

To reference another unit’s outputs, use the var.iacconsole_backend_config variable — automatically injected by the CLI — so you never need to hard-code bucket names:

# Read outputs from the "network" unit in the same environment
data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = var.iacconsole_backend_config.bucket
    key    = "account_prod/datacenter_us-east-1/network.tfstate"
    region = var.iacconsole_backend_config.region
  }
}

resource "aws_instance" "app" {
  subnet_id = data.terraform_remote_state.network.outputs.private_subnet_id
}

For GCS:

data "terraform_remote_state" "network" {
  backend = "gcs"
  config = {
    bucket = var.iacconsole_backend_config.bucket
    prefix = "account_free-tier/network.tfstate"
  }
}

Isolated State Per Environment

Because the state path encodes every dimension value, each environment gets a completely isolated state file:

Command	Generated State Path
-o demo-org -d account:dev -d datacenter:eu-west-1 -u vpc	account_dev/datacenter_eu-west-1/vpc.tfstate
-o demo-org -d account:staging -d datacenter:eu-west-1 -u vpc	account_staging/datacenter_eu-west-1/vpc.tfstate
-o demo-org -d account:prod -d datacenter:us-east-1 -u vpc	account_prod/datacenter_us-east-1/vpc.tfstate

This eliminates the risk of accidentally sharing or overwriting state between environments — a common source of production incidents with manually managed Terraform backends.

Plugin Cache (Performance Tip)

Add a ~/.tofurc to reuse downloaded providers across runs:

plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
plugin_cache_may_break_dependency_lock_file = true

Create the cache directory:

mkdir -p "$HOME/.terraform.d/plugin-cache"