Azure Enterprise Infra Planner

Azure Enterprise Infra Planner

When to Use This Skill

Activate this skill when user wants to:

• Plan enterprise Azure infrastructure from a workload or architecture description
• Architect a landing zone, hub-spoke network, or multi-region topology
• Design networking infrastructure: VNets, subnets, firewalls, private endpoints, VPN gateways
• Plan identity, RBAC, and compliance-driven infrastructure
• Generate Bicep or Terraform for subscription-scope or multi-resource-group deployments
• Plan disaster recovery, failover, or cross-region high-availability topologies

Quick Reference

Workflow (Start Here)

Follow the step-by-step instructions in workflow.md to execute the 7 phases of infrastructure planning and provisioning.

MCP Tools

Error Handling

Bicep Generation

Generate Bicep IaC files from the approved infrastructure plan.

Important: All Bicep files must be created under <project-root>/infra/. Never place .bicep files in the project root or in .azure/.

File Structure

Generate files under <project-root>/infra/:

infra/
├── main.bicep              # Orchestrator — deploys all modules
├── main.bicepparam         # Parameter values
└── modules/
    ├── storage.bicep        # One module per resource or logical group
    ├── compute.bicep
    ├── networking.bicep
    └── monitoring.bicep

Generation Steps

1. Create infra/ directory — create <project-root>/infra/ and <project-root>/infra/modules/ directories. All files in subsequent steps go here. 2. Read plan — load <project-root>/.azure/infrastructure-plan.json, verify meta.status === "approved" 3. Fetch Bicep schemas — for each resource in the plan, use a sub-agent to call bicepschema_get with resource-type set to the ARM type from the relevant resources/ category file (e.g., Microsoft.ContainerService/managedClusters). Instruct the sub-agent: "Return the full property structure for {ARM type}: required properties, allowed values, child resources. ≤500 tokens." Use this output — not training data — to generate correct resource definitions.

The schema tool returns only the schema for the exact type requested. Sub-resource types (e.g., Microsoft.Network/virtualNetworks/subnets) return a smaller, focused schema but miss parent-level properties (e.g., VNet encryption lives on the parent, not the subnet sub-resource). Strategy:

- Start with sub-resource types when validating child resources — smaller responses (~25KB vs ~95KB), easier to summarize

- Fetch the parent type separately when you need parent-level properties (encryption, tags, SKU) — delegate to a sub-agent with specific property extraction instructions to manage the large response

4. Generate modules — group resources by category; one .bicep file per group under infra/modules/. Use the schema from step 3 for property names, allowed values, and required fields. 5. Generate main.bicep — write infra/main.bicep that imports all modules and passes parameters 6. Generate parameters — create infra/main.bicepparam with environment-specific values

Bicep Conventions

• Use @description() decorators on all parameters
• Use @secure() for secrets and connection strings
• Choose targetScope in main.bicep based on the deployment plan:
• For single resource group deployments, set targetScope = 'resourceGroup' and deploy with az deployment group create.
• For subscription-scope deployments (for example, resources across multiple resource groups or subscription-level resources), set targetScope = 'subscription' and deploy with az deployment sub create.
• Use existing keyword for referencing pre-existing resources
• Output resource IDs and endpoints needed by other resources
• Use dependsOn only when implicit dependencies are insufficient

Parameter File Format

using './main.bicep'

param location = 'eastus'
param environmentName = 'prod'
param workloadName = 'datapipeline'

Multi-Environment

For multi-environment plans, generate one parameter file per environment:

infra/
├── main.bicep
├── main.dev.bicepparam
├── main.staging.bicepparam
└── main.prod.bicepparam

Validation Before Deployment

Run az bicep build --file infra/main.bicep to validate syntax before deploying.

AI & ML Pairing Constraints

AI Search

Cognitive Services

ML Workspace

Compute (PaaS) Pairing Constraints

App Service

App Service Plan

Container App

Container Apps Environment

Container Registry

Function App

Static Web App

Compute (IaaS) Pairing Constraints

AKS Cluster

Availability Set

Managed Disk

Virtual Machine

VM Scale Set

Data (Analytics) Pairing Constraints

Cosmos DB

Redis Cache

Storage Account

