awesome-copilot/skills/azure-architecture-autopilot/references/bicep-generator.md

Bicep Generator Agent

Receives the finalized architecture spec from Phase 1 and generates deployable Bicep templates.

Step 0: Verify Latest Specs (Required Before Bicep Generation)

Do not hardcode API versions in Bicep code. Always fetch the MS Docs Bicep reference for the services you intend to use and confirm the latest stable apiVersion before using it.

Verification Steps

1. Identify the list of services to be used
2. Fetch the MS Docs URL for each service (using the web_fetch tool)
3. Confirm the latest stable API version from the page
4. Write Bicep using that version

Model Deployment Availability Check (Required When Using Foundry/OpenAI Models)

Verify that the model name specified by the user is actually deployable in the target region before generating Bicep. Model availability varies by region and changes frequently — do not rely on static knowledge.

Verification Methods (in priority order):

1. Check the MS Docs model availability page: https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models
2. Or query directly via Azure CLI:

   az cognitiveservices account list-models --name "<FOUNDRY_NAME>" --resource-group "<RG_NAME>" -o table
   

   (When the Foundry resource already exists)

If the model is not available in the target region:

• Inform the user and suggest available regions or alternative models
• Do not substitute a different model or region without user approval

Per-Service MS Docs URLs

The full URL registry is in references/azure-dynamic-sources.md. Refer to this file when fetching. Reference files are located under the .github/skills/azure-architecture-autopilot/ path.

Important

: Fetch directly from the URL using web_fetch to confirm the latest stable apiVersion. Do not blindly use hardcoded versions from reference files or previous conversations.

Always verify child resources too: Check the API versions for child resources (accounts/projects, accounts/deployments, privateDnsZones/virtualNetworkLinks, privateEndpoints/privateDnsZoneGroups, etc.) from the parent resource page. Parent and child API versions may differ.

Same principle applies when errors/warnings occur: If an API version–related error occurs during what-if or deployment, do not trust the version in the error message as the "latest version" and apply it directly. Always re-fetch the MS Docs URL to confirm the actual latest stable version before making corrections.

---

Information Reference Principles (Stable vs Dynamic)

Always Fetch (Dynamic)

• API version → Fetch from URLs in azure-dynamic-sources.md
• Model availability (name, version, region) → Fetch
• SKU list/pricing → Fetch
• Region availability → Fetch

Reference First (Stable)

• Required property patterns (isHnsEnabled, allowProjectManagement, etc.) → service-gotchas.md
• PE groupId & DNS Zone mappings (major services) → service-gotchas.md
• PE/security/naming common patterns → azure-common-patterns.md
• AI/Data service configuration guide → ai-data.md

If unsure about stable information, re-verify with MS Docs. But there is no need to fetch every time.

---

Unknown Service Fallback Workflow

When the user requests a service not covered by the v1 scope (ai-data.md):

1. Notify the user: "This service is outside the v1 default scope. It will be generated on a best-effort basis by referencing MS Docs."
2. Fetch API version: Construct the URL in the format https://learn.microsoft.com/en-us/azure/templates/microsoft.{provider}/{resourceType} and fetch
3. Identify resource type/required properties: Confirm the resource type and required properties from the fetched Docs
4. Verify PE mapping: Fetch https://learn.microsoft.com/en-us/azure/private-link/private-endpoint-dns to confirm groupId/DNS Zone
5. Apply common patterns: Apply security/network/naming patterns from azure-common-patterns.md
6. Write Bicep: Generate the module based on the above information
7. Hand off to reviewer: Validate compilation with az bicep build

Input Information

The following information must be finalized upon completion of Phase 1:

- services: [Service list + SKU]
- networking: Whether private_endpoint is used
- resource_group: Resource group name
- location: Deployment location (confirmed with user in Phase 1)
- subscription_id: Azure subscription ID

Output File Structure

<project-name>/
├── main.bicep              # Main orchestration — module calls and parameter passing
├── main.bicepparam         # Parameter file — environment-specific values, excluding sensitive info
└── modules/
    ├── network.bicep           # VNet, Subnet (including pe-subnet)
    ├── ai.bicep                # AI services (configured per user requirements)
    ├── storage.bicep           # ADLS Gen2 (isHnsEnabled: true required)
    ├── fabric.bicep            # Microsoft Fabric Capacity (only when needed)
    ├── keyvault.bicep          # Key Vault
    ├── monitoring.bicep        # Application Insights, Log Analytics (only needed for Hub-based configurations)
    └── private-endpoints.bicep # All PEs + Private DNS Zones + VNet Links + DNS Zone Groups

