Skip to content

svcgdatacommon-infrastructure

Infrastructure as Code (IaC) repository for provisioning and managing Azure resources for the Servicing Data Common application across multiple environments using Terraform.

Overview

This repository manages the complete Azure infrastructure for the Servicing Data Common application, including networking, databases, function apps, storage, and security components. It follows a modular Terraform approach with environment-specific configurations for Dev, QA, UAT, and Prod.

Key Capabilities

  • Multi-environment deployment - Dev, QA, UAT, and Prod configurations
  • Hub-spoke network architecture - VNet peering with central hub for shared services
  • Private endpoints - Secure, private connectivity to all Azure PaaS services
  • Disaster recovery - Multi-region Cosmos DB with automatic failover (Production)
  • Automated CI/CD - Azure DevOps pipelines with security scanning and approval gates
  • State management - Remote state stored in Azure Storage with locking

Architecture

Azure Resources Managed

Resource Type Purpose
Virtual Networks Hub-spoke topology with custom DNS and subnets
Azure SQL Database ODS database with private endpoint access
Cosmos DB AccessManagement and DataDictionaries databases with SQL API
Key Vault Secrets management for connection strings and credentials
Function Apps Linux-based serverless compute with container registry integration
Storage Accounts Blob storage with private endpoints
App Service Plans Hosting infrastructure for Function Apps
NAT Gateway Outbound internet connectivity for VNet-integrated services
Private DNS Zones Name resolution for private endpoints

Repository Structure

svcgdatacommon-infrastructure/
├── environments/                    # Environment-specific configurations
│   ├── dev/
│   │   ├── backend.tf              # State backend configuration
│   │   ├── dev.tf                  # Dev environment variables
│   │   └── providers.tf            # Azure provider setup
│   ├── qa/
│   ├── uat/
│   └── prod/
├── svcgdatacommon-resources/       # Terraform module implementations
│   ├── app-service-plan.tf
│   ├── cosmosdb.tf
│   ├── key-vault.tf
│   ├── linux-function-app.tf
│   ├── local-names.tf              # Naming conventions
│   ├── nat-gateway.tf
│   ├── network-security-group.tf
│   ├── resource-group.tf
│   ├── sql.tf
│   ├── storage-account.tf
│   ├── subnet.tf
│   ├── tags.tf
│   ├── variables.tf                # Module variable definitions
│   └── virtual-network.tf
└── pipelines/                      # Azure DevOps CI/CD
    └── svcg-data-common-infrastructure.yml

Module Pattern

This repository uses a root module pattern: - The svcgdatacommon-resources/ directory contains all resource definitions as a reusable module - Each environment directory instantiates this module with environment-specific variable values - Module reference: source = "../../svcgdatacommon-resources"

Environments

Environment Azure Subscription VNet Address Space Key Vault
Dev Enterprise Dev/Test 10.221.128.0/24 CmgSvcgDataCommonKvDev01
QA Enterprise Dev/Test 10.221.130.0/24 CmgSvcgDataCommonKvQa01
UAT Microsoft Azure Enterprise 10.220.130.0/24 CmgSvcgDataCommonKvUat01
Prod Microsoft Azure Enterprise 10.220.56.0/26 CmgSvcgDataCommonKvProd01

Production Disaster Recovery

The Production environment includes comprehensive DR capabilities:

  • Multi-region Cosmos DB: westus2 (primary) and westcentralus (secondary)
  • Automatic failover: Enabled for seamless regional failover
  • Multi-region writes: Active-active write capability across both regions
  • Continuous backup: 30-day point-in-time restore capability
  • Zone redundancy: Enabled in both regions for high availability

Getting Started

Prerequisites

  • Terraform v1.9 or later
  • Azure CLI v2.0 or later
  • Appropriate Azure RBAC permissions for target subscription

Authentication

Authenticate with Azure CLI:

az login
az account set --subscription "Enterprise Dev/Test"  # or appropriate subscription

Working with Environments

Navigate to the target environment directory:

cd environments/dev  # or qa, uat, prod

Basic Terraform Workflow

# Initialize Terraform (downloads providers and configures backend)
terraform init

# Validate configuration syntax
terraform validate

# Format code to canonical style
terraform fmt -recursive

# Preview changes
terraform plan

# Apply changes (DO NOT EXECUTE OUTSIDE OF EMERGENCIES)
terraform apply

# View current state
terraform show

# List all managed resources
terraform state list