Data Factory

Synapse Workspace

Data (Relational) Pairing Constraints

SQL Server

SQL Database

MySQL Flexible Server

PostgreSQL Flexible Server

Messaging Pairing Constraints

Event Grid Topic

Event Hub

Service Bus

Monitoring Pairing Constraints

Application Insights

Log Analytics

Networking (Connectivity) Pairing Constraints

Azure Bastion

Azure Firewall

VPN Gateway

DNS Zone

Private DNS Zone

Private Endpoint

Networking (Core) Pairing Constraints

Virtual Network

Subnet

NSG

Route Table

Network Interface

Public IP

NAT Gateway

Networking (Traffic) Pairing Constraints

Application Gateway

Front Door

Load Balancer

API Management

Pairing Constraints Index

Security Pairing Constraints

Key Vault

Managed Identity

Deployment Execution

Execute infrastructure deployment after plan approval and IaC generation.

Status Gate

Before executing any deployment command, verify:

meta.status === "approved"

If status is not approved, stop and inform the user. Do not manually change the status.

Pre-Deployment Checklist

1. Plan approved — meta.status is approved 2. IaC generated — Bicep or Terraform files exist in <project-root>/infra/ 3. Azure context confirmed — subscription and resource group selected 4. User confirmation — explicit "yes, deploy" from the user 5. Syntax validated — az bicep build or terraform validate passed

Bicep Deployment

Scope selection: use resource-group scope when your template deploys into an existing resource group. Use subscription scope when your template creates resource groups or other subscription-level resources (policies, role assignments, etc.).

# Validate first (applies to both scopes)
az bicep build --file infra/main.bicep

Choose the command based on the targetScope set in main.bicep (see bicep-generation.md Bicep Conventions):

Resource Group Scope

# What-if preview
az deployment group create \
  --resource-group <resource-group-name> \
  --template-file infra/main.bicep \
  --parameters infra/main.bicepparam \
  --what-if

# Deploy
az deployment group create \
  --resource-group <resource-group-name> \
  --template-file infra/main.bicep \
  --parameters infra/main.bicepparam \
  --name <deployment-name>

PowerShell:

az deployment group create `
  --resource-group <resource-group-name> `
  --template-file infra/main.bicep `
  --parameters infra/main.bicepparam `
  --name <deployment-name>

Subscription Scope

# What-if preview
az deployment sub create \
  --location <location> \
  --template-file infra/main.bicep \
  --parameters infra/main.bicepparam \
  --what-if

# Deploy
az deployment sub create \
  --location <location> \
  --template-file infra/main.bicep \
  --parameters infra/main.bicepparam \
  --name <deployment-name>

PowerShell:

az deployment sub create `
  --location <location> `
  --template-file infra/main.bicep `
  --parameters infra/main.bicepparam `
  --name <deployment-name>

Terraform Deployment

cd infra

# Initialize
terraform init

# Preview changes
terraform plan -var-file=prod.tfvars -out=tfplan

# Apply (requires confirmation)
terraform apply tfplan

PowerShell:

Set-Location infra
terraform init
terraform plan -var-file=prod.tfvars -out=tfplan
terraform apply tfplan

Post-Deployment

After successful deployment:

1. Update status — set meta.status to deployed in <project-root>/.azure/infrastructure-plan.json 2. Verify resources — list resources in the target resource group using Azure CLI: az resource list -g <resource-group-name> -o table 3. Report to user — list deployed resources, endpoints, and any follow-up actions

Error Handling

Property & Pairing Checks

Cross-check each new resource's properties against every already-written resource it connects to. Only run the checks relevant to this resource's type. Consult the resource file's Pairing Constraints section for type-specific rules.

SKU Compatibility

Subnet & Network Conflicts

Storage Pairing

Cosmos DB

Key Vault & CMK

SQL Database

AKS Networking

Phase 1: Extract Insights

The goal of this phase is to extract insights from the user's existing Azure environment. These insights will be used to guide the planning process in later phases.

