Skip to content

Getting Started

Prerequisites

  • Terraform >= 1.6
  • Azure CLI authenticated to the target tenant
  • Permissions to create resources: network, private endpoint, policy, monitoring, storage

The bootstrap script automates state backend setup, provider registration, config file creation, and terraform init.

# Bootstrap the dev environment
./scripts/bootstrap.sh dev

# Bootstrap with custom options
./scripts/bootstrap.sh staging --resource-group rg-mystate --location westus2

# Skip provider registration if already done
./scripts/bootstrap.sh prod --skip-providers

The script is idempotent — safe to re-run at any time. It checks for existing resources before creating them.

What the Bootstrap Script Does

  1. Validates Azure CLI authentication
  2. Creates a resource group for Terraform state storage
  3. Creates a storage account with secure defaults (TLS 1.2, no public blob access)
  4. Creates a blob container for state files
  5. Registers required Azure resource providers
  6. Copies backend.tf.example to backend.tf with actual values
  7. Copies terraform.tfvars.example to terraform.tfvars
  8. Runs terraform init

After Bootstrap

  1. Review and update envs/<env>/terraform.tfvars with your values
  2. Run terraform plan to preview changes
  3. Run terraform apply after review
terraform -chdir=envs/dev plan
terraform -chdir=envs/dev apply

Option B: Manual Setup

1. Set Up Remote State Backend

# Create resource group for state
az group create --name rg-tfstate --location eastus

# Create storage account (name must be globally unique)
az storage account create \
  --name sttzstatedev \
  --resource-group rg-tfstate \
  --sku Standard_LRS \
  --encryption-services blob \
  --min-tls-version TLS1_2 \
  --allow-blob-public-access false

# Create container
az storage container create \
  --name tfstate \
  --account-name sttzstatedev

Repeat for each environment with distinct storage account names.

2. Configure Backend

cp envs/dev/backend.tf.example envs/dev/backend.tf
# Edit backend.tf with your storage account details

3. Configure Variables

cp envs/dev/terraform.tfvars.example envs/dev/terraform.tfvars
# Edit terraform.tfvars with your client name, region, CIDRs, etc.

4. Initialize and Deploy

cd envs/dev
terraform init
terraform plan
terraform apply

Key Inputs

Variable Purpose
client_name Client identifier for naming and tags
env Environment name (dev, staging, prod)
location Primary Azure region
vnet_cidr VNet CIDR range
subnets Subnet map for VNet deployment
data_profile cosmos or postgres
models OpenAI model deployments (name, model, version, capacity)
enable_cmk Customer-managed key in Key Vault
enable_aks Private AKS cluster
enable_policy_baseline Policy definitions and assignments
cost_center Value for cost-center tag (empty string omits)

Choosing a Tier

See the Blueprints section for full composition references.

Tier Start With Key Settings
Foundation blueprints/foundation.tf enable_cmk = false, enable_aks = false, enable_policy_baseline = false
Enterprise blueprints/enterprise.tf enable_policy_baseline = true, cost_center = "CC-..."
Regulated blueprints/regulated.tf enable_cmk = true, enable_aks = true, log_retention_days = 365

Validation

Run these before deploying or submitting changes:

./scripts/preflight.sh       # Check prerequisites and Azure context
./scripts/validate.sh        # Format check, init, validate across all environments
./scripts/drift_check.sh dev # Detect configuration drift

DevContainer

The repository includes a DevContainer configuration with a pinned toolchain:

  • Terraform
  • Azure CLI
  • GitHub CLI
  • tflint, checkov, terraform-docs

Open the repository in VS Code with the Dev Containers extension, or in GitHub Codespaces, to get a pre-configured environment.

CI/CD

The repository includes a GitHub Actions workflow that:

  • Validates and format-checks on every PR
  • Plans all three environments on PR
  • Applies sequentially on merge to main: dev → staging → prod
  • Each environment requires approval via GitHub Environments

See the Operations Guide for CI/CD configuration details.