Terraform State

The TerraformStateManager and TerraformExecutor manage Terraform state for all infrastructure managed by the platform. State is stored remotely in cloud storage backends (Azure Blob Storage, AWS S3, or GCP Cloud Storage) with per-tenant isolation and state locking.

State Backend Architecture

Infrastructure Service
       |
       v
TerraformStateManager
       |
       +-- StateBackendConfig (provider-specific)
       |
       v
Cloud Storage
  |-- Azure Blob Storage (tfstate container)
  |-- AWS S3 (tfstate bucket)
  |-- GCP Cloud Storage (tfstate bucket)
       |
       +-- /tenants/<tenantId>/terraform.tfstate
       +-- /tenants/<tenantId>/terraform.tfstate.lock

State Management

Get State Info

Endpoint: GET /api/v1/infrastructure/terraform/tenants/:tenantId/state

Returns metadata about the Terraform state for a tenant (last modified, version, resource count) without exposing the state contents.

Lock State

Endpoint: POST /api/v1/infrastructure/terraform/tenants/:tenantId/state/lock

Acquires a lock on the tenant's Terraform state. State locking prevents concurrent modifications.

Unlock State

Endpoint: POST /api/v1/infrastructure/terraform/tenants/:tenantId/state/unlock

Releases the state lock. Used for manual recovery when a Terraform operation fails and leaves a stale lock.

TerraformExecutor

The TerraformExecutor wraps Terraform CLI operations with platform-specific conventions:

Operation	Description
`init`	Initialize the working directory with backend config
`plan`	Generate an execution plan
`apply`	Apply the planned changes
`destroy`	Tear down managed infrastructure
`output`	Read output values

Execution Flow

1. TerraformExecutor.init(stateBackendConfig)
2. TerraformModuleComposer.compose(tenantConfig)  --> generates main.tf
3. TerraformExecutor.plan()                        --> generates plan
4. TerraformExecutor.apply()                       --> applies changes
5. TerraformResult                                 --> captures output

TerraformModuleComposer

The TerraformModuleComposer dynamically generates Terraform configurations based on tenant requirements:

Selects appropriate modules based on cloud provider and tier
Sets resource parameters (database size, storage, networking)
Configures provider authentication using platform credentials
Generates variable files from tenant configuration

State Backend Configuration

StateBackendConfig

Field	Type	Description
`provider`	String	`azure`, `aws`, `gcp`
`containerName`	String	Storage container/bucket name
`stateKey`	String	State file path within the container
`resourceGroupName`	String	Azure resource group (Azure only)
`storageAccountName`	String	Azure storage account (Azure only)
`region`	String	Storage region
`encryptionEnabled`	boolean	Whether state is encrypted at rest

CloudStorageClient

The CloudStorageClient provides a unified interface for state operations across cloud providers:

Method	Description
`getState(key)`	Read state file from cloud storage
`putState(key, data)`	Write state file to cloud storage
`acquireLock(key)`	Acquire state lock
`releaseLock(key)`	Release state lock
`listStates(prefix)`	List state files

⚠️

Terraform state files may contain sensitive information including resource IDs, IP addresses, and connection strings. State files are encrypted at rest in cloud storage and access is restricted to the infrastructure service only.

Topology API Reference