awesome-copilot/skills/azure-architecture-autopilot/references/service-gotchas.md

Service Gotchas (Stable)

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.

---

1. Required Properties (Deployment Failure or Functional Issues If Omitted)

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

---

2. PE groupId & DNS Zone Mapping (Key Services)

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, both blob and dfs PEs are required.

• With only the blob PE, Blob API works, but Data Lake operations (file system creation, directory manipulation, abfss:// protocol) will fail.
• DFS PE: groupId dfs, DNS Zone privatelink.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.com
• privatelink.oms.opinsights.azure.com
• privatelink.ods.opinsights.azure.com
• privatelink.agentsvc.azure-automation.net
• privatelink.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

---

3. Common Mistakes Checklist

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

---

4. Service Relationship Decision Rules

Described as default selection rules rather than absolute determinations.

Foundry vs Azure OpenAI vs AI Hub

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 resource

These rules are a default selection guide reflecting current MS recommendations. Azure product relationships can change, so check MS Docs when uncertain.

Monitoring

Default rules:
├─ Foundry (AIServices) → Application Insights not required
└─ AI Hub (MachineLearningServices) → Application Insights + Log Analytics required