1. Check whether insights already exist at <project-root>/.azure/insights.json. If they do, reuse them and skip the rest of this phase. 2. Check whether the insights_get tool is available. If it is not, skip this phase. 3. Ask the user which scope to use for generating insights. Present these three options: a. "Subscription-scoped (default subscription)" — use this as the default if the user does not respond. b. "Subscription-scoped (choose a subscription)" — if selected, ask the user to provide a subscription name or ID. c. "Tenant-scoped (slower)" 4. Ask the user whether there are specific areas they want the insights to focus on. Present these options: a. "General" — use this as the default if the user does not respond. b. "Cost" c. "Reliability" d. "Security" e. "Performance" f. "Other" — this should be a custom input field. 5. Run the insights_get tool using a general-purpose subagent. Pass a one-line summary via the --query option that describes the user's infrastructure and the types of insights to prioritise. Do not pass the --nocache flag unless the user has explicitly asked for it. Begin Phase 2 while this tool runs. 6. Once the tool finishes, save the resulting JSON to <project-root>/.azure/insights.json. Do not include tool call metadata. If the tool errors or returns no insights, write an empty array [] to the file instead.

Gate

• insights.json must exist and match the Insights Schema defined in schema.md. If the tool errored or returned no insights, the file should contain an empty array [].

Phase 2: Research WAF

The goal of this phase is to understand user intent and gather WAF guidance using MCP tools.

Step 1 - Clarify Requirements

Clarify the user's requirements until you can confidently describe what they want to build. Do NOT proceed to Step 2 until all critical gaps are resolved. Stay focused on what the user needs — do not make architectural decisions or propose specific services yet.

1. Extract what's explicitly stated in the user's prompt: workload purpose, traffic expectations, data storage needs, security requirements, and budget constraints. 2. Identify gaps across: workload purpose, data/storage needs, networking requirements, security/compliance constraints, availability expectations, environments, expected scale, and budget. A gap is critical if it would fundamentally change the scope of the infrastructure. 3. Ask the user focused questions (≤5 per round) for critical gaps only. Repeat until no critical gaps remain. Defer region and SKU related questions until insights have been generated; only ask the user directly if the insights do not address them. 4. Summarize your understanding of the user's requirements and wait for confirmation before proceeding.

Step 2 - Identify Sub-Goals

Derive sub-goals and include them in inputs.subGoals. Sub-goals are implicit constraints the user hasn't stated but the workload clearly requires. Examples:

• "assume all defaults" -> Cost-optimized: consumption/serverless tiers, minimal complexity.
• "production system" -> Production-grade: zone redundancy, private networking, managed identity.
• "secure" -> Security-first: no public IPs on workload VMs; Bastion + Key Vault SSH key; Trusted Launch; managed identity over keys.
• "observable" -> Operational excellence baseline: Log Analytics + VM Insights, NSG flow logs, boot diagnostics, NAT Gateway for deterministic egress.

Step 3 - Research WAF

Mandatory: Call WAF MCP tools before reading local resource files.

1. Call get_azure_bestpractices with resource: "general", action: "all" for baseline guidance. Call once only. 2. Call wellarchitectedframework_serviceguide_get with service: "<name>" for each core service (in parallel). Examples: "Container Apps", "Cosmos DB", "App Service", "Event Grid", "Key Vault". Return URLs only. 3. Dispatch sub-agents in parallel to fetch every WAF URL (never inline — guides are 20–60 KB) and summarize in ≤500 tokens. Focus on: additional resources needed, required properties for security and reliability, and key design decisions. Do not skip this step to keep token usage down, even if the core WAF principles for these services are already well-established and captured in your plan. 4. Collect all WAF findings: missing resources, property hardening, architecture patterns.

Gate

• All tool calls must be completed and all WAF guides summarized.

Phase 3: Research Resources

The goal of this phase is to research Azure resources before generating the plan.

Step 1 - Resource Refinement

Cross reference WAF

Read WAF cross-cutting checklist. For every checklist item, either:

• Add missing resources / harden properties, or;
• Document the intentional omission in overallReasoning.tradeoffs and inputs.subGoals.

Insights Integration

Read .azure/insights.json produced by Phase 1 and evaluate each insight against the current workload and sub-goals identified in Phase 2:

