🚀 Quickstart for Azure Landing Zone

⚠️ 🚧 WORK IN PROGRESS - DRAFT 🚧 ⚠️

🚨 Important Notice: This template is currently under active development and should be considered a DRAFT version. Features, configurations, and documentation may change without notice. Use in production environments is not recommended at this time.

A production-ready, secure, and compliant infrastructure template for deploying containerized applications to Azure Landing Zone environments. This template follows Azure Landing Zone security guardrails and BC Government cloud deployment best practices.

🎯 What This Template Provides

• Full-stack containerized application: NestJS backend + React/Vite frontend
• Secure Azure infrastructure: Landing Zone compliant with proper network isolation
• Database management: PostgreSQL with Flyway migrations and optional CloudBeaver admin UI
• CI/CD pipeline: GitHub Actions with OIDC authentication
• Infrastructure as Code: Terraform with Terragrunt for multi-environment management
• Monitoring & observability: Azure Monitor, Application Insights, and comprehensive logging
• Security best practices: Managed identities, private endpoints, and network security groups

📋 Prerequisites

Required Tools

• Azure CLI v2.50.0+ - Installation Guide
• GitHub CLI v2.0.0+ - Installation Guide
• Terraform v1.5.0+ - Installation Guide
• Docker or Podman - Docker Installation

Required Accounts & Permissions

• BCGOV Azure account with appropriate permissions - Registry Link
• GitHub repository with Actions enabled
• Azure subscription with Owner or Contributor role
• Access to Azure Landing Zone with network connectivity configured

📁 Project Structure

/quickstart-azure-containers
├── .github/                   # GitHub Actions CI/CD workflows
│   └── workflows/
│       ├── pr-open.yml        # PR validation and deployment
│       ├── pr-close.yml       # PR cleanup
│       ├── pr-validate.yml    # Code quality checks
│       └── prune-env.yml      # Environment cleanup
├── infra/                     # Terraform infrastructure code
│   ├── main.tf                # Root configuration
│   ├── providers.tf           # Azure provider configuration
│   ├── variables.tf           # Global variables
│   ├── outputs.tf             # Infrastructure outputs
│   └── modules/               # Reusable infrastructure modules
│       ├── backend/           # App Service for NestJS API
│       ├── frontend/          # App Service for React SPA
│       ├── postgresql/        # PostgreSQL Flexible Server
│       ├── flyway/            # Database migration service
│       ├── network/           # VNet, subnets, NSGs
│       ├── monitoring/        # Log Analytics, App Insights
│       └── frontdoor/         # Azure Front Door CDN
├── backend/                   # NestJS TypeScript API
│   ├── src/                   # API source code
│   │   ├── users/             # User management module
│   │   ├── common/            # Shared utilities
│   │   └── middleware/        # Request/response middleware
│   ├── prisma/                # Database ORM configuration
│   │   └── schema.prisma      # Database schema definition
│   ├── test/                  # E2E API tests
│   └── Dockerfile             # Container build configuration
├── frontend/                  # React + Vite SPA
│   ├── src/                   # Frontend source code
│   │   ├── components/        # React components
│   │   ├── routes/            # Application routes
│   │   ├── services/          # API integration
│   │   └── interfaces/        # TypeScript interfaces
│   ├── e2e/                   # Playwright end-to-end tests
│   ├── public/                # Static assets
│   └── Dockerfile             # Container build configuration
├── migrations/                # Flyway database migrations
│   ├── sql/                   # SQL migration scripts
│   ├── Dockerfile             # Migration runner container
│   └── entrypoint.sh          # Migration execution script
├── docker-compose.yml         # Local development stack
├── initial-azure-setup.sh     # Azure setup automation script
└── package.json               # Monorepo configuration

🚀 Quick Start Guide

1. Clone and Setup Repository

# Use this template to create a new repository
gh repo create my-azure-app --template bcgov/quickstart-azure-containers --public

# Clone your new repository  
git clone https://github.com/your-org/my-azure-app.git
cd my-azure-app

2. Configure Azure Environment

The initial-azure-setup.sh script automates the complete Azure environment setup with OIDC authentication for GitHub Actions.

Prerequisites for Setup Script

• Azure CLI logged in (az login)
• GitHub CLI (optional, for automatic secret creation)
• Azure subscription with appropriate permissions
• Existing Azure Landing Zone resource group