Module Responsibilities

network.bicep

• VNet — CIDR received as a parameter (to avoid conflicts with existing address spaces in the customer environment)
• pe-subnet — privateEndpointNetworkPolicies: 'Disabled' required
• Additional subnets handled via parameters as needed

ai.bicep

• Microsoft Foundry resource (Microsoft.CognitiveServices/accounts, kind: 'AIServices') — Top-level AI resource
  • customSubDomainName: foundryName required — Cannot be changed after creation. If omitted, the resource must be deleted and recreated
  • identity: { type: 'SystemAssigned' } required
  • allowProjectManagement: true required
  • Model deployment (Microsoft.CognitiveServices/accounts/deployments) — Performed at the Foundry resource level
• ⚠️ Foundry Project (Microsoft.CognitiveServices/accounts/projects) — Must be created as a child resource
  • Resource type: Microsoft.CognitiveServices/accounts/projects (never create as a standalone accounts resource)
  • Use parent: foundryAccount in Bicep
  • Incorrect example: Creating a Project as a separate kind: 'AIServices' account → Not recognized in the portal
  • Correct example:

    resource foundryProject 'Microsoft.CognitiveServices/accounts/projects@<apiVersion>' = {
      parent: foundryAccount
      name: 'project-${uniqueString(resourceGroup().id)}'
      location: location
      kind: 'AIServices'
      properties: {}
    }
    

• Azure AI Search — Semantic Ranking, vector search configuration
• Hub-based (Microsoft.MachineLearningServices/workspaces) should only be considered when the user explicitly requests it or when ML training/open-source models are needed. For standard AI/RAG workloads, Foundry (AIServices) is the default choice

⛔ CognitiveServices Prohibited Properties:

• apiProperties.statisticsEnabled — This property does not exist. Never use it. Causes ApiPropertiesInvalid error during deployment
• apiProperties.qnaAzureSearchEndpointId — QnA Maker only. Do not use with Foundry
• Do not arbitrarily add unvalidated properties to properties.apiProperties

storage.bicep

• ADLS Gen2: isHnsEnabled: true ← Never omit this
• Containers: raw, processed, curated (or as per requirements)
• allowBlobPublicAccess: false, minimumTlsVersion: 'TLS1_2'

keyvault.bicep

• enableRbacAuthorization: true (do not use access policy model)
• enableSoftDelete: true, softDeleteRetentionInDays: 90
• enablePurgeProtection: true

monitoring.bicep

• Log Analytics Workspace
• Application Insights (only needed for Hub-based configurations — not required for Foundry AIServices)

private-endpoints.bicep

• 3-piece set for each service:
  1. Microsoft.Network/privateEndpoints (placed in pe-subnet)
  2. Microsoft.Network/privateDnsZones + VNet Link (registrationEnabled: false)
  3. Microsoft.Network/privateEndpoints/privateDnsZoneGroups
• For per-service DNS Zone mappings, refer to references/service-gotchas.md

⚠️ Foundry/AIServices PE DNS Rules:

• PE groupId: account
• DNS Zone Group must include 2 zones:
  1. privatelink.cognitiveservices.azure.com
  2. privatelink.openai.azure.com
• Including only one causes DNS resolution failure for OpenAI API calls → connection error

⚠️ ADLS Gen2 (isHnsEnabled: true) PE Rules:

• 2 PEs required:
  1. blob → privatelink.blob.core.windows.net
  2. dfs → privatelink.dfs.core.windows.net
• Without the DFS PE, Data Lake operations (file system creation, directory manipulation) will fail

rbac.bicep (or inline in main.bicep)

⚠️ RBAC Role Assignment — Never Omit

Any service with a Managed Identity (identity.type: 'SystemAssigned') must have RBAC role assignments created. Having an identity without role assignments causes inter-service authentication failures. This is not optional — it is a mandatory item. Omission will be reported as CRITICAL in Phase 3 review.

• Required RBAC mappings:

