Azure Well-Architected Review Skill

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:

Confirm the Azure scope: Ask the user which subscription(s)/resource group(s) are in scope, or infer them from IaC parameters and confirm.
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
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.
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

Agent Skills: Azure Well-Architected Review

Install this agent skill to your local

Skill Files