/azure-well-architected-review

name: azure-well-architected-review
description: 'Perform an Azure Well-Architected Framework review of the current workload IaC and architecture, generating findings and GitHub issues for improvements.'

Azure Well-Architected Review

This workflow performs a structured Azure Well-Architected Framework (WAF) review against your workload's IaC files and deployed infrastructure. It identifies risks across all 5 WAF pillars and creates GitHub issues to track remediation.

Prerequisites

• Azure CLI (`az`) configured and authenticated
• IaC files present in the repository (Bicep, Terraform, or ARM templates)
• GitHub MCP server configured and authenticated

Workflow Steps

Step 1: Load Well-Architected Framework Reference

Fetch current Azure WAF best practices:

• `https://learn.microsoft.com/en-us/azure/well-architected/`
• Service guides for the Azure services in use (`https://learn.microsoft.com/en-us/azure/well-architected/service-guides/`)
• Workload-specific guidance relevant to the workload type (SaaS, mission-critical, AI, etc.)

If the `microsoft.docs.mcp` MCP server is available, use it to query the latest pillar checklists and service-specific recommendations.

Step 2: Discover IaC & Architecture

Establish the review scope, then inventory both the code and the live environment:

1. **Confirm the Azure scope**: Ask the user which subscription(s)/resource group(s) are in scope, or infer them from IaC parameters and confirm. 2. **Scan the repository for IaC files**:

• Bicep: `**/*.bicep`, `bicepconfig.json`
• Terraform: `**/*.tf` (azurerm/azapi providers)
• ARM templates: `**/azuredeploy*.json`, `**/*.template.json`, files with `$schema` containing `deploymentTemplate`

3. **Inventory live resources** (always, even when IaC exists): `az resource list --resource-group <rg> --output json` (or subscription-wide), plus targeted `az <service> show` calls for configuration details the pillar checks need. 4. **Compare IaC with live inventory**: Flag drift — resources present in Azure but absent from IaC (portal-created), resources defined in IaC but not deployed, and configuration mismatches. Record drift findings for Step 3 (they typically map to the Operational Excellence pillar).

Identify key Azure services in use (compute, data, networking, security, observability) and generate a Mermaid architecture diagram.

Step 3: Pillar-by-Pillar Review

Pillar 1: Reliability

• [ ] Availability zones enabled for zonal services (VMs, VMSS, AKS node pools, App Service, SQL, Storage ZRS)
• [ ] Production SKUs support the required SLA (no Basic/Free tiers on critical paths)
• [ ] Azure SQL / Cosmos DB backup and point-in-time restore configured with appropriate retention
• [ ] Geo-redundancy configured where RPO requires it (GRS/RA-GRS storage, SQL failover groups, Cosmos DB multi-region)
• [ ] Autoscale rules configured for App Service plans, VMSS, AKS (no fixed single instance for production)
• [ ] Health probes configured on Load Balancer / Application Gateway / Front Door backends
• [ ] Dead-lettering enabled for Service Bus queues/subscriptions and Event Grid subscriptions
• [ ] Retry policies with exponential backoff implemented for transient fault handling
• [ ] Disaster recovery plan defined (documented RTO/RPO, tested failover)

Pillar 2: Security

• [ ] Managed identities used instead of service principals with secrets or connection strings
• [ ] No hardcoded credentials, keys, or connection strings in IaC or code
• [ ] Secrets stored in Azure Key Vault with RBAC authorization (not access policies)
• [ ] Storage accounts deny public blob access and disallow shared key access where possible
• [ ] Private endpoints (or at minimum service endpoints + firewall rules) for PaaS data services
• [ ] NSGs restrict inbound traffic to minimum required ports/CIDRs (no `*` → `*` allow rules)
• [ ] TLS 1.2+ enforced on all endpoints (`minimumTlsVersion`, `httpsOnly`)
• [ ] Azure RBAC follows least privilege (no Owner/Contributor at subscription scope for workload identities)
• [ ] Microsoft Defender for Cloud enabled on relevant resource types (`az security pricing list`)
• [ ] Azure WAF (Application Gateway or Front Door) configured for public-facing web endpoints
• [ ] Diagnostic settings send security logs to Log Analytics / Microsoft Sentinel

Pillar 3: Cost Optimization

• [ ] Reservations or savings plans evaluated for steady-state compute (VMs, App Service, SQL)
• [ ] Storage lifecycle management policies move blobs to cool/archive tiers
• [ ] Right-sized SKUs based on actual utilization (no oversized VMs/App Service plans)
• [ ] Dev/test environments use auto-shutdown schedules and Dev/Test pricing where eligible
• [ ] Azure Budgets and cost alerts configured (`az consumption budget list`)
• [ ] Unattached managed disks and orphaned public IPs identified and removed
• [ ] Consumption/serverless tiers used for spiky or low-volume workloads (Functions, Container Apps, SQL serverless)
• [ ] Log Analytics retention and data-cap settings tuned to avoid ingestion overruns

Pillar 4: Operational Excellence

• [ ] All infrastructure defined as IaC (no manual portal changes; deny assignments or policy where feasible)
• [ ] Consistent tagging strategy applied across all resources (owner, environment, cost center)
• [ ] Azure Monitor alerts defined for key metrics and service health
• [ ] Automated deployment pipeline present (GitHub Actions / Azure Pipelines, no manual deployments)
• [ ] Azure Activity Log and resource diagnostic settings routed to Log Analytics
• [ ] Application Insights (or OpenTelemetry equivalent) instrumented for application workloads
• [ ] Azure Policy assignments enforce organizational standards (allowed locations, SKUs, tags)
• [ ] Runbooks or operational documentation present

Pillar 5: Performance Efficiency

• [ ] Right-sized compute SKUs validated against load requirements
• [ ] Caching implemented where beneficial (Azure C