Initial Setup for GHA and Terraform

# Make the setup script executable
chmod +x initial-azure-setup.sh

• follow the instruction in the header section of the file.

What the Setup Script Does

🔐 Identity & Authentication:

• Creates a user-assigned managed identity in your Landing Zone resource group
• Configures OIDC federated identity credentials for GitHub Actions
• Sets up environment-specific authentication (no secrets stored in Azure)

💾 Terraform State Management:

• Creates a secure Azure storage account for Terraform state files
• Enables blob versioning for state file protection
• Configures appropriate access permissions for the managed identity

🔑 GitHub Integration:

• Automatically creates GitHub environment if --create-github-secrets is used
• Sets up required secrets in your GitHub repository:
  • AZURE_CLIENT_ID
  • AZURE_TENANT_ID
  • AZURE_SUBSCRIPTION_ID
  • VNET_NAME (derived from resource group)
  • VNET_RESOURCE_GROUP_NAME

⚡ Azure Permissions:

• Assigns security group to the managed identity aligned with landing zone policy.
• Configures storage-specific permissions for Terraform state management
• Validates all configurations and provides verification

Post-Setup Verification

After running the script, verify the setup:

# Check managed identity was created
az identity show --name "my-app-github-identity" --resource-group "ABCD-dev-networking"

# Verify federated credentials
az identity federated-credential list --identity-name "my-app-github-identity" --resource-group "ABCD-dev-networking"

# Test GitHub Actions authentication (in your repository)
gh workflow run test-azure-connection  # if you have a test workflow

3. Configure GitHub Secrets (If Not Auto-Created)

If you didn't use the --create-github-secrets flag, manually add the following secrets to your GitHub repository (Settings > Secrets and variables > Actions > Environment secrets):

Required Environment Secrets

AZURE_CLIENT_ID=<managed-identity-client-id>
AZURE_TENANT_ID=<your-azure-tenant-id>
AZURE_SUBSCRIPTION_ID=<your-azure-subscription-id>
VNET_NAME=<landing-zone-vnet-name>
VNET_RESOURCE_GROUP_NAME=<landing-zone-rg-name>

💡 Tip: The setup script outputs the exact values to use for these secrets if you didn't use auto-creation.

4. Local Development Setup

# Install dependencies for all packages
npm install

# Start local development environment
docker-compose up -d

# Run database migrations
docker-compose exec migrations flyway migrate

# Start backend development server
cd backend && npm run start:dev

# Start frontend development server (in new terminal)
cd frontend && npm run dev

Access your local application:

• Frontend: http://localhost:5173
• Backend API: http://localhost:3000 (default; see docker-compose.yml for overrides)
• Database: localhost:5432 (postgres/default)

🚢 Deployment Process

Automated Deployment via GitHub Actions

The repository includes comprehensive CI/CD workflows:

Pull Request Workflow (pr-open.yml)

# Triggered on: Pull Request creation
# Actions:
# 1. Build and test frontend/backend containers
# 2. Run security scans and linting
# 3. Plan Terraform infrastructure changes
# 4. Ability to manually deploy for testing to tools
# 5. Run end-to-end tests

Merge to Main Workflow

# Triggered on: Merge to main branch
# Actions:
# 1. Build and push production containers
# 2. Deploy to staging environment
# 3. Run full test suite
# 4. Deploy to production (with approval)

Manual Deployment

Deploy Infrastructure

# Navigate to environment configuration
cd terragrunt/dev  # or test/prod

# Initialize and plan
terragrunt init
terragrunt plan

# Apply changes
terragrunt apply

🗄️ Database Management

Schema Migrations with Flyway

The template uses Flyway for database schema management:

Migration Files (migrations/sql/)

-- V1.0.0__init.sql
CREATE SCHEMA IF NOT EXISTS app;

CREATE TABLE app.users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Running Migrations

# Local development
docker-compose exec migrations flyway migrate

# Production (via container)
docker run --rm \
  -v $(pwd)/migrations/sql:/flyway/sql:ro \
  -e FLYWAY_URL=jdbc:postgresql://your-db:5432/app \
  -e FLYWAY_USER=your-user \
  -e FLYWAY_PASSWORD=your-password \
  flyway/flyway:11-alpine migrate

Database Administration with CloudBeaver