• If an insight applies, prefer it over defaults — especially for region, SKU tier, security posture, naming, and tagging.
• If an insight doesn't apply, document the intentional omission in overallReasoning.tradeoffs.
• Insights can shape both resource selection and property configuration.
• Track each insight you apply in inputs.insightsApplied so the user can trace why a decision was made.

Mandatory Security rule: only apply a security-related insight if it results in an equal or stronger security posture than the alternatives. A weaker security posture from an insight is only acceptable when the user has explicitly requested it in the initial prompt.

Step 2 - Resource Lookup

Mandatory: Complete this step for every resource before generating the plan. WAF tools from Phase 2 provide architecture guidance, but do not provide ARM types, naming rules, or pairing constraints. This step fills those gaps.

For each resource identified since Phase 1: 1. Read the relevant resource reference file to get its ARM type, API version, and CAF prefix. Use resources/README.md as the index to help you find the right file (e.g., resources/compute-infra.md for AKS, resources/data-analytics.md for Cosmos DB). 2. Read the relevant pairing constraint file using constraints/README.md as the index. Each category file is <2K tokens, you must read the whole file for all resources in that category. 3. Required — for every resource, spawn a general-purpose sub-agent to fetch its naming rules. Pass the naming rules URL from the resource file and instruct the sub-agent to call microsoft_docs_fetch and return only the min/max length, allowed characters, and uniqueness scope. The resource file's CAF prefix is a style convention only — it does not capture these ARM-enforced constraints, so this step cannot be skipped.

Important Tip: Only load the category files you need. For a plan with AKS + Cosmos DB + VNet + Key Vault, you'd load 4 constraint files and 4 resource files (~5.5K tokens total) instead of the full catalog (~22K tokens).

After completing the steps above, verify from the tool results:

1. Type — Correct Microsoft.* resource type and API version 2. SKU — Available in target region, appropriate for workload 3. Region — Service available, data residency met 4. Name — CAF-compliant naming constraints 5. Dependencies — All prerequisites identified and ordered 6. Properties — Required properties per resource schema 7. Alternatives — At least one alternative with tradeoff documented

Gate

• Every resource has an ARM type, naming rules, and pairing constraints checked.
• Present the preliminary resource list to the user with brief justifications and wait for approval before proceeding.

Phase 4: Generate Plan

Build <project-root>/.azure/infrastructure-plan.json using the schema in schema.md. Set meta.status to draft.

Use the user requirements and the research gathered from previous phases to assist:

• Phase 1: insights from <project-root>/.azure/insights.json (existing environment, user-selected focus areas).
• Phase 2: clarified requirements, derived sub-goals (inputs.subGoals), and WAF summaries covering missing resources, property hardening, and architecture patterns.
• Phase 3: refined resource list, including ARM types, naming rules, and pairing constraints.

Important: Write the plan to file progressively using inline edits - never hold the full plan in a single tool-call output.

Gate

• The plan is fully written to file.

Phase 5: Verify Plan

Thoroughly and objectively verify the generated plan based on the following checklists:

• verification.md
• pairing-checks.md

Other mandatory areas to check:

• Goal coverage — does every user requirement map to a resource?
• Dependency completeness — every dependencies[] entry resolves
• Pairing constraints — SKU compatibility, subnet conflicts, storage pairing

You must fix any issue in-place in the plan JSON.

Gate

• Every item in both checklists pass (or have been fixed).
• Present plan to user and wait for manual and explicit approval before proceeding.
• Edit meta.status to approved if approved.
• Otherwise, ask the user for improvements, and return to Phase 2, 3, or 4 based on the nature of their request.

Phase 6: Generate IaC

Important: Before continuing this phase, meta.status must be set to approved as required by Phase 5.

1. Ask the user whether to generate Bicep, Terraform, or stop here. Never accept vague statements such as "continue", "yes", "go ahead", "proceed", or "make it". Only continue if the user instructs you to generate IaC and names the flavor (e.g. "yes, generate the Bicep" or "go ahead with Terraform"). 2. Generate IaC from the approved plan. Refer to bicep-generation.md for Bicep or terraform-generation.md for Terraform.

Gate

• All required IaC files generated and saved to disk.

Phase 7: Deployment

Destructive Action Gate

