williamlimasilva/azure-well-architected-review

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 Cache for Redis, CDN/Front Door caching)
• [ ] Azure Front Door or CDN used for global static content delivery
• [ ] Autoscale based on load metrics rather than fixed instance counts
• [ ] Database performance tier appropriate (DTU vs vCore, elastic pools, Cosmos DB RU autoscale)
• [ ] Premium/zone-redundant storage used for latency-sensitive disk workloads
• [ ] Connection pooling and async patterns used for database and HTTP clients

Step 4: Risk Classification

For each finding, classify:

• High Risk: Security vulnerability, single point of failure, no backup/recovery
• Medium Risk: Suboptimal reliability, cost inefficiency, performance concern
• Low Risk: Best practice deviation, minor optimization opportunity

Step 5: User Confirmation

🏗️ Azure Well-Architected Review Summary

📊 Review Results:
• IaC Files Analyzed: X
• Azure Services Identified: Y
• Total Findings: Z
  • High Risk: A (immediate action required)
  • Medium Risk: B (should address soon)
  • Low Risk: C (nice to have)

🔴 Top High Risk Findings:
1. [Pillar]: [Finding] — [Why it matters]
2. [Pillar]: [Finding] — [Why it matters]

💡 This will create Z individual GitHub issues + 1 EPIC issue.

❓ Proceed with creating GitHub issues? (y/n)

Gate: Only proceed to Steps 6–7 if the user gives an explicit affirmative response (e.g. "y", "yes"). On a negative, ambiguous, or missing response, do not create any GitHub issues — output the full findings as formatted markdown to the console and stop.

Step 6: Create Individual Finding Issues

Label with "well-architected" and the pillar name (e.g., "security", "reliability").

Title: [WAF-<PILLAR>] [Brief Finding] — [Risk Level]

Body:

## 🏗️ Well-Architected Finding: [Brief Title]

**Pillar**: [Name] | **Risk Level**: [High/Medium/Low] | **Effort**: [Low/Medium/High]

### 📋 Description
[Clear explanation of the finding and why it matters]

### 🔧 Remediation

**IaC Fix** (preferred):
```bicep
// Bicep example
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  sku: { name: 'Standard_ZRS' }
  kind: 'StorageV2'
  properties: {
    minimumTlsVersion: 'TLS1_2'
    allowBlobPublicAccess: false
    supportsHttpsTrafficOnly: true
  }
}
```

**Azure CLI fallback**:
```bash
az storage account update --name <name> --resource-group <rg> \
  --min-tls-version TLS1_2 --allow-blob-public-access false --https-only true
```

### 📚 Azure Reference
- [WAF Best Practice Link]
- [Microsoft Learn Documentation Link]

### ✅ Validation
- [ ] Change implemented in IaC and deployed
- [ ] Azure Policy compliance passes (if applicable)
- [ ] Microsoft Defender for Cloud recommendation resolved (if applicable)

**Well-Architected Recommendation**: [WAF checklist item this maps to]

Step 7: Create EPIC Tracking Issue

Label with "well-architected" and "epic".

Title: [EPIC] Azure Well-Architected Review — X findings across 5 pillars

Body: Executive summary with pillar breakdown table (finding counts by pillar and risk level), Mermaid architecture diagram, prioritized checklist linking all individual issues (High → Medium → Low), and success criteria:

• All High-risk findings resolved
• Medium findings have accepted mitigation plans
• No regression in existing Azure Monitor alerts or Azure Policy compliance

Error Handling

• No IaC Files Found: Limit review to live resource discovery via Azure CLI (az resource list) and note the gap
• Insufficient Azure Permissions: List required read-only roles for the review (Reader, Security Reader)
• GitHub Creation Failure: Output all findings as formatted markdown to console

Success Criteria

• ✅ All 5 WAF pillars reviewed against IaC and live infrastructure
• ✅ All findings classified by risk level and pillar
• ✅ Actionable remediation steps with IaC examples for each finding
• ✅ GitHub issues created for team tracking
• ✅ Architecture diagram generated for EPIC context
• ✅ Microsoft Learn documentation references included