smom-dbis-138/docs/configuration/TERRAFORM_BACKEND_SETUP.md

Terraform Backend Setup Guide

Overview

This guide explains how to configure Terraform backend for state management using Azure Storage.

Prerequisites

• Azure CLI installed and configured
• Terraform >= 1.0
• Azure subscription with appropriate permissions
• Storage account (or create one)

Step 1: Create Storage Account

Option 1: Using Azure CLI

# Set variables
RESOURCE_GROUP="tfstate-rg"
STORAGE_ACCOUNT="tfstate$(openssl rand -hex 4)"
CONTAINER_NAME="tfstate"
LOCATION="eastus"

# Create resource group
az group create --name $RESOURCE_GROUP --location $LOCATION

# Create storage account
az storage account create \
  --resource-group $RESOURCE_GROUP \
  --name $STORAGE_ACCOUNT \
  --sku Standard_LRS \
  --kind StorageV2 \
  --location $LOCATION

# Create container
az storage container create \
  --name $CONTAINER_NAME \
  --account-name $STORAGE_ACCOUNT

# Get access key
ACCESS_KEY=$(az storage account keys list \
  --resource-group $RESOURCE_GROUP \
  --account-name $STORAGE_ACCOUNT \
  --query "[0].value" -o tsv)

echo "Storage Account: $STORAGE_ACCOUNT"
echo "Container: $CONTAINER_NAME"
echo "Access Key: $ACCESS_KEY"

Option 2: Using Terraform

cd terraform/backend-setup
terraform init
terraform apply

Step 2: Configure Backend

Option 1: Environment Variables

export ARM_STORAGE_ACCOUNT_NAME="tfstate<your-random>"
export ARM_CONTAINER_NAME="tfstate"
export ARM_RESOURCE_GROUP_NAME="tfstate-rg"
export ARM_ACCESS_KEY="<your-access-key>"

Option 2: Backend Config File

Create terraform/backend.hcl:

resource_group_name  = "tfstate-rg"
storage_account_name = "tfstate<random>"
container_name       = "tfstate"
key                  = "defi-oracle-mainnet.terraform.tfstate"

Then initialize:

terraform init -backend-config=backend.hcl

Option 3: Command Line

terraform init \
  -backend-config="resource_group_name=tfstate-rg" \
  -backend-config="storage_account_name=tfstate<random>" \
  -backend-config="container_name=tfstate" \
  -backend-config="key=defi-oracle-mainnet.terraform.tfstate" \
  -backend-config="access_key=<your-access-key>"

Step 3: Update terraform/main.tf

Uncomment the backend configuration in terraform/main.tf:

terraform {
  backend "azurerm" {
    resource_group_name  = "tfstate-rg"
    storage_account_name = "tfstate<random>"
    container_name       = "tfstate"
    key                  = "defi-oracle-mainnet.terraform.tfstate"
  }
}

Step 4: Initialize Terraform

cd terraform
terraform init

Step 5: Verify Backend

# Check backend configuration
terraform show -backend-config

# List state
terraform state list

Security Best Practices

1. Use Azure Key Vault

Store access keys in Azure Key Vault:

# Store access key in Key Vault
az keyvault secret set \
  --vault-name <key-vault-name> \
  --name "terraform-backend-key" \
  --value $ACCESS_KEY

Reference in Terraform:

data "azurerm_key_vault_secret" "backend_key" {
  name         = "terraform-backend-key"
  key_vault_id = azurerm_key_vault.main.id
}

terraform {
  backend "azurerm" {
    # Use Key Vault for access key
    access_key = data.azurerm_key_vault_secret.backend_key.value
  }
}

2. Enable Storage Account Security

• Enable soft delete
• Enable versioning
• Restrict network access
• Enable encryption at rest
• Use managed identity when possible

3. State Locking

Terraform automatically uses blob leasing for state locking. Ensure:

• Storage account supports blob leasing
• Network access allows Terraform to access storage

Troubleshooting

Backend Initialization Failed

Error: "Failed to get existing workspaces"

Solution:

1. Verify storage account exists
2. Check access key is correct
3. Verify container exists
4. Check network access rules

State Lock Error

Error: "Error acquiring the state lock"

Solution:

1. Check if another Terraform process is running
2. Manually release lock if process crashed:

   az storage blob lease break \
     --account-name $STORAGE_ACCOUNT \
     --container-name $CONTAINER_NAME \
     --blob-name "defi-oracle-mainnet.terraform.tfstate"
   

Access Denied

Error: "Access denied to storage account"

Solution:

1. Verify access key is correct
2. Check storage account firewall rules
3. Verify network access
4. Check RBAC permissions

Migration

Migrate from Local to Remote Backend

# Initialize with backend
terraform init -migrate-state

# Verify migration
terraform state list

Migrate Between Backends

# Update backend configuration
terraform init -migrate-state -backend-config=backend.hcl

References

• Terraform Azure Backend
• Azure Storage Documentation
• Terraform State Management