This phase is destructive and has irreversible effects. Explicitly confirm with the user whether to deploy, and mention the risks of altering live environments. Never accept implicit or vague intent; only continue if the user acknowledges the risks and instructs you to proceed (e.g. "I understand the risks, continue with deployment") in a reply sent after you have presented the risks. The original task prompt never satisfies this gate, even if it says "deploy" or "run all phases". Stop if no such reply is received. Do not accept vague statements such as "continue", "yes", "deploy now" (without risk acknowledgement), or "go ahead".

---

Important: Before continuing this phase, meta.status must be set to approved as required by Phase 5. Each destructive action requires explicit user confirmation.

Refer to deployment.md for executing deployment commands.

1. Confirm subscription and resource group with user 2. Select the correct deployment scope based on targetScope in main.bicep (resource group, subscription, management group, or tenant) 3. Run az bicep build to validate, then execute the matching scope command (az deployment group create, az deployment sub create, etc.) or terraform apply

AI & ML Resources

Documentation

Compute (PaaS) Resources

Documentation

Compute (IaaS) Resources

Documentation

Data (Analytics) Resources

Documentation

Data (Relational) Resources

Documentation

Messaging Resources

Documentation

Monitoring Resources

Documentation

Networking (Connectivity) Resources

Documentation

Networking (Core) Resources

Documentation

Networking (Traffic) Resources

Documentation

Resource Reference Index

Region Categories

Resources fall into region-scoped or global categories. Check individual files for details.

Globally-Unique Names

Some resources require globally unique names (e.g., Storage Accounts, Key Vaults). See individual category files.

Shared ARM Types

Resources share the Microsoft.* ARM type namespace. Each file documents the relevant ARM types and documentation URLs.

Security Resources

Documentation

Infrastructure Plan Schema

{
  meta: {
    planId: string // Unique identifier (e.g., "plan-1")
    generatedAt: string // ISO 8601 timestamp
    version: string // Schema version (e.g., "0.1-draft")
    status: "draft" | "approved" | "deployed" // Lifecycle state
  }
  inputs: {
    userGoal: string // User's stated objective or workload description, matches user query exactly
    subGoals?: string[] // Inferred architectural constraints and priorities derived from the user's request and research phase. Examples: "Cost-optimized: user chose defaults, avoid premium networking", "Security-first: encrypt all data, use managed identity", "Minimal complexity: single region, no VNet". These help evaluators understand intentional tradeoffs. Should be short list of 0-3 points.
    insightsApplied: string[] // For each insight that influenced this plan, cite the insight ID and explain how and why it was applied. Set to an empty array if no insights were applied. Document any unapplied insights in plan.overallReasoning.tradeoffs.
  }
  plan: {
    resources: {
      name: string // Logical resource name (CAF-compliant)
      type: string // ARM resource type (e.g., "Microsoft.Storage/storageAccounts")
      subtype?: string // Exact subtype (e.g., "Blob Storage", "Azure Function")
      location: string // Azure region (e.g., "eastus")
      sku: string // SKU tier (e.g., "Standard_LRS", "Consumption")
      properties?: Record<string, unknown> // Resource-specific properties
      reasoning: {
        whyChosen: string // Justification referencing WAF pillars (see phases/2-research-best-practices.md and phases/3-research-resources.md) or requirements
        alternativesConsidered: string[] // Other options evaluated
        tradeoffs: string // Key tradeoffs in this choice
      }
      dependencies: string[] // Names of resources this depends on (empty if none)
      dependencyReasoning?: string // Why these dependencies exist
      references: { title: string, url: string }[] // Links to Azure docs
    }[]
    overallReasoning: {
      summary: string // Overall architecture rationale
      tradeoffs: string // Top-level tradeoffs and gaps
    }
    validation: string // Deployment coherence statement
    architecturePrinciples: string[] // Guiding principles (e.g., "Highly available", "Secure")
    references: { title: string, url: string }[] // Architecture-level doc links
  }
}

Insights Schema

{
  id: string // Stable identifier (e.g., "insight-001"); cited from inputs.insightsApplied
  pattern: string // Observed fact from the tenant scan (what is true today)
  implication: string // Recommended planning action derived from the pattern
}[]

Terraform Generation

Generate Terraform IaC files from the approved infrastructure plan.

