mirror of
https://github.com/github/awesome-copilot.git
synced 2026-04-13 03:35:55 +00:00
3e01810473
* Add azure-architecture-autopilot skill E2E Azure infrastructure automation skill: - Natural language → Architecture diagram → Bicep → Deploy - 70+ service types with 605+ official Azure icons - Interactive HTML diagrams (drag, zoom, click, PNG export) - Scans existing resources or designs new architecture - Modular Bicep with RBAC, Private Endpoints, DNS - Multi-language support (auto-detects user language) - Zero dependencies (diagram engine embedded) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix generator.py import for flat scripts/ structure + sync README Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: whoniiii <whoniiii@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
114 lines
6.4 KiB
Markdown
114 lines
6.4 KiB
Markdown
# 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
|
|
```
|