Optional CloudBeaver container provides web-based database management:

• Access: https://your-app-cloudbeaver.azurewebsites.net
• Features: Query editor, schema browser, data export/import

🔐 Security Features

Azure Security Best Practices

Network Security

• Private endpoints for all Azure services
• Network Security Groups with least-privilege rules
• Azure Front Door with WAF protection
• VNet integration for App Services

Identity & Access Management

• Managed identities for service-to-service authentication
• OIDC authentication for GitHub Actions (no stored credentials)

Application Security

• HTTPS everywhere with TLS 1.3 minimum
• Security headers (HSTS, CSP, X-Frame-Options)
• Container scanning in CI/CD pipeline

Security Configuration Examples

App Service Security (infra/modules/backend/main.tf)

resource "azurerm_linux_web_app" "backend" {
  # ... other configuration
  
  site_config {
    minimum_tls_version = "1.3"
    ftps_state         = "Disabled"
    
    # IP restrictions for enhanced security
    ip_restriction {
      service_tag = "AzureFrontDoor.Backend"
      action      = "Allow"
      priority    = 100
      headers {
        x_azure_fdid = [var.frontend_frontdoor_resource_guid]
      }
    }
    
    ip_restriction {
      name       = "DenyAll"
      action     = "Deny"
      priority   = 500
      ip_address = "0.0.0.0/0"
    }
  }
}

📊 Monitoring & Observability

Azure Monitor Integration

Application Insights Setup

resource "azurerm_application_insights" "main" {
  name                = "${var.app_name}-appinsights"
  location            = var.location
  resource_group_name = var.resource_group_name
  application_type    = "web"
  workspace_id        = azurerm_log_analytics_workspace.main.id
}

PostgreSQL Backups & Point-In-Time Recovery (PITR)

Azure PostgreSQL Flexible Server automatically supports point-in-time restore (PITR) to any moment within the configured backup retention window (postgres_backup_retention_period).

Key points:

• PITR window = retention days (7–35) you set in Terraform.
• Geo-redundant backup (postgres_geo_redundant_backup_enabled = true) improves DR but adds cost.
• Restores create a new server; you then repoint apps / rotate connection strings.

Restore example (CLI):

az postgres flexible-server restore \
  --resource-group <rg> \
  --name <new-server-name> \
  --source-server <current-server-name> \
  --restore-time "2025-08-12T15:04:05Z"

PostgreSQL Logging & Cost Tuning

Variables controlling verbosity:

• postgres_enable_server_logs: Master toggle for connection / duration logging.
• postgres_log_statement_mode: none | ddl | mod | all (default ddl). Avoid all in production unless debugging.
• postgres_log_min_duration_statement_ms: Slow query threshold (default 500 ms). Lower value = more logs & cost.
• postgres_track_io_timing: Enables IO timing (slight overhead, useful for perf diagnostics).
• postgres_pg_stat_statements_max: Controls number of statements tracked; higher values consume more memory.

Recommendations:

Scenario	log_statement	log_min_duration_statement_ms	Notes
Prod steady state	ddl	500–1000	Focus on schema changes + slow queries
Perf investigation	mod or all	100–250	Temporarily increase verbosity
Heavy cost pressure	none	1000–2000	Minimize ingestion volume

If you disable full statement logging (none/ddl) ensure slow query threshold captures problematic queries (set <= 1000 ms initially).

Metric Alert Customization

Metric alerts are enabled when postgres_alerts_enabled = true. Customize or add alerts via postgres_metric_alerts map. Default keys: cpu_percent, storage_used, active_connections.

Example override in terraform.tfvars:

postgres_alerts_enabled = true
postgres_alert_emails   = ["[email protected]", "[email protected]"]
postgres_metric_alerts = {
  cpu_percent = {
    metric_name = "cpu_percent"
    operator    = "GreaterThan"
    threshold   = 75
    aggregation = "Average"
    description = "CPU > 75% (tuned)"
  }
  failed_connections = {
    metric_name = "connections_failed"
    operator    = "GreaterThan"
    threshold   = 5
    aggregation = "Total"
    description = "Failed connections spike"
  }
}

Supported metric names (common): cpu_percent, storage_used, active_connections, connections_failed, deadlocks, serverlog_storage_percent.

Action Group:

