> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Terraform

> Terraform deployment workflow and commands

This guide covers the Terraform deployment workflow for Soundcheck infrastructure.

## GitHub Actions workflow

The `terraform-apply.yml` workflow automates infrastructure deployment.

### Workflow steps

1. **Terraform Init** - Initialize with environment-specific backend
2. **tfsec Scan** - Security scanning (fails on HIGH severity)
3. **Format Check** - Validate code formatting
4. **Generate tfvars** - Pull secrets from Key Vault
5. **Terraform Plan** - Show proposed changes
6. **Terraform Apply** - Apply changes (only on merge)

### Triggers

| Trigger | Action |
| - | - |
| PR opened | Plan only (no changes) |
| Merge to `dev` | Apply to Dev |
| Merge to `qa` | Apply to QA |
| Merge to `main` | Apply to Production |

***

## Manual deployment

For exceptional cases, use the workflow\_dispatch trigger:

**1. Navigate to Actions**

Go to **Actions → Terraform Apply**

**2. Run workflow**

Click **Run workflow**

**3. Configure**

* Select branch
* Select environment
* Choose whether to apply after plan

**4. Monitor**

Watch the workflow execution

***

## Sandbox environment

Use sandbox for testing infrastructure changes before committing.

### Step 1: connect to Azure

```bash theme={null}
az login
az account set --subscription "Microsoft Azure Sponsorship"
```

### Step 2: create sandbox.tfvars

```bash theme={null}
cd infra/environments/dev
cp dev.tfvars.example sandbox.tfvars
```

Edit `sandbox.tfvars`:

* `env` → `"sbx"` (or similar unique prefix)
* `subscription_id` → your subscription ID

### Step 3: provision base resources

```bash theme={null}
terraform init
terraform apply -var-file="sandbox.tfvars" \
  -target=module.networking \
  -target=module.platform \
  -target=module.database \
  -target=module.security
```

### Step 4: add secrets

Populate Key Vault with secrets via Azure Portal or CLI.

### Step 5: provision remaining resources

```bash theme={null}
terraform apply -var-file="sandbox.tfvars"
```

> [!WARNING]
>
> Sandbox resources cost money. Destroy when done:
>
> ```bash theme={null}
> terraform destroy -var-file="sandbox.tfvars"
> ```

***

## Environment commands

### Dev environment

```bash theme={null}
cd infra/environments/dev
az account set --subscription "dbbacbf2-c2e4-41b5-b914-e9de96fff821"
./generate-tfvars.sh

terraform init -reconfigure \
  -backend-config="resource_group_name=dev-terraform-state" \
  -backend-config="storage_account_name=soundchecktfstatedev" \
  -backend-config="container_name=tfstate" \
  -backend-config="key=dev.tfstate"

terraform plan -var-file="dev.tfvars"
```

### QA environment

```bash theme={null}
cd infra/environments/qa
# Similar commands with qa-specific values
```

### Production environment

```bash theme={null}
cd infra/environments/prod
# Similar commands with prod-specific values
```

***

## Quick reference

```bash theme={null}
# Initialize
terraform init

# Plan changes
terraform plan -var-file="<env>.tfvars"

# Apply changes
terraform apply -var-file="<env>.tfvars"

# Destroy resources
terraform destroy -var-file="<env>.tfvars"

# Upgrade modules
terraform init -upgrade

# Format code
terraform fmt -recursive

# Validate configuration
terraform validate
```

***

## State management

| Environment | Resource Group | Storage Account | Container | State Key |
| - | - | - | - | - |
| Dev | `dev-terraform-state` | `soundchecktfstatedev` | `tfstate` | `dev.tfstate` |
| QA | `qa-terraform-state` | `soundchecktfstateqa` | `tfstate` | `qa.tfstate` |
| Prod | `prod-terraform-state` | `soundchecktfstateprod` | `tfstate` | `prod.tfstate` |

***

## Troubleshooting

> [accordion] Empty Variables in Generated tfvars
>
> You likely don't have Key Vault Secrets Officer access. Request access and repopulate the tfvars file.

> [accordion] State Lock Errors
>
> Break the blob lease:
>
> ```bash theme={null}
> az storage blob lease break \
>   --container-name tfstate \
>   --blob-name <env>.tfstate \
>   --account-name soundchecktfstate<env>
> ```

> [accordion] Permission Errors
>
> Verify login and subscription:
>
> ```bash theme={null}
> az account show
> az account set --subscription <name>
> ```

> [accordion] Module Changes Not Reflected
>
> Upgrade modules:
>
> ```bash theme={null}
> terraform init -upgrade
> ```

***

## Review requirements

| Target | Requirement |
| - | - |
| PRs to `dev` | Standard review |
| PRs to `qa` | Standard review |
| PRs to `main` | Infrastructure lead approval |

The branch-enforcement action prevents unauthorized merges.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.