Source Service	Target Service	Role	Role Definition ID
Foundry	Storage	Storage Blob Data Contributor	ba92f5b4-2d11-453d-a403-e96b0029c9fe
Foundry	AI Search	Search Index Data Contributor	8ebe5a00-799e-43f5-93ac-243d3dce84a7
Foundry	AI Search	Search Service Contributor	7ca78c08-252a-4471-8644-bb5ff32d4ba0
App Service	Key Vault	Key Vault Secrets User	4633458b-17de-408a-b874-0445c86b69e6
AKS (kubeletIdentity)	ACR	AcrPull	7f951dda-4ed3-4680-a7ca-43fe172d538d
Data Factory	Storage	Storage Blob Data Contributor	ba92f5b4-2d11-453d-a403-e96b0029c9fe
Data Factory	Key Vault	Key Vault Secrets User	4633458b-17de-408a-b874-0445c86b69e6
Databricks	Storage	Storage Blob Data Contributor	ba92f5b4-2d11-453d-a403-e96b0029c9fe

AKS Special Rule: AKS uses identityProfile.kubeletidentity.objectId, not identity.principalId.

// RBAC Example — Foundry → Storage Blob Data Contributor
resource foundryStorageRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storageAccount.id, foundry.id, 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
  scope: storageAccount
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
    principalId: foundry.identity.principalId
    principalType: 'ServicePrincipal'
  }
}

SQL Server Rules

• Password management: Declare @secure() param sqlAdminPassword string in main.bicep and pass it to modules
  • Do not generate with newGuid() inside modules — the password changes on redeployment
  • Store as a Key Vault Secret so it can be retrieved after deployment
• Authentication method: Default to administrators.azureADOnlyAuthentication: true
  • Many organizational policies (MCAPS, etc.) block standalone SQL authentication
  • AAD-only authentication + Managed Identity is the most secure configuration

Network Secret Handling

• VPN Gateway shared key: @secure() param vpnSharedKey string — @secure() is mandatory
• Never include plaintext VPN keys in .bicepparam — provide at deployment time or use Key Vault reference
• This rule applies the same as for SQL passwords
• Applies to: VPN shared key, ExpressRoute authorization key, Wi-Fi PSK, and all other network secrets
• Module params must also include the @secure() decorator

⚠️ Network Isolation Consistency Rules

• When setting publicNetworkAccess: 'Disabled', you must also create the corresponding PE for that service
• Setting publicNetworkAccess to Disabled without a PE makes the service unreachable → unusable after deployment
• The Phase 3 reviewer must report this inconsistency as CRITICAL
• When an inconsistency is found: either add a PE module or revert publicNetworkAccess to Enabled

Mandatory Coding Principles

Naming Conventions

// Use uniqueString to prevent naming collisions — always required
param foundryName string = 'foundry-${uniqueString(resourceGroup().id)}'
param searchName string = 'srch-${uniqueString(resourceGroup().id)}'
param storageName string = 'st${uniqueString(resourceGroup().id)}'  // No special characters allowed
param keyVaultName string = 'kv-${uniqueString(resourceGroup().id)}'

⚠️ Resources requiring customSubDomainName (Foundry, Cognitive Services, etc.) must include uniqueString(). Static strings (e.g., 'my-rag-chatbot') may already be in use by another tenant, causing deployment failures. The same applies to Foundry Project names — 'project-${uniqueString(resourceGroup().id)}'

Network Isolation

// Required for all services when using Private Endpoints
publicNetworkAccess: 'Disabled'
networkAcls: {
  defaultAction: 'Deny'
  ipRules: []
  virtualNetworkRules: []
}

Dependency Management

// Use implicit dependencies via resource references instead of explicit dependsOn
resource aiProject '...' = {
  properties: {
    hubResourceId: aiHub.id  // Reference to aiHub → aiHub is automatically deployed first
  }
}

Security

// Use Key Vault references for sensitive values — never store plaintext in parameter files
@secure()
param adminPassword string  // Do not put plaintext values in main.bicepparam

Code Comments

// Microsoft Foundry resource — kind: 'AIServices'
// customSubDomainName: Required, globally unique. Cannot be changed after creation — if omitted, resource must be deleted and recreated
// allowProjectManagement: true is required or Foundry Project creation will fail
// Replace apiVersion with the latest version fetched in Step 0
resource foundry 'Microsoft.CognitiveServices/accounts@<version fetched in Step 0>' = {
  kind: 'AIServices'
  properties: {
    customSubDomainName: foundryName
    allowProjectManagement: true
    ...
  }
}

⚠️ Bicep Code Quality Validation (Required After Generation)

Module Declaration Validation:

• Verify that the name: property in each module block is not duplicated
• Correct example: name: 'deploy-sql'
• Incorrect example: name: 'name: 'deploy-sql' (duplicated name: → compilation error)

Duplicate Property Prevention:

• If the same property name appears more than once within a single resource block, it causes a compilation error
• Especially common in complex resources like VPN Gateway (gatewayType), Firewall, AKS, etc.
• Check for BCP025: The property "xxx" is declared multiple times in the az bicep build output

az bicep build Must Be Run:

• After generating all Bicep files, always run az bicep build --file main.bicep
• Fix errors and recompile
• Warnings (BCP081, etc.) can be ignored after verifying the API version in MS Docs

main.bicep Base Structure

// ============================================================
// Azure [Project Name] Infrastructure — main.bicep
// Generated: [Date]
// ============================================================

targetScope = 'resourceGroup'

// ── Common Parameters ─────────────────────────────────────
param location string   // Location confirmed in Phase 1 — do not hardcode
param projectPrefix string
param vnetAddressPrefix string    // ← Confirm with user. Prevent conflicts with existing networks
param peSubnetPrefix string       // ← PE-dedicated subnet CIDR within the VNet

// ── Network ───────────────────────────────────────────────
module network './modules/network.bicep' = {
  name: 'deploy-network'
  params: {
    location: location
    vnetAddressPrefix: vnetAddressPrefix
    peSubnetPrefix: peSubnetPrefix
  }
}

// ── AI/Data Services ──────────────────────────────────────
module ai './modules/ai.bicep' = {
  name: 'deploy-ai'
  params: {
    location: location
    // Add separate params if regions differ per service — verify available regions in MS Docs
  }
  dependsOn: [network]
}

// ── Storage ───────────────────────────────────────────────
module storage './modules/storage.bicep' = {
  name: 'deploy-storage'
  params: {
    location: location
  }
}

// ── Key Vault ─────────────────────────────────────────────
module keyVault './modules/keyvault.bicep' = {
  name: 'deploy-keyvault'
  params: {
    location: location
  }
}

// ── Private Endpoints (All Services) ──────────────────────
module privateEndpoints './modules/private-endpoints.bicep' = {
  name: 'deploy-private-endpoints'
  params: {
    location: location
    vnetId: network.outputs.vnetId
    peSubnetId: network.outputs.peSubnetId
    foundryId: ai.outputs.foundryId
    searchId: ai.outputs.searchId
    storageId: storage.outputs.storageId
    keyVaultId: keyVault.outputs.keyVaultId
  }
}

// ── Outputs ───────────────────────────────────────────────
output vnetId string = network.outputs.vnetId
output foundryEndpoint string = ai.outputs.foundryEndpoint
output searchEndpoint string = ai.outputs.searchEndpoint

main.bicepparam Base Structure

using './main.bicep'

param location = '<Location confirmed in Phase 1>'
param projectPrefix = '<Project prefix>'
// Do not put sensitive values here — use Key Vault references
// Set regions after verifying per-service availability in MS Docs

@secure() Parameter Handling

When a .bicepparam file contains a using directive, additional --parameters flags cannot be used with az deployment. Therefore, @secure() parameters must follow these rules:

• Set a default value when possible: @secure() param password string = newGuid()
• If user input is required for @secure() parameters: Generate a JSON parameter file (main.parameters.json) alongside instead of using .bicepparam
• Never do this: Generate a command that uses .bicepparam and --parameters key=value simultaneously

Common Mistake Checklist

The full checklist is in references/service-gotchas.md. Key summary:

Item	❌ Incorrect	✅ Correct
ADLS Gen2	isHnsEnabled omitted	isHnsEnabled: true
PE Subnet	Policy not set	privateEndpointNetworkPolicies: 'Disabled'
PE Configuration	PE only created	PE + DNS Zone + VNet Link + DNS Zone Group
Foundry	kind: 'OpenAI'	kind: 'AIServices' + allowProjectManagement: true
Foundry	customSubDomainName omitted	customSubDomainName: foundryName — cannot be changed after creation
Foundry Project	Not created	Must always be created as a set with the Foundry resource
Hub Usage	Used for standard AI	Only when explicitly requested by user or ML/open-source models needed
Public Network	Not configured	publicNetworkAccess: 'Disabled'
Storage Name	Contains hyphens	Lowercase + digits only, uniqueString() recommended
API version	Copied from previous value	Fetch from MS Docs (Dynamic)
Region	Hardcoded	Parameter + verify availability in MS Docs (Dynamic)

After Generation Is Complete

When Bicep generation is complete:

1. Provide the user with a summary report of the generated file list and each file's role
2. Immediately transition to Phase 3 (Bicep Reviewer)
3. The reviewer proceeds with automated review and corrections following the references/bicep-reviewer.md guidelines