File Structure

Generate files under <project-root>/infra/:

infra/
├── main.tf                 # Root module — calls child modules
├── variables.tf            # Input variable declarations
├── outputs.tf              # Output values
├── terraform.tfvars        # Default variable values
├── providers.tf            # Provider configuration
├── backend.tf              # State backend configuration
└── modules/
    ├── storage/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    ├── compute/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    └── networking/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

Generation Steps

1. Create infra/ directory — create <project-root>/infra/ and <project-root>/infra/modules/ directories. All files in subsequent steps go here. 2. Read plan — load <project-root>/.azure/infrastructure-plan.json, verify meta.status === "approved" 3. Generate providers.tf — write infra/providers.tf to configure azurerm provider with required features 4. Generate modules — group resources by category; one module per group under infra/modules/ 5. Generate root main.tf — write infra/main.tf that calls all modules, wire outputs to inputs 6. Generate variables.tf — write infra/variables.tf with all configurable parameters 7. Generate terraform.tfvars — write infra/terraform.tfvars with default values from the plan 8. Generate backend.tf — write infra/backend.tf for Azure Storage backend remote state

Terraform Conventions

• Use azurerm provider (latest stable version)
• Set features {} block in provider configuration
• Use variable blocks with description, type, and default where appropriate
• Use locals for computed values and naming patterns
• Use depends_on only when implicit dependencies are insufficient
• Tag all resources with environment, workload, and managed-by = "terraform"

Provider Configuration

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
  subscription_id = var.subscription_id
}

Multi-Environment

For multi-environment plans, generate one .tfvars file per environment:

infra/
├── main.tf
├── variables.tf
├── dev.tfvars
├── staging.tfvars
└── prod.tfvars

Deploy with: terraform apply -var-file=prod.tfvars

Validation Before Deployment

Run terraform validate and terraform plan to verify before applying.

Resource Verification

Run these checks immediately after writing each resource to plan.resources[]. Fix issues in-place before moving to the next resource. Load the relevant category file from resources/ for naming constraints, valid SKUs, and pairing rules.

1. Name Checks

2. Dependency Checks

3. Property & Pairing Checks

Read pairing-checks.md in full. It covers SKU compatibility, subnet/network conflicts, storage pairing, Cosmos DB, Key Vault/CMK, SQL Database, and AKS networking. For every connected pair of resources in the plan, walk through each applicable rule, confirm compliance, and fix any violation in-place before moving on to the next pair.

4. Insights Checks

Skip this section when insights.json does not exist or contains no insights.

WAF Cross-Cutting Checklist

Walk through every row and decide if resources or properties are needed.

Common Additions

Most workloads should include these unless sub-goals justify omission:

• Key Vault — secrets, certificates, customer-managed keys
• Managed Identity — prefer over keys for service-to-service auth
• Application Insights — for App Service, Functions, Container Apps, AKS
• Log Analytics — centralized log aggregation
• Diagnostic Settings — wire data resources to Log Analytics

If you intentionally skip a concern (e.g., no VNet for cost reasons), document it in overallReasoning.tradeoffs and inputs.subGoals.

Workflow

Mandatory Rules

• You must execute the seven phases in sequential order. Follow the instructions precisely as defined. Do not continue to the next phase until the current phase is complete.
• You must stop on all "gate" conditions and only continue when the conditions have been met.
• Destructive actions require explicit user confirmation.
• You must read each phase's reference file in full before executing it.
• Never assume knowledge and cut corners or skip research steps.

Overview

Starting from Phase 1, execute all phases in sequential order. Do not advance to the next phase until the current phase is complete and all of its gate conditions have been met.

Plan Status Lifecycle

draft → approved → deployed

• draft — set by Phase 4 when the plan is written.
• approved — set by Phase 5 only after the user explicitly approves. Required before Phase 6 and Phase 7.
• deployed — set by Phase 7 after a successful az deployment ... create or terraform apply.

Outputs

Before writing any .bicep or .tf files in Phase 6:

1. Create the infra/ directory at <project-root>/infra/. 2. Create infra/modules/ for child modules. 3. Write main.bicep (or main.tf) inside infra/, not in the project root or .azure/.