Common Operations

Viewing Infrastructure

# List all resources in state
terraform state list

# Show details of a specific resource
terraform state show module.svcgdatacommon.azurerm_cosmosdb_account.cosmosdb

# View all outputs
terraform output

# View outputs as JSON
terraform output -json

Adding New Resources

  1. Add resource definition to appropriate file in svcgdatacommon-resources/
  2. Add any required variables to svcgdatacommon-resources/variables.tf
  3. Set environment-specific values in environments/{env}/{env}.tf
  4. Create a feature branch and PR to be merged into dev
  5. Apply in Dev and QA via ADO pipelines
  6. Create a PR to merge dev into main
  7. Apply in UAT and Prod via ADO pipelines

Troubleshooting State Issues

# Refresh state from actual infrastructure
terraform plan -refresh-only

# View differences between state and actual infrastructure
terraform plan -detailed-exitcode

CI/CD Pipeline

Automated Deployment

The Azure DevOps pipeline (pipelines/svcg-data-common-infrastructure.yml) triggers on commits to: - dev branch - master branch - feature/** branches - fix/** branches

Pipeline Stages

For each environment, the pipeline executes:

  1. Checkov Security Scan - Static analysis for security misconfigurations
  2. Terraform Validate - Configuration validation
  3. Terraform Plan - Generate execution plan
  4. Terraform Apply - Apply changes (requires approval for production)

Security Architecture

Private Endpoints

All Azure PaaS services use private endpoints with private DNS resolution:

Service Private DNS Zone
Cosmos DB privatelink.documents.azure.com
Key Vault privatelink.vaultcore.azure.net
Storage Account privatelink.blob.core.windows.net
SQL Database privatelink.database.windows.net

Private DNS zones are centrally managed in the shared infrastructure resource group.

Network Security

  • VNet Integration: Function Apps integrate with dedicated integration subnet
  • Service Endpoints: Enabled for Storage, Key Vault, and SQL
  • NAT Gateway: Provides secure outbound connectivity
  • Network Security Groups: Control traffic flow between subnets
  • No Public Access: All databases and storage accounts accessible only via private endpoints

Secrets Management

  • SQL admin passwords auto-generated using random_password resource
  • All connection strings stored in Azure Key Vault
  • Function Apps use managed identity for Key Vault access
  • No secrets stored in Terraform state or code

State Management

Backend Configuration

  • Type: Azure Storage Account (azurerm backend)
  • Container: svcgdatacommontfstate
  • State Locking: Enabled via Azure Storage blob leasing
  • Dev State Storage: cmginfrastdev01 storage account

State Operations

# Move resource in state (useful for refactoring)
terraform state mv <source> <destination>

# Remove resource from state (doesn't delete actual resource)
terraform state rm <resource_address>

# Import existing Azure resource into state
terraform import <resource_address> <azure_resource_id>

Database Configuration

Cosmos DB

Two databases with multiple containers:

AccessManagement Database - accountprofiles container

DataDictionaries Database - documentcategories container - documenttypemap container - vendorpartners container

SQL Database

  • Single SQL Server per environment
  • ODS database with private endpoint
  • Auto-generated admin credentials in Key Vault
  • Automated connection string management

Development Workflow

Git Workflow

# Create feature branch
git checkout -b feature/new-resource

# Make changes and test locally
cd environments/dev
terraform plan

# Commit changes
git add -A
git commit -m "feat(cosmosdb): add new container for feature"

# Push to remote (triggers CI/CD pipeline)
git push -u origin feature/new-resource

Branching Strategy

  • Main branch: dev
  • Feature branches: feature/*
  • Fix branches: fix/*

Note: Pushing to remote triggers CI/CD pipeline. Test locally first.

Variable Validation

The environment_name variable has strict validation: - Allowed values: "Dev", "Qa", "Uat", "Prod" (case-sensitive) - Purpose: Ensures consistent naming and configuration

Support and Documentation

Additional Resources

Common Issues

Issue: Error acquiring the state lock - Cause: Previous Terraform operation didn't complete cleanly - Solution: Check Azure Storage container for lease, manually break if needed (be cautious about doing this)

Issue: Provider configuration not present - Cause: Not running from environment directory - Solution: Always run Terraform commands from environments/{env}/ directories

Issue: Module not installed - Cause: Module reference changed or first-time setup - Solution: Run terraform init to download/update modules

License

Copyright © CMG. All rights reserved.