Setting the file. One moment.
Skill 45 · Azure Architecture Autopilot
Subchapter 45.10
references/service-gotchas.mdMarkdown6 KBView on GitHub
Per-service summary of non-intuitive required properties, common mistakes, and PE mappings. Only near-immutable patterns are included here. Dynamic values such as API version, SKU lists, and region are not included.
Scripts
CLIAlso bundled
Gitignore| Service | Required Property | Result If Omitted | Notes |
|---|---|---|---|
| ADLS Gen2 | isHnsEnabled: true | Becomes regular Blob Storage. Cannot be reversed | kind: 'StorageV2' required |
| Storage Account | No special characters/hyphens in name | Deployment failure | Lowercase+numbers only, 3-24 characters |
| Foundry (AIServices) | customSubDomainName: foundryName | Cannot create Project, cannot change after creation → Must delete and recreate resource | Globally unique value |
| Foundry (AIServices) | allowProjectManagement: true | Cannot create Foundry Project | kind: 'AIServices' |
| Foundry (AIServices) | identity: { type: 'SystemAssigned' } | Project creation fails | |
| Foundry Project | Must be created as a set with Foundry resource | Cannot use from portal | accounts/projects |
| Key Vault | enableRbacAuthorization: true | Risk of mixed Access Policy usage | |
| Key Vault | enablePurgeProtection: true | Required for production | |
| Fabric Capacity | administration.members required | Deployment failure | Admin email |
| PE Subnet | privateEndpointNetworkPolicies: 'Disabled' | PE deployment failure | |
| PE DNS Zone | registrationEnabled: false (VNet Link) | Possible DNS conflict | |
| PE Configuration | 3-component set (PE + DNS Zone + VNet Link + Zone Group) | DNS resolution fails even with PE present |
The mappings below are stable, but re-verify from the PE DNS integration document in azure-dynamic-sources.md when adding new services.
| Service | groupId | Private DNS Zone |
|---|---|---|
| Azure OpenAI / CognitiveServices | account | privatelink.cognitiveservices.azure.com |
| ⚠️ (Foundry/AIServices additional) | account | privatelink.openai.azure.com ← Both zones must be included in DNS Zone Group. OpenAI API DNS resolution fails if omitted |
| Azure AI Search | searchService | privatelink.search.windows.net |
| Storage (Blob/ADLS) | blob | privatelink.blob.core.windows.net |
| Storage (DFS/ADLS Gen2) | dfs | privatelink.dfs.core.windows.net |
| Key Vault | vault | privatelink.vaultcore.azure.net |
| Azure ML / AI Hub | amlworkspace | privatelink.api.azureml.ms |
| Container Registry | registry | privatelink.azurecr.io |
| Cosmos DB (SQL) | Sql | privatelink.documents.azure.com |
| Azure Cache for Redis | redisCache | privatelink.redis.cache.windows.net |
| Data Factory | dataFactory | privatelink.datafactory.azure.net |
| API Management | Gateway | privatelink.azure-api.net |
| Event Hub | namespace | privatelink.servicebus.windows.net |
| Service Bus | namespace | privatelink.servicebus.windows.net |
| Monitor (AMPLS) | ⚠️ Complex configuration — see below | ⚠️ Multiple DNS Zones required — see below |
ADLS Gen2 Note: When
isHnsEnabled: true, bothblobanddfsPEs are required.
- With only the
blobPE, Blob API works, but Data Lake operations (file system creation, directory manipulation,abfss://protocol) will fail.- DFS PE: groupId
dfs, DNS Zoneprivatelink.dfs.core.windows.net⚠️ Azure Monitor Private Link (AMPLS) Note: Azure Monitor cannot be configured with a single PE + single DNS Zone. It connects through Azure Monitor Private Link Scope (AMPLS), and all 5 DNS Zones are required:
privatelink.monitor.azure.comprivatelink.oms.opinsights.azure.comprivatelink.ods.opinsights.azure.comprivatelink.agentsvc.azure-automation.netprivatelink.blob.core.windows.net(for Log Analytics data ingestion)This mapping is complex and subject to change, so always fetch and verify MS Docs when configuring Monitor PE: https://learn.microsoft.com/en-us/azure/azure-monitor/logs/private-link-configure (opens in a new tab)
| Item | ❌ Incorrect Example | ✅ Correct Example |
|---|---|---|
| ADLS Gen2 HNS | isHnsEnabled omitted or false | isHnsEnabled: true |
| PE Subnet | Policy not set | privateEndpointNetworkPolicies: 'Disabled' |
| DNS Zone Group | Only PE created | PE + DNS Zone + VNet Link + DNS Zone Group |
| Foundry resource | kind: 'OpenAI' | kind: 'AIServices' + allowProjectManagement: true |
| Foundry resource | customSubDomainName omitted | customSubDomainName: foundryName — Cannot change after creation |
| Foundry Project | Only Foundry exists without Project | Must create as a set |
| Key Vault auth | Access Policy | enableRbacAuthorization: true |
| Public network | Not configured | publicNetworkAccess: 'Disabled' |
| Storage name | st-my-storage | stmystorage or st${uniqueString(...)} |
| API version | Copied from previous conversation/error | Verify latest stable from MS Docs |
| Region | Hardcoded ('eastus') | Pass as parameter (param location) |
| Sensitive values | Plaintext in .bicepparam | @secure() + Key Vault reference |
Described as default selection rules rather than absolute determinations.
Default rules:
├─ AI/RAG workloads → Use Microsoft Foundry (kind: 'AIServices')
│ ├─ Create Foundry resource + Foundry Project as a set
│ └─ Model deployment is performed at the Foundry resource level (accounts/deployments)
│
├─ ML/open-source model training needed → Consider AI Hub (MachineLearningServices)
│ └─ Only when the user explicitly requests it or features not supported in Foundry are needed
│
└─ Standalone Azure OpenAI resource →
Consider only when the user explicitly requests it or
official documentation requires a separate resourceThese rules are a default selection guide reflecting current MS recommendations. Azure product relationships can change, so check MS Docs when uncertain.
Default rules:
├─ Foundry (AIServices) → Application Insights not required
└─ AI Hub (MachineLearningServices) → Application Insights + Log Analytics required