• Created only if postgres_alert_emails is non-empty.
• Add/remove emails without recreating alerts (resource uses dynamic receivers).

High Availability SKU Validation

If postgres_ha_enabled = true, Terraform validates that postgres_sku_name starts with GP_ or MO_ (General Purpose / Memory Optimized). Adjust SKU before enabling HA to avoid apply failure.

Log Analytics Workspace

resource "azurerm_log_analytics_workspace" "main" {
  name                = "${var.app_name}-log-analytics"
  location            = var.location
  resource_group_name = var.resource_group_name
  sku                 = var.log_analytics_sku
  retention_in_days   = var.log_analytics_retention_days
}

Monitoring Dashboards

Access monitoring through:

• Azure Portal: Resource group > Monitoring
• Application Insights: Performance, failures, dependencies
• Log Analytics: Custom queries and alerts
• Azure Monitor: Infrastructure metrics and alerts

Testing in CI/CD

The GitHub Actions workflows include:

• Unit tests for frontend and backend
• Integration tests with test database
• E2E tests in containerized environment
• Security scanning of dependencies and containers
• Performance testing with load simulation

🏷️ Environment Management

Multi-Environment Setup

The template supports multiple environments with Terragrunt:

terragrunt/
├── terragrunt.hcl          # Root configuration
├── dev/
│   └── terragrunt.hcl      # Development overrides
├── test/
│   └── terragrunt.hcl      # Testing overrides
├── prod/
│   └── terragrunt.hcl      # Production overrides
└── tools/
    └── terragrunt.hcl      # Tools/utilities environment

Environment-Specific Configuration

Development (terragrunt/dev/terragrunt.hcl)

include "root" {
  path = find_in_parent_folders()
}

inputs = {
  app_service_sku_name_backend  = "B1"
  app_service_sku_name_frontend = "B1"
  postgres_sku_name            = "B_Standard_B1ms"
  backend_autoscale_enabled    = false
  enable_cloudbeaver         = true
}

Production (terragrunt/prod/terragrunt.hcl)

include "root" {
  path = find_in_parent_folders()
}

inputs = {
  app_service_sku_name_backend  = "P1V3"
  app_service_sku_name_frontend = "P1V3"
  postgres_sku_name            = "GP_Standard_D2s_v3"
  backend_autoscale_enabled    = true
  enable_cloudbeaver         = false
  postgres_ha_enabled         = true
}

🚨 Troubleshooting

Common Issues and Solutions

1. GitHub Actions Deployment Failures

Issue: OIDC authentication fails

Error: No subscription found. Run 'az account set' to select a subscription.

Solution:

• Verify AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_SUBSCRIPTION_ID secrets
• Ensure managed identity has proper federated credentials
• Check that repository URL matches federated identity configuration

2. Terraform State Issues

Issue: State file conflicts or locks

Error: Error acquiring the state lock

Solution:

# Force unlock (use with caution)
terragrunt force-unlock <lock-id>

# Or check Azure storage account permissions
az storage blob list --account-name your-storage --container-name tfstate

3. Container Deployment Issues - ACR (Azure Container Registry)

Issue: App Service fails to pull container (if using ACR)

Error: Failed to pull image: unauthorized

Solution:

• Verify managed identity has AcrPull role on container registry
• Check container registry URL in app settings
• Ensure container image exists and is accessible

4. Database Connection Issues

Issue: Backend cannot connect to PostgreSQL

Error: getaddrinfo ENOTFOUND your-postgres-server

Solution:

• Verify VNet integration and private endpoint configuration
• Check PostgreSQL firewall rules
• Ensure connection string environment variables are correct
• if you are using pgpool make sure you have this line ssl: process.env.PGSSLMODE === 'require' ? { rejectUnauthorized: false } : false,

Debugging Tools

1. Azure CLI Debugging

# Enable debug logging
az config set core.log_level=debug

# Check resource status
az webapp show --name your-app --resource-group your-rg

# View app service logs
az webapp log tail --name your-app --resource-group your-rg

📚 Additional Resources

Documentation Links

• Terraform Azure Provider
• Terragrunt Documentation
• NestJS Documentation
• React + Vite Documentation
• Prisma Documentation

🤝 Contributing

We welcome contributions to improve this template! Please see our Contributing Guidelines for details.

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Built with ❤️ by the NRIDS Team