← All packs

skill pack
Microsoft Azure
Microsoft's skills for deploying, securing and operating workloads on Azure.
35 skills by Microsoft · microsoft/azure-skills · MIT licence · checked on 18 Nov 2026
airunway-aks-setupSet up AI Runway on AKS — from bare cluster to running model. Covers cluster verification, controller install, GPU assessment, provider setup, and first deployment. WHEN: \"setup AI Runway\", \"onboard AKS cluster\", \"install AI Runway\", \"airunway setup\", \"deploy model to AKS\", \"GPU inference on AKS\", \"KAITO setup on AKS\", \"run LLM on AKS\", \"vLLM on AKS\", \"set up model serving on AKS\", \"AI Runway controller\".ReadClose
--- name: airunway-aks-setup description: "Set up AI Runway on AKS — from bare cluster to running model. Covers cluster verification, controller install, GPU assessment, provider setup, and first deployment. WHEN: \"setup AI Runway\", \"onboard AKS cluster\", \"install AI Runway\", \"airunway setup\", \"deploy model to AKS\", \"GPU inference on AKS\", \"KAITO setup on AKS\", \"run LLM on AKS\", \"vLLM on AKS\", \"set up model serving on AKS\", \"AI Runway controller\"." license: MIT metadata: author: Microsoft version: "1.1.2" argument-hint: "[skip-to-step N]" --- # AI Runway AKS Setup This skill walks users from a bare Kubernetes cluster to a running AI model deployment. Follow each step in sequence unless the user provides `skip-to-step N` to resume from a specific phase. > **Cost awareness:** GPU node pools incur significant compute charges (A100-80GB can cost $3–5+/hr). Confirm the user understands cost implications before provisioning GPU resources. ## Prerequisites This skill assumes an AKS cluster already exists. If the user does not have a cluster, hand off to the `azure-kubernetes` skill first to provision one (with a GPU node pool unless CPU-only inference is acceptable), then return here. ## Quick Reference | Property | Value | |----------|-------| | Best for | End-to-end AI Runway onboarding on AKS | | CLI tools | `kubectl`, `make`, `curl` | | MCP tools | None | | Related skills | `azure-kubernetes` (cluster setup), `azure-diagnostics` (baseline troubleshooting), optional `aks-gpu-inference` (existing GPU/inference Day-2 incidents only) | ## When to Use This Skill Use this skill when the user wants to: - Set up AI Runway on an existing AKS cluster from scratch - Install the AI Runway controller and CRDs - Assess GPU hardware compatibility for model deployment - Choose and install an inference provider (KAITO, Dynamo, KubeRay) - Deploy their first AI model to AKS via AI Runway - Resume a partially-complete AI Runway setup from a specific step ## GPU setup versus Day-2 incidents Keep initial GPU node-pool, provider, controller, and model setup in this skill. For an incident affecting an existing GPU or inference deployment, load [optional-gpu-day2.md](references/optional-gpu-day2.md) before deciding whether to offer the focused optional add-on. ## MCP Tools This skill uses no MCP tools. All cluster operations are performed directly via `kubectl` and `make`. ## Rules 1. Execute steps in sequence — load the reference for each step as you reach it 2. Report cluster state at each step: ✓ healthy, ✗ missing/failed 3. Ask for user confirmation before any install or deployment action 4. If a step is already complete, report status and skip to the next step 5. If the user provides `skip-to-step N`, start at step N; assume prior steps are complete ## Steps | # | Step | Reference | |---|------|-----------| | 1 | **Cluster Verification** — context check, node inventory, GPU detection | [step-1-verify.md](references/steps/step-1-verify.md) | | 2 | **Controller Installation** — CRD + controller deployment | [step-2-controller.md](references/steps/step-2-controller.md) | | 3 | **GPU Assessment** — detect GPU models, flag dtype/attention constraints | [step-3-gpu.md](references/steps/step-3-gpu.md) | | 4 | **Provider Setup** — recommend and install inference provider | [step-4-provider.md](references/steps/step-4-provider.md) | | 5 | **First Deployment** — pick a model, deploy, verify Ready | [step-5-deploy.md](references/steps/step-5-deploy.md) | | 6 | **Summary** — recap, smoke test, next steps | [step-6-summary.md](references/steps/step-6-summary.md) | ## Error Handling | Error / Symptom | Likely Cause | Remediation | |-----------------|--------------|-------------| | No kubeconfig context | Not connected to a cluster | Run `az aks get-credentials` or equivalent | | Controller in CrashLoopBackOff | Config or RBAC issue | `kubectl logs -n airunway-system -l control-plane=controller-manager --previous` | | Provider not ready | Image pull or RBAC issue | `kubectl logs <pod-name> -n <namespace>` for the provider pod | | ModelDeployment stuck in Pending | GPU scheduling failure or provider not ready | `kubectl describe modeldeployment <name> -n <namespace>` events | | `bfloat16` errors at inference | T4 or V100 lacks bfloat16 support | Add `--dtype float16` to serving args | For full error handling and rollback procedures, see [troubleshooting.md](references/troubleshooting.md).
Original on GitHubappinsights-instrumentationGuidance for instrumenting webapps with Azure Application Insights. Provides telemetry patterns, SDK setup, and configuration references. WHEN: how to instrument app, App Insights SDK, telemetry patterns, what is App Insights, Application Insights guidance, instrumentation examples, APM best practices.ReadClose
--- name: appinsights-instrumentation description: "Guidance for instrumenting webapps with Azure Application Insights. Provides telemetry patterns, SDK setup, and configuration references. WHEN: how to instrument app, App Insights SDK, telemetry patterns, what is App Insights, Application Insights guidance, instrumentation examples, APM best practices." license: MIT metadata: author: Microsoft version: "1.2.2" --- # AppInsights Instrumentation Guide This skill provides **guidance and reference material** for instrumenting webapps with Azure Application Insights. > **⛔ ADDING COMPONENTS?** > > If the user wants to **add App Insights to their app**, invoke **azure-prepare** instead. > This skill provides reference material—azure-prepare orchestrates the actual changes. ## When to Use This Skill - User asks **how** to instrument (guidance, patterns, examples) - User needs SDK setup instructions - azure-prepare invokes this skill during research phase - User wants to understand App Insights concepts ## When to Use azure-prepare Instead - User says "add telemetry to my app" - User says "add App Insights" - User wants to modify their project - Any request to change/add components ## Prerequisites The app in the workspace must be one of these kinds - An ASP.NET Core app hosted in Azure - An Azure Container App - A Node.js app hosted in Azure - A Python app hosted in Azure ## Guidelines ### Collect context information Find out the (programming language, application framework, hosting) tuple of the application the user is trying to add telemetry support in. This determines how the application can be instrumented. Read the source code to make an educated guess. Confirm with the user on anything you don't know. You must always ask the user where the application is hosted (e.g. on a personal computer, in an Azure App Service as code, in an Azure App Service as container, in an Azure Container App, etc.). ### Prefer auto-instrument if possible If the app is a C# ASP.NET Core app hosted in Azure App Service, use [AUTO guide](references/auto.md) to help user auto-instrument the app. ### Manually instrument Manually instrument the app by creating the AppInsights resource and update the app's code. #### Create AppInsights resource Use one of the following options that fits the environment. - Add AppInsights to existing Bicep template. See [examples/appinsights.bicep](examples/appinsights.bicep) for what to add. This is the best option if there are existing Bicep template files in the workspace. - Use Azure CLI. See [scripts/appinsights.ps1](scripts/appinsights.ps1) for what Azure CLI command to execute to create the App Insights resource. No matter which option you choose, recommend the user to create the App Insights resource in a meaningful resource group that makes managing resources easier. A good candidate will be the same resource group that contains the resources for the hosted app in Azure. #### Modify application code - If the app is an ASP.NET Core app, see [ASPNETCORE guide](references/aspnetcore.md) for how to modify the C# code. - If the app is a Node.js app, see [NODEJS guide](references/nodejs.md) for how to modify the JavaScript/TypeScript code. - If the app is a Python app, see [PYTHON guide](references/python.md) for how to modify the Python code. ## SDK Quick References - **OpenTelemetry Distro**: [Python](references/sdk/azure-monitor-opentelemetry-py.md) | [TypeScript](references/sdk/azure-monitor-opentelemetry-ts.md) - **OpenTelemetry Exporter**: [Python](references/sdk/azure-monitor-opentelemetry-exporter-py.md) | [Java](references/sdk/azure-monitor-opentelemetry-exporter-java.md) ## Platform-Specific Guides - **Container Apps**: [Observability Guide](references/container-apps.md)
Original on GitHubazure-aiBuild and troubleshoot Azure AI Search, Speech, OpenAI, and Document Intelligence apps. WHEN: AI Search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, fast or batch transcription, Speech SDK logs, session ID, result ID, OCR.ReadClose
--- name: azure-ai description: "Build and troubleshoot Azure AI Search, Speech, OpenAI, and Document Intelligence apps. WHEN: AI Search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, fast or batch transcription, Speech SDK logs, session ID, result ID, OCR." license: MIT metadata: author: Microsoft version: "1.2.4" --- # Azure AI Services ## Scope and Handoffs | Request Scope | Route To | |---------------|----------| | Foundry projects, agents (Prompt/Hosted/Voice), model deployments, fine-tuning, quota, RBAC, Foundry VNet | `microsoft-foundry` | | Classic AI Search, Speech SDK/REST/batch, Document Intelligence, OpenAI SDK | Stay in `azure-ai` | ## Services and Diagnostic Workflows Read the matching reference before diagnosing errors, validating local inputs, or collecting support evidence: | Service | MCP / CLI | Preflight & Diagnostics | |---------|-----------|-------------------------| | **AI Search** (full-text, vector, hybrid, semantic search) | `azure__search` (`search_index_list`, `search_index_get`, `search_query`), `az search` | [Python](references/sdk/azure-search-documents-py.md) \| [TypeScript](references/sdk/azure-search-documents-ts.md) \| [.NET](references/sdk/azure-search-documents-dotnet.md) | | **Speech** (STT, TTS, Fast/Batch Transcription, Batch Synthesis, SDK logs) | `azure__speech` (`speech_transcribe`, `speech_synthesize`), `az cognitiveservices` | [Speech SDK client diagnostics](references/speech/diagnostics.md) \| [Audio & REST/batch preflight](references/speech/transcription-and-audio-preflight.md) | | **Document Intelligence** (form extraction, layout, OCR) | `az cognitiveservices` | [.NET](references/sdk/azure-ai-document-intelligence-dotnet.md) \| [TypeScript](references/sdk/azure-ai-document-intelligence-ts.md) | | **OpenAI** (direct SDK/API usage) | `az cognitiveservices` | [.NET SDK](references/sdk/azure-ai-openai-dotnet.md) | **If Azure MCP is not enabled:** In Copilot CLI or Claude Code, ask the user to run `/mcp` and enable Azure MCP; in other hosts, ask the user to enable Azure MCP through the host's MCP configuration. Offline local preflight scripts do not require Azure MCP or Azure sign-in. For keyless authentication patterns across Azure AI SDKs, read [Azure Authentication Best Practices](references/auth-best-practices.md). ## SDK Quick References - **AI Search**: [Python](references/sdk/azure-search-documents-py.md) | [TypeScript](references/sdk/azure-search-documents-ts.md) | [.NET](references/sdk/azure-search-documents-dotnet.md) - **OpenAI**: [.NET](references/sdk/azure-ai-openai-dotnet.md) - **Vision**: [Python](references/sdk/azure-ai-vision-imageanalysis-py.md) | [Java](references/sdk/azure-ai-vision-imageanalysis-java.md) - **Transcription**: [Python](references/sdk/azure-ai-transcription-py.md) - **Translation**: [Python](references/sdk/azure-ai-translation-text-py.md) | [TypeScript](references/sdk/azure-ai-translation-ts.md) - **Document Intelligence**: [.NET](references/sdk/azure-ai-document-intelligence-dotnet.md) | [TypeScript](references/sdk/azure-ai-document-intelligence-ts.md) - **Content Safety**: [Python](references/sdk/azure-ai-contentsafety-py.md) | [TypeScript](references/sdk/azure-ai-contentsafety-ts.md) | [Java](references/sdk/azure-ai-contentsafety-java.md) ## Service Documentation - [Azure AI Search documentation](https://learn.microsoft.com/azure/search/search-what-is-azure-search) - [Azure AI Speech documentation](https://learn.microsoft.com/azure/ai-services/speech-service/overview)
Original on GitHubazure-aigatewayConfigure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: semantic caching, token limit, content safety, load balancing, AI model governance, MCP rate limiting, jailbreak detection, add Azure OpenAI backend, add AI Foundry model, test AI gateway, LLM policies, configure AI backend, token metrics, AI cost control, convert API to MCP, import OpenAPI to gateway.ReadClose
--- name: azure-aigateway description: "Configure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: semantic caching, token limit, content safety, load balancing, AI model governance, MCP rate limiting, jailbreak detection, add Azure OpenAI backend, add AI Foundry model, test AI gateway, LLM policies, configure AI backend, token metrics, AI cost control, convert API to MCP, import OpenAPI to gateway." license: MIT metadata: author: Microsoft version: "3.2.1" compatibility: Requires Azure CLI (az) for configuration and testing --- # Azure AI Gateway Configure Azure API Management (APIM) as an AI Gateway for governing AI models, MCP tools, and agents. > **To deploy APIM**, use the **azure-prepare** skill. See [APIM deployment guide](https://learn.microsoft.com/azure/api-management/get-started-create-service-instance). ## When to Use This Skill | Category | Triggers | |----------|----------| | **Model Governance** | "semantic caching", "token limits", "load balance AI", "track token usage" | | **Tool Governance** | "rate limit MCP", "protect my tools", "configure my tool", "convert API to MCP" | | **Agent Governance** | "content safety", "jailbreak detection", "filter harmful content" | | **Configuration** | "add Azure OpenAI backend", "configure my model", "add AI Foundry model" | | **Testing** | "test AI gateway", "call OpenAI through gateway" | --- ## Quick Reference | Policy | Purpose | Details | |--------|---------|---------| | `azure-openai-token-limit` | Cost control | [Model Policies](references/policies.md#token-rate-limiting) | | `azure-openai-semantic-cache-lookup/store` | 60-80% cost savings | [Model Policies](references/policies.md#semantic-caching) | | `azure-openai-emit-token-metric` | Observability | [Model Policies](references/policies.md#token-metrics) | | `llm-content-safety` | Safety & compliance | [Agent Policies](references/policies.md#content-safety) | | `rate-limit-by-key` | MCP/tool protection | [Tool Policies](references/policies.md#request-rate-limiting) | --- ## Get Gateway Details ```bash # Get gateway URL az apim show --name <apim-name> --resource-group <rg> --query "gatewayUrl" -o tsv # List backends (AI models) az apim backend list --service-name <apim-name> --resource-group <rg> \ --query "[].{id:name, url:url}" -o table # Get subscription key az apim subscription keys list \ --service-name <apim-name> --resource-group <rg> --subscription-id <sub-id> ``` --- ## Test AI Endpoint ```bash GATEWAY_URL=$(az apim show --name <apim-name> --resource-group <rg> --query "gatewayUrl" -o tsv) curl -X POST "${GATEWAY_URL}/openai/deployments/<deployment>/chat/completions?api-version=2024-02-01" \ -H "Content-Type: application/json" \ -H "Ocp-Apim-Subscription-Key: <key>" \ -d '{"messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}' ``` --- ## Common Tasks ### Add AI Backend See [references/patterns.md](references/patterns.md#pattern-1-add-ai-model-backend) for full steps. ```bash # Discover AI resources az cognitiveservices account list --query "[?kind=='OpenAI']" -o table # Create backend az apim backend create --service-name <apim> --resource-group <rg> \ --backend-id openai-backend --protocol http --url "https://<aoai>.openai.azure.com/openai" # Grant access (managed identity) az role assignment create --assignee <apim-principal-id> \ --role "Cognitive Services User" --scope <aoai-resource-id> ``` ### Apply AI Governance Policy Recommended policy order in `<inbound>`: 1. **Authentication** - Managed identity to backend 2. **Semantic Cache Lookup** - Check cache before calling AI 3. **Token Limits** - Cost control 4. **Content Safety** - Filter harmful content 5. **Backend Selection** - Load balancing 6. **Metrics** - Token usage tracking See [references/policies.md](references/policies.md#combining-policies) for complete example. --- ## Troubleshooting | Issue | Solution | |-------|----------| | Token limit 429 | Increase `tokens-per-minute` or add load balancing | | No cache hits | Lower `score-threshold` to 0.7 | | Content false positives | Increase category thresholds (5-6) | | Backend auth 401 | Grant APIM "Cognitive Services User" role | See [references/troubleshooting.md](references/troubleshooting.md) for details. --- ## References - [**Detailed Policies**](references/policies.md) - Full policy examples - [**Configuration Patterns**](references/patterns.md) - Step-by-step patterns - [**Troubleshooting**](references/troubleshooting.md) - Common issues - [AI-Gateway Samples](https://github.com/Azure-Samples/AI-Gateway) - [GenAI Gateway Docs](https://learn.microsoft.com/azure/api-management/genai-gateway-capabilities) ## SDK Quick References - **Content Safety**: [Python](references/sdk/azure-ai-contentsafety-py.md) | [TypeScript](references/sdk/azure-ai-contentsafety-ts.md) - **API Management**: [Python](references/sdk/azure-mgmt-apimanagement-py.md) | [.NET](references/sdk/azure-mgmt-apimanagement-dotnet.md)Original on GitHubazure-app-onboardEnd-to-end orchestrator: from a business idea, app idea, or existing app to running Azure deployment with cost estimates and pre-deploy approval. Analyzes your app, auto-detects the right Azure services, scaffolds infrastructure code, and deploys — tailored to your app, not a template. Handles moving existing apps to Azure without rewriting or with minimal changes. WHEN: bring your app to Azure, plan my app, cost to run, is my code ready to deploy, deploy my app to the cloud, deploy all my services, what Azure services do I need, plan my Azure deployment, deploy my new app to Azure, one-click deploy, I have an app and want it on Azure, migrate my app to Azure, help me get started, build an app, no code yet, starter project. DO NOT USE FOR: use azd for deployment(use azure-deploy), optimizing existing costs (use cost-optimization), code readiness checks only (use azure-app-onboard-prereq).ReadClose
--- name: azure-app-onboard description: "End-to-end orchestrator: from a business idea, app idea, or existing app to running Azure deployment with cost estimates and pre-deploy approval. Analyzes your app, auto-detects the right Azure services, scaffolds infrastructure code, and deploys — tailored to your app, not a template. Handles moving existing apps to Azure without rewriting or with minimal changes. WHEN: bring your app to Azure, plan my app, cost to run, is my code ready to deploy, deploy my app to the cloud, deploy all my services, what Azure services do I need, plan my Azure deployment, deploy my new app to Azure, one-click deploy, I have an app and want it on Azure, migrate my app to Azure, help me get started, build an app, no code yet, starter project. DO NOT USE FOR: use azd for deployment(use azure-deploy), optimizing existing costs (use cost-optimization), code readiness checks only (use azure-app-onboard-prereq)." license: MIT metadata: author: Microsoft version: "1.2.9" --- # Azure App Onboard > ⛔ **Every repo goes through the full pipeline (Steps 1–10). No exceptions.** Do not skip steps, refuse, or short-circuit based on what you recognize. Follow the Workflow table below sequentially — read each step's references before acting. ## Quick Reference | Property | Value | |----------|-------| | Best for | Developers who know what to build but not which Azure services to use | | Inputs | Business idea or existing codebase, budget/scale preferences (optional) | | Outputs | Architecture plan, cost estimate, IaC files, deployed Azure resources | | Phases | Discover → Architect → Scaffold → Deploy (self-contained, no external skill calls) | ## When to Use This Skill - Deploy existing code without knowing which Azure services to use - Check if your existing code is ready to deploy to Azure - Move an existing app to Azure without rewriting or with minimal changes - Get cost estimates before committing to infrastructure - Understand architecture decisions and rejected alternatives - Get answers to Azure architecture or service selection questions (e.g., "What database should I use?") - Get guided Azure onboarding without prior experience ## When NOT to Use | Scenario | Use Instead | |----------|-------------| | Run `azd up` or execute an existing deployment | `azure-deploy` | | Optimize existing Azure spend | `cost-optimization` from the optional `azure-cost` plugin | | Generate Bicep/Terraform for a known architecture | `azure-prepare` | | Validate infrastructure or run preflight checks | `azure-validate` | | Troubleshoot a running Azure deployment | `azure-diagnostics` | | Deploy to or manage AKS/Kubernetes directly | `azure-kubernetes` | | Look up or list existing Azure resources | `azure-resource-lookup` | If `cost-optimization` is unavailable, explain that it is provided by the optional `azure-cost` plugin and direct the user to their client's supported plugin installation flow; do not imply the handoff completed. ## Pipeline Rules > ⛔ **You MUST read [`references/pipeline-rules.md`](references/pipeline-rules.md) at the start of every AppOnboard session.** It contains approval gates, phase lifecycle, session artifacts, deploy-as-is, and security baseline rules. ## Workflow > ⛔ **Deploy recovery:** After deploy gate approval OR before any `az deployment`/`az webapp deploy`/`az acr build` — if you haven't read `deploy/PHASE.md`, read `.copilot-azure/sessions/{id}/deploy-checklist.md` first, then `deploy/PHASE.md`. ⛔ NEVER invoke `{"skill": "azure-deploy"}` — that is a DIFFERENT skill for a DIFFERENT workflow. > ⛔ **Post-scaffold transition (MANDATORY):** Immediately after `scaffold-manifest.json` is written, YOUR NEXT ACTION MUST be Step 8 (Deploy Approval Gate) — NOT a summary report, NOT a "here are the generated files" message, NOT a completion signal. Confirm `context.json` has `completedPhases: [...,"scaffold"]` + `currentPhase: "deploy"` (update it yourself if the scaffold subagent didn't). Re-read [approval-gates.md § Deploy Gate](references/approval-gates.md) if evicted from context (scaffold reference loading is heavy), then present the exact prompt: **"🚀 Ready to deploy? (Yes / Run manually / Edit plan / Cancel)"**. This gate is the LAST content in your response — wait for the user's reply. | # | Step | Action | Reference | |---|------|--------|-----------| | 1 | **Session check + Azure login** | Create/resume session, verify Azure CLI auth, resolve subscription + user identity | ⛔ **You MUST read [session-protocol.md](references/session-protocol.md)** | | 2 | **Scope triage** | Check azd markers, triage question. Empty workspace or code-only (no infra) → Step 3 directly. | ⛔ Read [intent-gathering.md](references/intent-gathering.md) § Scope Triage | | 3 | **Prereq scan** | ⛔ Skip if `completedPhases` includes `"prereq"`. Otherwise: invoke `{"skill": "azure-app-onboard-prereq"}`. Write `prereq-output.json`, update `context.json`. **Halt if:** `overallHealth: "blocked"` OR `routeToSkill` set. | | | 4 | **Gather intent** | Present prereq results, confirm stack + Azure services, ask remaining questions. | ⛔ Read [intent-gathering.md](references/intent-gathering.md) § After Prereq Returns | | 5 | **Plan architecture** | Write `prepare-plan.json`. | ⛔ **You MUST read [prepare/PHASE.md](prepare/PHASE.md)** | | 6 | **Scaffold approval gate** | Display plan for user approval BEFORE generating any files. | ⛔ Read [approval-gates.md](references/approval-gates.md) § Scaffold Gate | | 7 | **Scaffold** | Generate IaC, self-review. Write `scaffold-manifest.json`. Update `context.json`. | ⛔ **You MUST read [scaffold/PHASE.md](scaffold/PHASE.md)** | | 8 | **Deploy approval gate** | Display validation summary. ⛔ After approval: FIRST read deploy-checklist.md → deploy/PHASE.md. NEVER `{"skill": "azure-deploy"}`. | ⛔ Read [approval-gates.md](references/approval-gates.md) § Deploy Gate | | 9 | **Deploy** | Execute IaC, health-check. Write `deploy-result.json`. | ⛔ **You MUST read [deploy/PHASE.md](deploy/PHASE.md)** | | 10 | **Handoff** | Surface deployment identity, cleanup commands, next steps. | ⛔ **You MUST read [`handoff-protocol.md`](references/handoff-protocol.md)** | ## Error Handling | Error | Remediation | |-------|-------------| | Phase fails | Halt, report phase + error. User decides: retry, skip, abort. | | MCP server unavailable | Skip affected checks, add disclaimer to `costEstimate.assumptions[]` and every approval gate. | | Missing RBAC | Report required role + `az role assignment` command. | > **Shared references:** [MCP tools](references/mcp-tool-reference.md) (cross-phase tool parameters) | [IaC resources](references/iac-resources.md) (Azure resource docs for troubleshooting)Original on GitHubazure-app-onboard-prereqAssess whether source code is ready to deploy to Azure — the check BEFORE infrastructure work. Evaluates build health, app completeness, dependencies and local services, stack compatibility, and deployment feasibility. Answers questions about what your app needs before it can be deployed — frameworks, dependencies, and configuration. Checks whether dependencies are compatible and identifies deployment blockers and unsupported frameworks. WHEN: \"evaluate my repo\", \"is my app ready to deploy\", \"what does my app need to deploy\", \"what do I need before deploying\", \"does my app need\", \"can I ship this to Azure\", \"scan my repo for issues\", \"is this app deployable\", \"check if my app is ready for Azure\", \"do I need a Dockerfile\", \"what's blocking my deployment\", \"are there any blockers\", \"are my dependencies compatible\", \"does Azure support my framework\", \"what needs to change before deploying\", \"check my app configuration\".ReadClose
--- name: azure-app-onboard-prereq description: "Assess whether source code is ready to deploy to Azure — the check BEFORE infrastructure work. Evaluates build health, app completeness, dependencies and local services, stack compatibility, and deployment feasibility. Answers questions about what your app needs before it can be deployed — frameworks, dependencies, and configuration. Checks whether dependencies are compatible and identifies deployment blockers and unsupported frameworks. WHEN: \"evaluate my repo\", \"is my app ready to deploy\", \"what does my app need to deploy\", \"what do I need before deploying\", \"does my app need\", \"can I ship this to Azure\", \"scan my repo for issues\", \"is this app deployable\", \"check if my app is ready for Azure\", \"do I need a Dockerfile\", \"what's blocking my deployment\", \"are there any blockers\", \"are my dependencies compatible\", \"does Azure support my framework\", \"what needs to change before deploying\", \"check my app configuration\"." license: MIT metadata: author: Microsoft version: "1.2.5" --- # Azure App Onboard Prereq — Repository Evaluation Evaluate a user's repository for build health, app completeness, and Azure deployment feasibility — before infrastructure planning. Produces per-component verdicts (PASS/WARN/FAIL) consumed by downstream phases. > **Orchestrator relationship:** Called by `azure-app-onboard` at Step 3, or standalone for code readiness checks. When called by orchestrator, return control to `azure-app-onboard` after writing artifacts — do NOT invoke downstream phases directly. Phase 1 of 4 in AppOnboard pipeline. Session: `.copilot-azure/sessions/{session-id}/`. Reads `context.json`. Writes `components[]`, `repo{}`, `detectedInfra[]`. Produces `prereq-output.json`. Schema: [`prereq-schemas.ts`](references/prereq-schemas.ts) — `PrereqOutput`, `BuildRequirements`. Direct entry supported. ## When NOT to Use | Signal | Redirect | |--------|----------| | Validate infrastructure (Bicep/TF/azure.yaml) | **azure-validate** | | Generate IaC | **azure-prepare** | | End-to-end idea-to-production | **azure-app-onboard** | | Run `azd up` or deploy | **azure-deploy** | ## Rules > ⛔ **ABSOLUTE PROHIBITION — `npm install`, `npm test`, `npx jest`, `pytest`, and ALL install/build/test commands are NEVER allowed.** > Under NO circumstances may you run `npm install`, `npm test`, `npx jest`, `pip install`, `pytest`, `dotnet build`, `dotnet restore`, `dotnet test`, `go mod download`, `cargo build`, or ANY package-manager install, build, or test command during the prereq phase. Do NOT run test suites to verify code — check for test config files statically instead. The prereq phase is read-only evaluation + static-only verification. > **ONLY exception — two sanctioned contexts, both consent-gated:** (a) code the agent **modified** during migration/remediation (see [remediation-protocol.md](references/remediation-protocol.md) step 6), or (b) code the agent **wrote** from scratch on the zero-code path (see [zero-code-path.md](references/zero-code-path.md)). In either case, install/build/test runs ONLY via the user-confirmed build-validation gate ([build-check.md](references/build-check.md) Step 3), after the user answers that specific per-command consent prompt. General prior consent never counts. 1. ⛔ **Full pipeline (Steps 1–8), no exceptions.** All prompts → Step 1 directly. Answer specific questions AS PART OF findings (Step 5), not before. 2. ⛔ **No sub-agents for evaluation.** 3-axis evaluation is inline. **Exception**: zero-code-path scaffolding (Step 2). 3. Code/destructive modifications require `ask_user`. Max 3 questions before results. Direct entry: don't repeat orchestrator's intent questions. ## MCP Tools | Tool | Purpose | |------|---------| | `mcp_azure_mcp_get_azure_bestpractices` | Validate detected stack patterns against Azure best practices | | `mcp_azure_mcp_extension_cli_install` | Check/install required CLI tools (az, azd, func) | ## Workflow ### Step 1: Session Check **Orchestrator entry:** Session exists — read `context.json`, proceed to Step 2. **Direct entry:** Check `.copilot-azure/sessions/active-session.json`: - **Exists** → ⛔ read [session-protocol.md](references/session-protocol.md) for resume/fresh gate. Do NOT proceed until user answers. - **Missing** → create session: generate UUID, `New-Item -ItemType Directory -Path ".copilot-azure/sessions/{uuid}" -Force`, write `context.json` + `active-session.json` via `create` tool. Then: `az account show` → merge `{id, name, tenantId}` into `context.json.azure`. ⛔ Session MUST exist on disk before any scanning. ### Step 2: Scan Workspace Scan for project files. Detect components, `repo{}`, `detectedInfra[]`, `detectedServices[]`. Classify Terraform providers. Check CLI availability. Stack detection conflicts: user explicit statement wins (write to `context.json`, mark scan as override); scan-only → confirm with user; multiple stacks → show all and ask (see [component-mapping.md](references/component-mapping.md)); no code → [zero-code-path.md](references/zero-code-path.md). > If no project files, no Dockerfile, AND no index.html → ⛔ read [zero-code-path.md](references/zero-code-path.md). > ⛔ **Cloud SDK early gate.** Grep for `aws-sdk|@aws-sdk|boto3|google-cloud|@google-cloud|firebase`. If functional deps found → read [cloud-sdk-migration.md](references/cloud-sdk-migration.md), then `ask_user`: **"Redirect to Azure Cloud Migrate"** (set `routeToSkill: "azure-cloud-migrate"`) · **"Continue evaluation anyway"** (finish readiness eval + SDK→Azure mapping, then STOP at Step 8 — no plan until the deps are swapped) · **"Cancel"**. ### Step 3: Per-Component Evaluation | Sub-step | Action | Reference | |----------|--------|-----------| | 3.1 | **Build check** | ⛔ **You MUST read [build-check.md](references/build-check.md)** | | 3.2 | **Completeness check** | ⛔ **You MUST read [completeness-check.md](references/completeness-check.md)** | | 3.3 | **Deployability check** | ⛔ **You MUST read [deployability-check.md](references/deployability-check.md)** | | 3.3a | **Component mapping** (conditional) | Read [component-mapping.md](references/component-mapping.md) ONLY IF >1 project manifest found (monorepo) | Populate `buildRequirements` per component after evaluation. Verdict propagation, tier rules, and f1Viable aggregation are in [readiness-gate.md](references/readiness-gate.md) and the individual check references. ### Step 4: Write Artifacts + Readiness Gate ⛔ Verify `context.json` exists on disk. ⛔ **You MUST read [readiness-gate.md](references/readiness-gate.md)** (verdicts, tiers, batch-then-approve, fast-track), then ⛔ **You MUST read [prereq-artifacts.md](references/prereq-artifacts.md)** (write procedures, schemas). ### Step 5: Present Findings Per [readiness-gate.md § Present Findings](references/readiness-gate.md) — show verdicts grouped by severity before proceeding. ### Step 6: Remediation (conditional) ⛔ **You MUST read [remediation-protocol.md](references/remediation-protocol.md)** IF any ❌ FAIL verdict, 🔧 Recommended Fix, or ⚠️ WARN with `fixPhase: "prereq"` exists. Contains remediation loop, static verification, re-eval mandate, post-remediation artifact updates, and the build-validation consent gate. If all verdicts are ✅ PASS or ⚠️ WARN without `fixPhase: "prereq"`, skip to Step 7. ### Step 7: Write Final State `completedPhases` already has `"prereq"` + `currentPhase: null` (from Step 4). Then: > ⛔ **Write `lastScanCommit`.** Run `git rev-parse HEAD` and store the full 40-character SHA as `context.json.repo.lastScanCommit`. Required — staleness guard in Step 1 compares to HEAD on resume to detect changes. ### Step 8: Route ⛔ **Mandatory — do NOT skip this step.** > **Routing fields:** All routing writes `routeToSkill` and `routeReason` to `context.json`. > **Post-remediation context:** If Step 6 ran, lead the routing prompt with: "Remediation complete — {N} issues fixed, your app is now {overallHealth}." > ⛔ **Evaluate rows top to bottom — first match wins.** | # | Condition | Action | |---|-----------|--------| | 1 | `routeToSkill` set (any entry) | `ask_user`: "Redirect to {routeToSkill}" / "Not now". ⛔ Pipeline stops — do NOT proceed to architecture planning. | | 2 | `cloudSdkFindings[]` non-empty (user chose "Continue evaluation anyway") | Present the cloud-SDK → Azure swap mapping as 🔶 blockers, then `ask_user` with this exact prompt: **"🔶 Cloud SDK migration required — these dependencies must be swapped before this app can deploy to Azure. (Redirect to azure-cloud-migrate / Stop — swap manually and re-run)"** — Redirect sets `routeToSkill: "azure-cloud-migrate"`, Stop halts. ⛔ Pipeline stops — do NOT proceed to architecture planning, and do NOT offer a "continue to prepare" option; the app can't deploy until the deps are swapped. | | 3 | Orchestrator + no `routeToSkill` | Tell the user: "✅ Your app has been evaluated and is ready — let's plan your Azure deployment." Then invoke `azure-app-onboard`. ⛔ Do NOT stop, do NOT wait for user input, do NOT narrate internal handoffs. The user already consented to the full pipeline at scope triage. | | 4 | Direct + ready/readyWithCaveats + no Azure infra | `ask_user`: "Deploy to Azure (full pipeline)" → invoke `azure-app-onboard` / "Not now" | | 5 | Direct + ready/readyWithCaveats + existing Azure infra | `ask_user`: "Start fresh" → invoke `azure-app-onboard` / "Use existing infra" → invoke `azure-prepare` / "Not now" | | 6 | Direct + blocked | Report blocker summary + "Fix and re-run." | Severity tiers (🛑🔶❌🔧⚠️✅) are defined in [readiness-gate.md](references/readiness-gate.md). ## Outputs | Artifact | Location | Consumer | |----------|----------|----------| | Session context | `context.json` → `components[]`, `repo{}`, `detectedInfra[]`, `detectedServices[]` | All downstream phases | | Prereq output | `prereq-output.json` | prepare phase (via `azure-app-onboard`) | | Readiness report | `.copilot-azure/sessions/{uuid}/readiness-report.md` | User (offline reference) |Original on GitHubazure-cloud-migrateAssess and migrate cross-cloud workloads to Azure with reports and code conversion. Supports Lambda→Functions, Beanstalk/Heroku/App Engine→App Service, Fargate/Kubernetes/Cloud Run/Spring Boot→Container Apps. WHEN: migrate Lambda to Functions, AWS to Azure, migrate Beanstalk, migrate Heroku, migrate App Engine, Cloud Run migration, Fargate to ACA, ECS/Kubernetes/GKE/EKS to Container Apps, Spring Boot to Container Apps, cross-cloud migration.ReadClose
--- name: azure-cloud-migrate description: "Assess and migrate cross-cloud workloads to Azure with reports and code conversion. Supports Lambda→Functions, Beanstalk/Heroku/App Engine→App Service, Fargate/Kubernetes/Cloud Run/Spring Boot→Container Apps. WHEN: migrate Lambda to Functions, AWS to Azure, migrate Beanstalk, migrate Heroku, migrate App Engine, Cloud Run migration, Fargate to ACA, ECS/Kubernetes/GKE/EKS to Container Apps, Spring Boot to Container Apps, cross-cloud migration." license: MIT metadata: author: Microsoft version: "1.3.3" --- # Azure Cloud Migrate > This skill handles **assessment and code migration** of existing cloud workloads to Azure. ## Rules 1. Follow phases sequentially — do not skip 2. Generate assessment before any code migration 3. Load the scenario reference and follow its rules 4. Use `mcp_azure_mcp_get_azure_bestpractices` and `mcp_azure_mcp_documentation` MCP tools 5. Use the latest supported runtime for the target service 6. Destructive actions require `ask_user` — [functions global-rules](references/services/functions/global-rules.md) | [app-service global-rules](references/services/app-service/global-rules.md) 7. **Report progress to user** — During long-running operations (deployments, image pushes), provide resource-level status updates so the user is never left waiting without feedback — see [workflow-details.md](references/workflow-details.md) 8. **Audit service discovery in app code** — Kubernetes DNS names (e.g., `http://order-service:3001`) do not resolve in Container Apps. During assessment, scan source code for hardcoded hostnames/ports in HTTP clients and flag them for env-var-driven URL injection ## Migration Scenarios | Source | Target | Reference | |--------|--------|-----------| | AWS Lambda | Azure Functions | [lambda-to-functions.md](references/services/functions/lambda-to-functions.md) ([assessment](references/services/functions/assessment.md), [code-migration](references/services/functions/code-migration.md)) | | AWS Elastic Beanstalk | Azure App Service | [beanstalk-to-app-service.md](references/services/app-service/beanstalk-to-app-service.md) | | Heroku | Azure App Service | [heroku-to-app-service.md](references/services/app-service/heroku-to-app-service.md) | | Google App Engine | Azure App Service | [app-engine-to-app-service.md](references/services/app-service/app-engine-to-app-service.md) | | AWS Fargate (ECS) | Azure Container Apps | [fargate-to-container-apps.md](references/services/container-apps/fargate-to-container-apps.md) ([assessment](references/services/container-apps/fargate-assessment-guide.md), [deployment](references/services/container-apps/fargate-deployment-guide.md)) | | Kubernetes (GKE/EKS/Self-hosted) | Azure Container Apps | [k8s-to-container-apps.md](references/services/container-apps/k8s-to-container-apps.md) | | GCP Cloud Run | Azure Container Apps | [cloudrun-to-container-apps.md](references/services/container-apps/cloudrun-to-container-apps.md) | | Spring Boot (Azure Spring Apps/VMs) | Azure Container Apps | [spring-apps-to-aca.md](references/services/container-apps/spring-apps-to-aca.md) | > No matching scenario? Use `mcp_azure_mcp_documentation` and `mcp_azure_mcp_get_azure_bestpractices` tools. ## Output Directory All output goes to `<workspace-root-basename>-azure/` at workspace root, where `<workspace-root-basename>` is the name of the top-level workspace directory itself (NOT a subdirectory within it). Never modify the source directory. ## Steps 1. **Create** `<workspace-root-basename>-azure/` at workspace root 2. **Assess** — Analyze source, map services, generate report using the scenario-specific assessment guide → [functions assessment](references/services/functions/assessment.md) | [app-service assessment](references/services/app-service/assessment.md) 3. **Migrate** — Convert code/config using the scenario-specific migration guide → [functions code-migration](references/services/functions/code-migration.md) | [app-service code-migration](references/services/app-service/code-migration.md) 4. **Ask User** — "Migration complete. Test locally or deploy to Azure?" 5. **Hand off** to azure-prepare for infrastructure, testing, and deployment Track progress in `migration-status.md` — see [workflow-details.md](references/workflow-details.md).
Original on GitHubazure-complianceRun Azure compliance and security audits with azqr plus Key Vault expiration checks. Covers best-practice assessment, resource review, policy/compliance validation, and security posture checks. WHEN: compliance scan, security audit, BEFORE running azqr (compliance cli tool), Azure best practices, Key Vault expiration check, expired certificates, expiring secrets, orphaned resources, compliance assessment.ReadClose
--- name: azure-compliance description: "Run Azure compliance and security audits with azqr plus Key Vault expiration checks. Covers best-practice assessment, resource review, policy/compliance validation, and security posture checks. WHEN: compliance scan, security audit, BEFORE running azqr (compliance cli tool), Azure best practices, Key Vault expiration check, expired certificates, expiring secrets, orphaned resources, compliance assessment." license: MIT metadata: author: Microsoft version: "1.2.3" --- # Azure Compliance & Security Auditing ## Quick Reference | Property | Details | |---|---| | Best for | Compliance scans, security audits, Key Vault expiration checks | | Primary capabilities | Comprehensive Resources Assessment, Key Vault Expiration Monitoring | | MCP tools | azqr, subscription and resource group listing, Key Vault item inspection | ## Prerequisites - Authentication: user is logged in to Azure via `az login` - Permissions to read resource configuration and Key Vault metadata ## Assessments | Assessment | Reference | |------------|-----------| | Comprehensive Compliance (azqr) | [references/azure-quick-review.md](references/azure-quick-review.md) | | Key Vault Expiration | [references/azure-keyvault-expiration-audit.md](references/azure-keyvault-expiration-audit.md) | | Resource Graph Queries | [references/azure-resource-graph.md](references/azure-resource-graph.md) | ## MCP Tools | Tool | Purpose | |------|---------| | `mcp_azure_mcp_extension_azqr` | Run azqr compliance scans | | `mcp_azure_mcp_subscription_list` | List available subscriptions | | `mcp_azure_mcp_group_list` | List resource groups | | `keyvault_key_list` | List all keys in vault | | `keyvault_key_get` | Get key details including expiration | | `keyvault_secret_list` | List all secrets in vault | | `keyvault_secret_get` | Get secret details including expiration | | `keyvault_certificate_list` | List all certificates in vault | | `keyvault_certificate_get` | Get certificate details including expiration | ## Assessment Workflow 1. Select scope (subscription or resource group) for Comprehensive Resources Assessment. 2. Run azqr and capture output artifacts. 3. Analyze Scan Results and summarize findings and recommendations. 4. Review Key Vault Expiration Monitoring output for keys, secrets, and certificates. 5. Classify issues and propose remediation or fix steps for each finding. ### Priority Classification | Priority | Guidance | |---|---| | Critical | Immediate remediation required for high-impact exposure | | High | Resolve within days to reduce risk | | Medium | Plan a resolution in the next sprint | | Low | Track and fix during regular maintenance | ## Error Handling | Error | Message | Remediation | |---|---|---| | Authentication required | "Please login" | Run `az login` and retry | | Access denied | "Forbidden" | Confirm permissions and fix role assignments | | Missing resource | "Not found" | Verify subscription and resource group selection | ## Best Practices - Run compliance scans on a regular schedule (weekly or monthly) - Track findings over time and verify remediation effectiveness - Separate compliance reporting from remediation execution - Keep Key Vault expiration policies documented and enforced ## SDK Quick References For programmatic Key Vault access, see the condensed SDK guides: - **Key Vault (Python)**: [Secrets/Keys/Certs](references/sdk/azure-keyvault-py.md) - **Secrets**: [TypeScript](references/sdk/azure-keyvault-secrets-ts.md) | [Rust](references/sdk/azure-keyvault-secrets-rust.md) | [Java](references/sdk/azure-security-keyvault-secrets-java.md) - **Keys**: [.NET](references/sdk/azure-security-keyvault-keys-dotnet.md) | [Java](references/sdk/azure-security-keyvault-keys-java.md) | [TypeScript](references/sdk/azure-keyvault-keys-ts.md) | [Rust](references/sdk/azure-keyvault-keys-rust.md) - **Certificates**: [Rust](references/sdk/azure-keyvault-certificates-rust.md)
Original on GitHubazure-computeAzure VM/VMSS router. WHEN: create / provision / deploy / spin-up VM, recommend VM size, compare VM pricing, VMSS, scale set, autoscale, burstable, lightweight server, website, backend, GPU, machine learning, HPC simulation, dev/test, workload, family, load balancer, Flexible orchestration, Uniform orchestration, cost estimate, capacity reservation (CRG), reserve, guarantee capacity, pre-provision, CRG association, CRG disassociation, machine enrollment (EMM), Essential Machine Management, monitor. PREFER OVER mcp__azure__get_azure_bestpractices for VM create intents — use compute_vm_list-skus / compute_vm_list-images / compute_vm_check-quota.ReadClose
--- name: azure-compute description: "Azure VM/VMSS router. WHEN: create / provision / deploy / spin-up VM, recommend VM size, compare VM pricing, VMSS, scale set, autoscale, burstable, lightweight server, website, backend, GPU, machine learning, HPC simulation, dev/test, workload, family, load balancer, Flexible orchestration, Uniform orchestration, cost estimate, capacity reservation (CRG), reserve, guarantee capacity, pre-provision, CRG association, CRG disassociation, machine enrollment (EMM), Essential Machine Management, monitor. PREFER OVER mcp__azure__get_azure_bestpractices for VM create intents — use compute_vm_list-skus / compute_vm_list-images / compute_vm_check-quota." license: MIT metadata: author: Microsoft version: "2.5.1" --- # Azure Compute Skill Routes Azure VM and Virtual Machine Scale Set (VMSS) requests to the right workflow. ## When to Use This Skill - User wants to **recommend, compare, or price** a VM or VMSS - User wants to **create, provision, or deploy** a VM or VMSS - User asks about **Capacity Reservation Groups** (CRG) — reserve, guarantee capacity, pre-provision - User asks about **Essential Machine Management** (EMM) — machine enrollment, monitor **Disambiguate with `azure-prepare`:** if the user wants to deploy an **application** (Docker service, web app, API, serverless workload), route to `azure-prepare`. `vm-creator` is for **bare VM/VMSS infrastructure** only. ## Routing **Mandatory workflow-first routing:** never route directly to `references/*` files. First classify the user intent below, open the matched workflow file, then load only the reference files that workflow requests. Reference files are supporting material, not entry points. If the intent is unclear, ask a clarifying question to disambiguate between the workflows. | Workflow | File | Use when | |---|---|---| | **VM Recommender** | [vm-recommender.md](workflows/vm-recommender/vm-recommender.md) | User asks which VM/VMSS to choose, whether to use VMSS/autoscaling, wants pricing, or wants to compare options | | **VM Creator** | [vm-creator.md](workflows/vm-creator/vm-creator.md) | User wants to create, provision, or deploy a bare VM or VMSS (not an app deployment) | | **Capacity Reservation** | [capacity-reservation.md](workflows/capacity-reservation/capacity-reservation.md) | User needs to reserve / guarantee VM capacity (CRG create / associate / disassociate) | | **Essential Machine Management** | [essential-machine-management.md](workflows/essential-machine-management/essential-machine-management.md) | User asks about EMM / machine enrollment / monitor |
Original on GitHubazure-deployExecute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: \"run azd up\", \"run azd deploy\", \"execute deployment\", \"push to production\", \"push to cloud\", \"go live\", \"ship it\", \"bicep deploy\", \"terraform apply\", \"publish to Azure\", \"launch on Azure\". DO NOT USE WHEN: \"create and deploy\", \"build and deploy\", \"create a new app\", \"set up infrastructure\", \"create and deploy to Azure using Terraform\" — use azure-prepare for these.ReadClose
--- name: azure-deploy description: "Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: \"run azd up\", \"run azd deploy\", \"execute deployment\", \"push to production\", \"push to cloud\", \"go live\", \"ship it\", \"bicep deploy\", \"terraform apply\", \"publish to Azure\", \"launch on Azure\". DO NOT USE WHEN: \"create and deploy\", \"build and deploy\", \"create a new app\", \"set up infrastructure\", \"create and deploy to Azure using Terraform\" — use azure-prepare for these." license: MIT metadata: author: Microsoft version: "1.2.2" --- # Azure Deploy > **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE** > > **PREREQUISITE**: The **azure-validate** skill **MUST** be invoked and completed with status `Validated` BEFORE executing this skill. > **⛔ STOP — PREREQUISITE CHECK REQUIRED** > Before proceeding, verify BOTH prerequisites are met: > > 1. **azure-prepare** was invoked and completed → `.azure/deployment-plan.md` exists > 2. **azure-validate** was invoked and passed → plan status = `Validated` > > If EITHER is missing, **STOP IMMEDIATELY**: > - No plan? → Invoke **azure-prepare** skill first > - Status not `Validated`? → Invoke **azure-validate** skill first > > **⛔ DO NOT MANUALLY UPDATE THE PLAN STATUS** > > You are **FORBIDDEN** from changing the plan status to `Validated` yourself. Only the **azure-validate** skill is authorized to set this status after running actual validation checks. If you update the status without running validation, deployments will fail. > > **DO NOT ASSUME** the app is ready. **DO NOT SKIP** validation to save time. Skipping steps causes deployment failures. The complete workflow ensures success: > > `azure-prepare` → `azure-validate` → `azure-deploy` ## Triggers Activate this skill when user wants to: - Execute deployment of an already-prepared application (azure.yaml and infra/ exist) - Push updates to an existing Azure deployment - Run `azd up`, `azd deploy`, or `az deployment` on a prepared project - Ship already-built code to production - Deploy an application that already includes API Management (APIM) gateway infrastructure > **Scope**: This skill executes deployments. It does not create applications, generate infrastructure code, or scaffold projects. For those tasks, use **azure-prepare**. > **APIM / AI Gateway**: Use this skill to deploy applications whose APIM/AI gateway infrastructure was already created during **azure-prepare**. For creating or changing APIM resources, see [APIM deployment guide](https://learn.microsoft.com/azure/api-management/get-started-create-service-instance). For AI governance policies, invoke **azure-aigateway** skill. ## Rules 1. Run after azure-prepare and azure-validate 2. `.azure/deployment-plan.md` must exist with status `Validated` 3. **Pre-deploy checklist required** — [Pre-Deploy Checklist](references/pre-deploy-checklist.md) 4. ⛔ **Destructive actions require `ask_user`** — [global-rules](references/global-rules.md) 5. **Scope: deployment execution only** — This skill owns execution of `azd up`, `azd deploy`, `terraform apply`, and `az deployment` commands. These commands are run through this skill's error recovery and verification pipeline. --- ## Steps | # | Action | Reference | |---|--------|-----------| | 1 | **Check Plan** — Read `.azure/deployment-plan.md`, verify status = `Validated` AND **Validation Proof** section is populated | `.azure/deployment-plan.md` | | 2 | **Pre-Deploy Checklist** — MUST complete ALL steps | [Pre-Deploy Checklist](references/pre-deploy-checklist.md) | | 3 | **Load Recipe** — Based on `recipe.type` in `.azure/deployment-plan.md` | [recipes/README.md](references/recipes/README.md) | | 4 | **RBAC Health Check** — For Container Apps + ACR with managed identity: run `azd provision --no-prompt`, then verify `AcrPull` role has propagated before proceeding (see checklist) | [Pre-Deploy Checklist — Container Apps RBAC](references/pre-deploy-checklist.md#container-apps--acr--pre-deploy-rbac-health-check) | | 5 | **Execute Deploy** — Follow recipe steps | Recipe README | | 6 | **Post-Deploy** — Configure SQL managed identity and apply EF migrations if applicable | [Post-Deployment](references/recipes/azd/post-deployment.md) | | 7 | **Handle Errors** — See recipe's `errors.md` | — | | 8 | **Verify Success** — Confirm deployment completed and endpoints are accessible | [Verification](references/recipes/azd/verify.md) | | 9 | **Live Role Verification** — Query Azure to confirm provisioned RBAC roles are correct and sufficient | [live-role-verification.md](references/live-role-verification.md) | | 10 | **Report Results** — Present deployed endpoint URLs to the user as fully-qualified `https://` links | [Verification](references/recipes/azd/verify.md) | > **⛔ URL FORMAT RULE** > > When presenting endpoint URLs to the user, you **MUST** always use fully-qualified URLs with the `https://` scheme (e.g. `https://myapp.azurewebsites.net`, not `myapp.azurewebsites.net`). Many Azure CLI commands return bare hostnames without a scheme — always prepend `https://` before presenting them. > **⛔ VALIDATION PROOF CHECK** > > When checking the plan, verify the **Validation Proof** section (Section 7) contains actual validation results with commands run and timestamps. If this section is empty, validation was bypassed — invoke **azure-validate** skill first. ## SDK Quick References - **Azure Developer CLI**: [azd](references/sdk/azd-deployment.md) - **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md) ## MCP Tools | Tool | Purpose | |------|---------| | `mcp_azure_mcp_subscription_list` | List available subscriptions | | `mcp_azure_mcp_group_list` | List resource groups in subscription | | `mcp_azure_mcp_azd` | Execute AZD commands | | `azure__role` | List role assignments for live RBAC verification (step 9) | ## References - [Troubleshooting](references/troubleshooting.md) - Common issues and solutions - [Post-Deployment Steps](references/recipes/azd/post-deployment.md) - SQL + EF Core setup
Original on GitHubazure-diagnosticsDebug Azure production issues using AppLens, Azure Monitor, resource health, and safe triage, including evidence-only diagnosis without live access. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.ReadClose
--- name: azure-diagnostics description: "Debug Azure production issues using AppLens, Azure Monitor, resource health, and safe triage, including evidence-only diagnosis without live access. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter." license: MIT metadata: author: Microsoft version: "1.2.14" --- # Azure Diagnostics > **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE** > > This document is the **official source** for debugging and troubleshooting Azure production issues. Follow these instructions to diagnose and resolve common Azure service problems systematically. ## Triggers Activate this skill when user wants to: - Debug or troubleshoot production issues - Diagnose errors in Azure services - Analyze application logs or metrics - Fix image pull, cold start, or health probe issues - Investigate why Azure resources are failing - Find root cause of application errors - Troubleshoot App Service issues (high CPU, deployment failures, crashes, slow responses, TLS/custom domains) - Respond to prompts like "troubleshoot app service", "app service high CPU", or "app service deployment failure" - Troubleshoot Azure Function Apps (invocation failures, timeouts, binding errors) - Find the App Insights or Log Analytics workspace linked to a Function App - Troubleshoot AKS clusters, nodes, pods, ingress, or Kubernetes networking issues - Troubleshoot Azure VM connectivity issues (RDP/SSH failures, port 3389/22 timeouts, NSG or firewall blocking, credential resets) - Troubleshoot Azure Messaging SDK issues (Event Hubs, Service Bus connection failures, AMQP errors, message lock issues) - Root-cause a symptom that looks like a healthy-runtime-but-wrong-destination problem (e.g., telemetry/messages stop flowing to the expected resource after a config change) — invoke this skill for the matrix even when MCP tools could answer the surface question alone ## Rules 1. Start with systematic diagnosis flow 2. Use supplied evidence first. If the user requests evidence-only analysis or prohibits live Azure access, do not query or modify Azure. Diagnose from the supplied logs, metrics, and timeline; identify assumptions and provide optional verification steps. 3. Use AppLens (MCP) for AI-powered diagnostics when available 4. Check resource health before deep-diving into logs 5. Select appropriate troubleshooting guide based on service type 6. Document findings and attempted remediation steps 7. Prefer bundled diagnostic scripts over ad hoc calls for permitted live collection when identifiers are known. If supplied evidence suffices or live access is prohibited, don't run them; otherwise run the applicable script first. 8. Route AKS incidents to the dedicated AKS troubleshooting document 9. Keep baseline AKS diagnostics available even when the optional `aks-skills` add-on is absent, declined, or unsupported by the host --- ## Quick Diagnosis Flow 1. **Identify symptoms** - What's failing? 2. **Check resource health** - Is Azure healthy? 3. **Review logs** - What do logs show? 4. **Analyze metrics** - Performance patterns? 5. **Investigate recent changes** - What changed? --- ## Troubleshooting Guides by Service | Service | Common Issues | Reference | |---------|---------------|-----------| | **Container Apps** | Image pull failures, cold starts, health probes, port mismatches | [container-apps/](references/container-apps/README.md) | | **App Service** | High CPU, deployment failures, crashes, slow responses, TLS/custom domains | [app-service/](references/app-service/README.md) | | **Function Apps** | App details, invocation failures, timeouts, binding errors, cold starts, missing app settings | [functions/](references/functions/README.md) | | **AKS** | Cluster access, nodes, `kube-system`, scheduling, crash loops, ingress, DNS, upgrades | [AKS Troubleshooting](troubleshooting/aks/aks-troubleshooting.md) | | **Compute** | VM RDP/SSH connectivity, NSG/firewall blocks, credential resets, VM agent/tooling issues | [VM Connectivity Troubleshooting](troubleshooting/compute/vm-troubleshooting.md) | | **Messaging** | Event Hubs & Service Bus SDK errors, AMQP failures, message lock, connectivity | [Messaging Troubleshooting](troubleshooting/messaging/README.md) | --- ## Routing - Keep Container Apps and Function Apps diagnostics in this parent skill. - Route active AKS incidents, AKS-specific intake, evidence gathering, and remediation guidance to [AKS Troubleshooting](troubleshooting/aks/aks-troubleshooting.md). - Route Azure VM RDP/SSH connectivity, NSG/firewall, credential reset, and VM agent troubleshooting to [VM Connectivity Troubleshooting](troubleshooting/compute/vm-troubleshooting.md). - Route Azure Messaging SDK troubleshooting (Event Hubs, Service Bus) to [Messaging Troubleshooting](troubleshooting/messaging/README.md). --- ## Quick Reference ### Common Diagnostic Commands ```bash # Check resource health az resource show --ids RESOURCE_ID # View activity log az monitor activity-log list -g RG --max-events 20 # Container Apps logs az containerapp logs show --name APP -g RG --follow # Function App logs (query App Insights traces) az monitor app-insights query --apps APP-INSIGHTS -g RG \ --analytics-query "traces | where timestamp > ago(1h) | order by timestamp desc | take 50" ``` ### AppLens (MCP Tools) For AI-powered diagnostics, use: ``` mcp_azure_mcp_applens intent: "diagnose issues with <resource-name>" command: "diagnose" parameters: resourceId: "<resource-id>" Provides: - Automated issue detection - Root cause analysis - Remediation recommendations ``` ### Azure Monitor (MCP Tools) For querying logs and metrics: ``` mcp_azure_mcp_monitor intent: "query logs for <resource-name>" command: "logs_query" parameters: workspaceId: "<workspace-id>" query: "<KQL-query>" ``` See [kql-queries.md](references/kql-queries.md) for common diagnostic queries. --- ## Check Azure Resource Health ### Using MCP ``` mcp_azure_mcp_resourcehealth intent: "check health status of <resource-name>" command: "get" parameters: resourceId: "<resource-id>" ``` ### Using CLI ```bash # Check specific resource health az resource show --ids RESOURCE_ID # Check recent activity az monitor activity-log list -g RG --max-events 20 ``` --- ## References - [KQL Query Library](references/kql-queries.md) - [Azure Resource Graph Queries](references/azure-resource-graph.md) - [App Service Troubleshooting](references/app-service/README.md) - [Function Apps Troubleshooting](references/functions/README.md) - [VM Connectivity Troubleshooting](troubleshooting/compute/vm-troubleshooting.md) - [Messaging Troubleshooting](troubleshooting/messaging/README.md)Original on GitHubazure-enterprise-infra-plannerArchitect and provision enterprise Azure infrastructure from workload descriptions. For cloud architects and platform engineers planning networking, identity, security, compliance, and multi-resource topologies with WAF alignment. Generates Bicep or Terraform directly (no azd). WHEN: 'plan Azure infrastructure', 'architect Azure landing zone', 'design hub-spoke network', 'plan multi-region DR topology', 'set up VNets firewalls and private endpoints', 'subscription-scope Bicep deployment', 'Azure Backup for VM workloads'. PREFER azure-prepare FOR app-centric workflows.ReadClose
--- name: azure-enterprise-infra-planner description: "Architect and provision enterprise Azure infrastructure from workload descriptions. For cloud architects and platform engineers planning networking, identity, security, compliance, and multi-resource topologies with WAF alignment. Generates Bicep or Terraform directly (no azd). WHEN: 'plan Azure infrastructure', 'architect Azure landing zone', 'design hub-spoke network', 'plan multi-region DR topology', 'set up VNets firewalls and private endpoints', 'subscription-scope Bicep deployment', 'Azure Backup for VM workloads'. PREFER azure-prepare FOR app-centric workflows." license: MIT metadata: author: Microsoft version: "1.4.2" --- # 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 | Property | Details | |---|---| | MCP tools | `insights_get`, `get_azure_bestpractices_get`, `wellarchitectedframework_serviceguide_get`, `microsoft_docs_fetch`, `microsoft_docs_search`, `bicepschema_get` | | CLI commands | `az deployment group create`, `az bicep build`, `az resource list`, `terraform init`, `terraform plan`, `terraform validate`, `terraform apply`, `checkov` | | Output schema | [schema.md](references/schema.md) | | Key references | [workflow.md](references/workflow.md), [waf-checklist.md](references/waf-checklist.md), [resources/](references/resources/README.md), [constraints/](references/constraints/README.md) | ## Workflow (Start Here) Follow the step-by-step instructions in [workflow.md](references/workflow.md) to execute the 7 phases of infrastructure planning and provisioning. ## Architecture The skill runs a **7-phase, gated pipeline**. Input is triaged into one of two flows: - **Greenfield** — only new requirements; run the phases straight through. - **Referenced (brownfield)** — the user supplies something that already exists (a live resource / resource group / subscription, IaC or an infra plan, or a requirements doc). The same phases run, plus [referenced-workload.md](references/referenced-workload.md): existing resources are inventoried and referenced (never recreated), the new workload is wired into them, and **Phase 7 deploys additively** (incremental only — never modifying or destroying the referenced resources). Every phase advances only after its gate passes. Phase 5 requires explicit user approval; **Phase 6 is a hardened, self-verifying gate** — the generated IaC must be secure-by-default, pass local validation (`az bicep build` / `terraform validate`) with zero errors, pass a `checkov` security scan with no unresolved high/critical findings, and the skill must **show the command output** and emit a completion self-check before advancing; Phase 7 requires an explicit, risk-acknowledged deploy confirmation. ```mermaid flowchart TD IN([Input]) --> TRIAGE{Existing infra<br/>referenced?} TRIAGE -- "No (greenfield)" --> P1 TRIAGE -- "Yes (referenced)" --> RW[/referenced-workload.md:<br/>inventory + assign roles<br/>reference, never recreate/] RW --> P1 subgraph PIPE [7-phase gated pipeline] direction TB P1[Phase 1 · Extract insights] --> P2[Phase 2 · Research best practices] P2 --> P3[Phase 3 · Research resources] P3 --> P4[Phase 4 · Generate plan] P4 --> P5{Phase 5 · Verify<br/>user approves?} P5 -- "no" --> P4 P5 -- "approved" --> P6[Phase 6 · Generate IaC] P6 --> VAL{Validate<br/>az bicep build /<br/>terraform validate} VAL -- "errors" --> P6 VAL -- "clean" --> P7{Phase 7 · Deploy<br/>risk-ack confirm?} end P7 -- "greenfield" --> DEP[az deployment / terraform apply] P7 -- "referenced" --> DEPADD[Additive deploy · incremental only<br/>what-if preview · no destroy of<br/>referenced resources] DEP --> OUT([Deployed]) DEPADD --> OUT classDef gate fill:#fff3cd,stroke:#d39e00,color:#000; classDef ref fill:#e2f0d9,stroke:#548235,color:#000; class P5,VAL,P7,TRIAGE gate; class RW,DEPADD ref; ``` **Artifacts** (written under `<project-root>/`): `.azure/insights.json` (Phase 1), `.azure/infrastructure-plan.json` (Phase 4, status `draft`→`approved`→`deployed`), and `infra/main.bicep` + `infra/modules/*` or `infra/main.tf` + `infra/modules/**` (Phase 6). ## MCP Tools | Tool | Purpose | |------|---------| | `insights_get` | Retrieve insights about the user's existing Azure environment to guide planning decisions | | `get_azure_bestpractices_get` | Azure best practices for code generation, operations, and deployment | | `wellarchitectedframework_serviceguide_get` | WAF service guide for a specific Azure service | | `microsoft_docs_search` | Search Microsoft Learn for relevant documentation chunks | | `microsoft_docs_fetch` | Fetch full content of a Microsoft Learn page by URL | | `bicepschema_get` | Bicep schema definition for any Azure resource type (latest API version) | ## Error Handling | Error | Cause | Fix | |---|---|---| | MCP tool error or not available | Tool call timeout, connection error, or tool doesn't exist | Retry once; fall back to reference files and notify user if unresolved | | Plan approval missing | `meta.status` is not `approved` | Stop and prompt user for approval before IaC generation or deployment | | IaC validation failure | `az bicep build` or `terraform validate` returns errors | Fix the generated code and re-validate; notify user if unresolved | | Pairing constraint violation | Incompatible SKU or resource combination | Fix in plan before proceeding to IaC generation | | Infra plan or IaC files not found | Files written to wrong location or not created | Verify files exist at `<project-root>/.azure/` and `<project-root>/infra/`; if missing, re-create the files by following [workflow.md](references/workflow.md) exactly |Original on GitHubazure-kubernetesPlan, create, and configure production-ready Azure Kubernetes Service (AKS) clusters. Covers Day-0 checklist, SKU selection (Automatic vs Standard), networking options (private API server, Azure CNI Overlay, egress configuration), security, and operations (autoscaling, upgrade strategy, cost analysis). WHEN: create AKS environment, provision AKS, enable AKS observability, design AKS networking, choose AKS SKU, secure AKS, optimize AKS, AKS spot nodes, AKS cluster-autoscaler, rightsize AKS pod, pod rightsizing, over-provisioned AKS pod, pod resource requests and limits, Vertical Pod Autoscaler, VPA recommendations.ReadClose
--- name: azure-kubernetes license: MIT metadata: author: Microsoft version: "1.2.5" description: "Plan, create, and configure production-ready Azure Kubernetes Service (AKS) clusters. Covers Day-0 checklist, SKU selection (Automatic vs Standard), networking options (private API server, Azure CNI Overlay, egress configuration), security, and operations (autoscaling, upgrade strategy, cost analysis). WHEN: create AKS environment, provision AKS, enable AKS observability, design AKS networking, choose AKS SKU, secure AKS, optimize AKS, AKS spot nodes, AKS cluster-autoscaler, rightsize AKS pod, pod rightsizing, over-provisioned AKS pod, pod resource requests and limits, Vertical Pod Autoscaler, VPA recommendations." --- # Azure Kubernetes Service > **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE** > > This skill produces a **recommended AKS cluster configuration** based on user requirements, distinguishing **Day-0 decisions** (networking, API server — hard to change later) from **Day-1 features** (can enable post-creation). See [CLI reference](./references/cli-reference.md) for commands. ## Quick Reference | Property | Value | |----------|-------| | Best for | AKS cluster planning and Day-0 decisions | | MCP Tools | `mcp_azure_mcp_aks` | | CLI | `az aks create`, `az aks show`, `kubectl get`, `kubectl describe` | | Related skills | azure-kubernetes-app-deploy (deploy an app to an existing cluster), azure-diagnostics (baseline AKS troubleshooting), azure-validate (readiness checks), azure-kubernetes-automatic-readiness (migrate existing cluster to AKS Automatic), optional `aks-skills` operations add-on (focused incident, advanced cost-efficiency, exact-signature, packet-capture, and GPU Day-2 workflows) | ## When to Use This Skill Activate this skill when user wants to: - Create a new AKS cluster - Plan AKS cluster configuration for production workloads - Design AKS networking (API server access, pod IP model, egress) - Set up AKS identity and secrets management - Configure AKS governance (Azure Policy, Deployment Safeguards) - Enable AKS observability (Container Insights, Managed Prometheus, Grafana) - Define AKS upgrade and patching strategy - Understand AKS Automatic vs Standard SKU differences - Get a Day-0 checklist for AKS cluster setup and configuration > **Deploying an application to an existing cluster?** This skill provisions and > configures the *cluster*. To containerize an app and deploy it to a cluster > that already exists (Dockerfile + manifests + Deployment Safeguards), use the > `azure-kubernetes-app-deploy` sub-skill instead. > **Deeper operational task?** Keep Day-0 planning and basic operations in this > base skill. Load [optional-aks-operations.md](./references/optional-aks-operations.md) > only when a focused optional AKS operational skill could improve the current > task. ## Rules 1. Start with the user's requirements for provisioning compute, networking, security, and other settings. 2. Use the `azure` MCP server and select `mcp_azure_mcp_aks` first to discover the exact AKS-specific MCP tools surfaced by the client. Choose the smallest discovered AKS tool that fits the task, and fall back to Azure CLI (`az aks`) only when the needed functionality is not exposed through the AKS MCP surface. 3. Determine if AKS Automatic or Standard SKU is more appropriate based on the user's need for control vs convenience. Default to AKS Automatic unless specific customizations are required. 4. Document decisions and rationale for cluster configuration choices, especially for Day-0 decisions that are hard to change later (networking, API server access). ## Required Inputs (Ask only what’s needed) If the user is unsure, use safe defaults. - AKS environment type: dev/test or production - Region(s), availability zones, preferred node VM sizes - Expected scale (node/cluster count, workload size) - Networking requirements (API server access, pod IP model, ingress/egress control) - Security and identity requirements, including image registry - Upgrade and observability preferences - Cost constraints ## Workflow ### 1. Cluster Type - **AKS Automatic** (default): Best for most production workloads, provides a curated experience with pre-configured best practices for security, reliability, and performance. Use unless you have specific custom requirements for networking, autoscaling, or node pool configurations not supported by Node Auto-Provisioning (NAP). - **AKS Standard**: Use if you need full control over environment configuration, which requires additional overhead to set up and manage. ### 2. Networking (Pod IP, Egress, Ingress, Dataplane) **Pod IP Model** (Key Day-0 decision): - **Azure CNI Overlay** (recommended): pod IPs from private overlay range, not VNet-routable, scales to large environments and good for most workloads - **Azure CNI (VNet-routable)**: pod IPs directly from VNet (pod subnet or node subnet), use when pods must be directly addressable from VNet or on-prem - Docs: https://learn.microsoft.com/azure/aks/azure-cni-overlay **Dataplane & Network Policy**: - **Azure CNI powered by Cilium** (recommended): eBPF-based for high-performance packet processing, network policies, and observability **Egress**: - **Static Egress Gateway** for stable, predictable outbound IPs - For restricted egress: UDR + Azure Firewall or NVA **Ingress**: - **App Routing addon with Gateway API** — recommended default for HTTP/HTTPS workloads - **Istio service mesh with Gateway API** - for advanced traffic management, mTLS, canary releases - **Application Gateway for Containers** — for L7 load balancing with WAF integration **DNS**: - Enable **LocalDNS** on all node pools for reliable, performant DNS resolution ### 3. Security - Use **Microsoft Entra ID** everywhere (control plane, Workload Identity for pods, node access). Avoid static credentials. - Azure Key Vault via **Secrets Store CSI Driver** for secrets - Enable **Azure Policy** + **Deployment Safeguards** - Enable **Encryption at rest** for etcd/API server; **in-transit** for node-to-node - Allow only signed, policy-approved images (Azure Policy + Ratify), prefer **Azure Container Registry** - **Isolation**: Use namespaces, network policies, scoped logging ### 4. Observability - Use Managed Prometheus and Container Insights with Grafana for AKS observability (logs + metrics). - Enable Diagnostic Settings to collect control plane logs and audit logs in a Log Analytics workspace for security monitoring and troubleshooting. - For other monitoring and troubleshooting tools, use features like the Agentic CLI for AKS, Application Insights, Resource Health Center, AppLens detectors, and Azure Advisors. ### 5. Upgrades & Patching - Configure **Maintenance Windows** for controlled upgrade timing - Enable **auto-upgrades** for control plane and node OS to stay up-to-date with security patches and Kubernetes versions - Consider **LTS versions** for enterprise stability (2-year support) by upgrading your AKS environment to the Premium tier - **Fleet upgrades**: Use **AKS Fleet Manager** for staged rollout across test to production environments ### 6. Performance - Use **Ephemeral OS disks** (`--node-osdisk-type Ephemeral`) for faster node startup - Select **Azure Linux** as node OS (smaller footprint, faster boot) - Enable **KEDA** for event-driven autoscaling beyond HPA ### 7. Node Pools & Compute - **Dedicated system node pool**: At least 2 nodes, tainted for system workloads only (`CriticalAddonsOnly`) - **Node Auto Provisioning (NAP)** is enabled per cluster and can reduce cost when dynamic capacity fits workload demand; savings are not guaranteed. Enable NAP for new clusters. For existing clusters, use [optional AKS operations](./references/optional-aks-operations.md) to invoke `aks-cost-optimization` when available for NAP readiness. Otherwise, continue with [base NAP readiness](./references/azure-aks-nap-readiness.md). - Use **latest generation SKUs (v5/v6)** for host-level optimizations - **Avoid B-series VMs** — burstable SKUs cause performance/reliability issues - Use SKUs with **at least 4 vCPUs** for production workloads - Set **topology spread constraints** to distribute pods across hosts/zones per SLO ### 8. Reliability - Deploy across **3 Availability Zones** (`--zones 1 2 3`) - Use **Standard tier** for zone-redundant control plane + 99.95% SLA for API server availability - Enable **Microsoft Defender for Containers** for runtime protection - Configure **PodDisruptionBudgets** for all production workloads - Use **topology spread constraints** to ensure pod distribution across failure domains ### 9. Cost Controls - Use **Spot node pools** for batch/interruptible workloads (up to 90% savings) - **Stop/Start** dev/test clusters: `az aks stop/start` #### Focused AKS Cost Workflows For a focused request, load only the relevant reference file. | Scenario | Trigger Keywords | Reference | |----------|-----------------|-----------| | Pod Rightsizing | over-provisioned pods, CPU requests, memory requests, rightsize workloads | [azure-aks-rightsizing.md](./references/azure-aks-rightsizing.md) | | VPA Setup | vertical pod autoscaler, VPA recommendations, VPA enable | [azure-aks-vpa.md](./references/azure-aks-vpa.md) | | Cluster Autoscaler | idle nodes, CAS off, enable autoscaler, scale-down profile, node utilization | [azure-aks-autoscaler.md](./references/azure-aks-autoscaler.md) | | Spot Node Pools | Spot VMs, Spot nodes, batch workloads, cheaper nodes | [azure-aks-spot.md](./references/azure-aks-spot.md) | | Advanced AKS Cost Efficiency | NAP readiness, node-pool bin packing, blocked scale-down, Kubernetes storage cost | [optional AKS operations](./references/optional-aks-operations.md) | > **Disambiguation:** If a prompt matches multiple rows (e.g., "cheaper nodes" could suggest both Spot and autoscaler), prefer the most specific match. If ambiguous, ask the user to clarify their intent before loading a reference file. #### Comprehensive AKS Cost Review When the user requests an overall AKS cost assessment rather than one focused workflow, this skill owns triage and coordinates one unified review: 1. Confirm the target subscription, resource group, and AKS cluster. If `cost-analysis` is available, collect one billed-cost baseline for that scope and reuse it throughout the review. 2. Evaluate the applicable rightsizing, VPA, Cluster Autoscaler, and Spot workflows. 3. Invoke `aks-cost-optimization` when available for NAP readiness, node-pool bin packing, node-scaling bottlenecks, or Kubernetes-to-Azure storage optimization. 4. Check for stable non-Spot demand. If present, invoke `cost-optimization` when available for commitment analysis. If the capability or evidence is unavailable, report commitment analysis as a gap. Do not recommend a purchase from this review alone. Investigate applicable levers and return one ranked report. Rank by comparable estimated cost impact when available; keep unknown monetary impact unknown rather than zero. Do not present one narrow analysis as the complete review. Mark unavailable capabilities or evidence as gaps. | Rank | Lever | Evidence | Estimated cost impact and basis | Risk | Approval needed | Confidence | |---|---|---|---|---|---|---| ## Guardrails / Safety - Do not request or output secrets (tokens, keys). - Do not ask the user to paste subscription IDs. Discover subscription and resource scope via MCP tools (e.g., list subscriptions, list resource groups) or `az account show` / `az account list` so the agent can resolve context without exposing identifiers. - If requirements are ambiguous for day-0 critical decisions, ask the user clarifying questions. For day-1 enabled features, propose 2–3 safe options with tradeoffs and choose a conservative default. - Do not promise zero downtime; advise workload safeguards (PDBs, probes, replicas) and staged upgrades along with best practices for reliability and performance. ## MCP Tools | Tool | Purpose | Key Parameters | |------|---------|----------------| | `mcp_azure_mcp_aks` | AKS MCP entry point used to discover the exact AKS-specific tools exposed by the client | Discover the callable AKS tool first, then use that tool's parameters | ## Error Handling | Error / Symptom | Likely Cause | Remediation | |-----------------|--------------|-------------| | MCP tool call fails or times out | Invalid credentials, subscription, or AKS context | Verify `az login`, confirm the active subscription context with `az account show`, and check the target resource group without echoing subscription identifiers back to the user | | Quota exceeded | Regional vCPU or resource limits | Request quota increase or select different region/VM SKU | | Networking conflict (IP exhaustion) | Pod subnet too small for overlay/CNI | Re-plan IP ranges; may require cluster recreation (Day-0) | | Workload Identity not working | Missing OIDC issuer or federated credential | Enable `--enable-oidc-issuer --enable-workload-identity`, configure federated identity |
Original on GitHubazure-kubernetes-app-deployUse when deploying an existing web application or API to an already-running Azure Kubernetes Service cluster. Detects the framework, generates a Dockerfile and Kubernetes manifests, validates against AKS Deployment Safeguards, and deploys with verification. WHEN: deploy app to AKS, deploy to existing AKS cluster, containerize app for Kubernetes, generate K8s manifests for Azure, set up CI/CD for AKS, my AKS deployment is failing safeguard checks, I have a Django/Express/Spring Boot app to run on AKS. DO NOT USE FOR: creating or provisioning an AKS cluster (use azure-kubernetes), assessing migration to AKS Automatic (use azure-kubernetes-automatic-readiness), or deploying to non-AKS targets like Web Apps, Container Apps, or Functions.ReadClose
--- name: azure-kubernetes-app-deploy license: MIT metadata: author: Microsoft version: "1.0.0" description: "Use when deploying an existing web application or API to an already-running Azure Kubernetes Service cluster. Detects the framework, generates a Dockerfile and Kubernetes manifests, validates against AKS Deployment Safeguards, and deploys with verification. WHEN: deploy app to AKS, deploy to existing AKS cluster, containerize app for Kubernetes, generate K8s manifests for Azure, set up CI/CD for AKS, my AKS deployment is failing safeguard checks, I have a Django/Express/Spring Boot app to run on AKS. DO NOT USE FOR: creating or provisioning an AKS cluster (use azure-kubernetes), assessing migration to AKS Automatic (use azure-kubernetes-automatic-readiness), or deploying to non-AKS targets like Web Apps, Container Apps, or Functions." --- # Deploy to AKS **Use when:** deploying a web app/API to AKS; containerizing for Kubernetes; generating manifests; AKS CI/CD; DS001–DS013 failures. **Not for:** provisioning clusters (`azure-kubernetes`), AKS Automatic readiness (`azure-kubernetes-automatic-readiness`), non-AKS targets. ## Workflow Requires: existing AKS cluster, `az login`, `kubectl` configured. Follow `phases/quick-deploy.md`. On failure: `references/rollback.md`. ## References - [detection.md](./references/detection.md) — framework/port/health detection - [safeguards.md](./references/safeguards.md) — DS001-DS013 checklist - [workload-identity.md](./references/workload-identity.md) — Workload Identity setup - [rollback.md](./references/rollback.md) — recovery procedures - [base-images.md](./references/base-images.md) — base image policy and `<LATEST_STABLE_*>` resolution ## Knowledge Packs Load `knowledge-packs/frameworks/<framework>.md` per detected framework. Available: `spring-boot`, `express`, `nextjs`, `fastapi`, `django`, `nestjs`, `aspnet-core`, `go`, `flask` ## Templates `templates/` (dockerfiles/, k8s/, github-actions/, mermaid/).
Original on GitHubazure-kubernetes-automatic-readinessAssess Kubernetes workloads and cluster configuration for AKS Automatic compatibility. Identifies incompatibilities, generates fixes, and guides migration from AKS Standard to AKS Automatic. WHEN: migrate to AKS Automatic, check AKS Automatic readiness, validate manifests for Automatic, assess cluster for Automatic compatibility, fix deployment for Automatic compatibility, identify AKS Automatic migration blockers, is my cluster ready for AKS Automatic.ReadClose
--- name: azure-kubernetes-automatic-readiness license: MIT metadata: author: Microsoft version: "1.1.0" description: "Assess Kubernetes workloads and cluster configuration for AKS Automatic compatibility. Identifies incompatibilities, generates fixes, and guides migration from AKS Standard to AKS Automatic. WHEN: migrate to AKS Automatic, check AKS Automatic readiness, validate manifests for Automatic, assess cluster for Automatic compatibility, fix deployment for Automatic compatibility, identify AKS Automatic migration blockers, is my cluster ready for AKS Automatic." --- # AKS Automatic Readiness Assessment > **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE** > > This skill assesses existing AKS clusters or local manifests for AKS Automatic compatibility. > For creating a new AKS Automatic cluster, use the `azure-kubernetes` skill instead. > See [constraint spec](./references/constraint-spec-v1.yaml) for all safeguard rules, [common fixes](./references/common-fixes.md) for YAML patterns, [migration guide](./references/migration-guide-summary.md) for end-to-end steps, and [MCP integration](./references/mcp-integration.md) for tool details and fallback handling. You are an AKS Automatic compatibility assessment agent. Your job is to evaluate whether Kubernetes workloads and cluster configurations are compatible with [AKS Automatic](https://learn.microsoft.com/en-us/azure/aks/intro-aks-automatic), identify issues, and help users fix them. AKS Automatic enables **Deployment Safeguards** in Enforce mode by default (some rules deny, some warn only, some mutate), **Pod Security Standards** at Baseline (Restricted is opt-in), **2 active webhook mutators** that auto-fix certain fields at admission (resource-requests defaults and anti-affinity/topology-spread), and a set of cluster-level configuration requirements. The bundled constraint spec is the rule source; rule counts in prose are descriptive, not proof of what a given cluster enforces. ## Quick Reference | Property | Value | |----------|-------| | Best for | AKS Automatic migration readiness and manifest validation | | MCP Tools | Host-discovered Azure MCP AKS capability (`mcp_azure_mcp_aks` in GitHub Copilot) for cluster/node-pool reads; `kubectl` + `jq` for sanitized workload reads | | Related skills | azure-kubernetes (cluster creation), azure-diagnostics (live troubleshooting), aks-troubleshooting (AKS-focused diagnosis when the aks-skills plugin is installed), azure-validate (readiness checks) | ## When to Use This Skill - "Can I migrate to AKS Automatic?" - "Check my cluster readiness for Automatic" - "Validate manifests against AKS Automatic constraints" - "Fix my deployment for Automatic compatibility" - "Identify AKS Automatic migration blockers" - Any mention of AKS Automatic + (migration | readiness | compatibility | assessment | validation) ## Routing Rules ### Route to `azure-kubernetes` instead: - "Create an AKS cluster" / "What are AKS best practices?" / "How do I deploy to AKS?" - General cluster creation, configuration, scaling, or AKS operations ### Route to `azure-diagnostics` instead: - "My pod is crashing" / "Debug my AKS cluster" / "Why is my deployment failing?" - Live troubleshooting, debugging, error diagnosis on a running cluster ## Guardrails — READ FIRST 1. **Read-only**: NEVER modify cluster state. Assessment is read-only. Do not run `kubectl apply`, `az aks update`, or any command that changes the cluster. 2. **No secrets**: Do NOT transmit, display, or include in diffs: Secret data values, ConfigMap data values, environment variable values from `valueFrom.secretKeyRef`, service account tokens, or connection strings. 3. **User approval for file changes**: Present every fix as a diff. The user must explicitly accept before you write to any file. 4. **Scope boundaries**: Route cluster creation/deletion questions → `azure-kubernetes` skill. Route live troubleshooting → `azure-diagnostics` skill. ## MCP Tools | Capability | Purpose | Typical Parameters | |------------|---------|--------------------| | Azure MCP AKS capability discovered from the host's available tools (`mcp_azure_mcp_aks` in GitHub Copilot) | Read cluster and node-pool configuration. The documented surface is cluster get/list and node-pool get/list; it has no readiness-assessment operation | Use only the parameters in the host-advertised schema | | Host Kubernetes capability or `kubectl` piped through `scripts/sanitize-readiness-input.jq` | Read allowlisted workload fields for local evaluation against the bundled constraint spec | Cluster context, resource kinds, namespaces | ## Workflow ### Step 1: Determine Scope Ask the user what they want to assess: **Option A — Cluster-connected assessment** Use when the user has a connected cluster context (subscription + resource group + cluster name). **Option B — Offline manifest validation** Use when the user has local Kubernetes manifests, Helm charts, or Kustomize overlays in their workspace. Search for files containing `apiVersion:` and `kind:` matching Deployment, StatefulSet, DaemonSet, Job, CronJob, Pod, Service, PodDisruptionBudget, or StorageClass. For Helm charts, look for `Chart.yaml` and rendered templates under `templates/`. **Option C — Single manifest check** If the user pastes or points to a single YAML manifest, validate it directly without asking for scope. ### Step 2: Run Assessment #### Cluster-Connected Mode 1. Discover the host's approved AKS metadata capabilities; use their host-assigned names and schemas. Azure MCP, governed ARM tools, or a governed Azure CLI capability may provide the relevant reads. A missing literal name is not proof of absence. 2. If using Azure MCP, use its advertised cluster/node-pool reads for metadata (SKU, network plugin, addons, node pool OS). The documented surface has no readiness-assessment operation — do not expect one ([Azure MCP AKS tools](https://learn.microsoft.com/azure/developer/azure-mcp-server/tools/azure-kubernetes)). 3. Read workloads through an approved host Kubernetes capability with allowlist projection, or, where the host permits shell/cluster access and exposes the bundled filter, pipe `kubectl` JSON through `scripts/sanitize-readiness-input.jq` (requires `jq`) before anything reaches the model. Never fetch `Secret`/ConfigMap resources or paste raw `kubectl -o json`. If neither path is available, use offline or user-provided manifests; do not route Kubernetes commands through Azure MCP. 4. Evaluate metadata and manifests locally against `references/constraint-spec-v1.yaml`. 5. Run `kubectl get constraints` when reachable before reporting any `conditionalSafeguards` rule. ```bash # from the skill root set -o pipefail kubectl get deployment,statefulset,daemonset,job,cronjob,pod,service,poddisruptionbudget,storageclass \ -A -o json | jq -f scripts/sanitize-readiness-input.jq ``` #### Fallback Chain ``` Cluster metadata: 1. Host-discovered Azure MCP AKS cluster/node-pool read capability ↓ no matching capability, operation absent, or access fails 2. Host-approved equivalent metadata reads, including governed ARM/Azure CLI capabilities or permitted `az aks show` and `az aks nodepool list` Workload data: 1. Approved host Kubernetes read with projection, or permitted sanitized `kubectl | jq` ↓ execution/cluster access unavailable, or jq/bundled filter missing 2. Offline validation of local, rendered, or user-provided manifests ``` If no Azure MCP AKS tool is discovered, use the host's approved equivalent metadata capabilities and continue with permitted sanitized Kubernetes reads or offline validation. A local or external MCP server is not a prerequisite. Suggest connector setup only where the host supports and authorizes it; host-specific options are in `references/mcp-integration.md`. Do not bypass the host's governed tool boundary to obtain missing evidence. #### Offline Mode Load `references/constraint-spec-v1.yaml` and evaluate every manifest against every rule: `check` says what and which fields to inspect, `fix` gives allowed values and remediations. Suggest needed fixes. Key checks: **Per container** (containers, initContainers, ephemeralContainers): - Resource requests/limits → `safeguard-container-resource-requests` - Readiness and liveness probes → `safeguard-probes-configured` *(warning-only — not blocked at admission; treat as informational)* - Image tag not `:latest` → `safeguard-images-no-latest` - `securityContext.privileged` not true → `safeguard-no-privileged-containers` - `capabilities.add` only adds allowed capabilities → `safeguard-container-capabilities` - `seccompProfile` is RuntimeDefault/Localhost → `safeguard-allowed-seccomp-profiles` - no `host` field in probes and lifecycle hooks → `safeguard-host-probes` *(advisory/unverified — not a documented Automatic block)* **Per pod spec:** - `hostPID`/`hostIPC` not true → `safeguard-block-host-namespaces` (incompatible) - `hostNetwork`/`hostPort` not true → `safeguard-host-network-ports` (incompatible) - No `hostPath` volumes → `safeguard-no-host-path-volumes` (incompatible) **Conditional (`conditionalSafeguards` — report only when applicable, never as default blockers):** - `allowPrivilegeEscalation`, run-as-non-root, allowed volume types → PSS Restricted opt-in only (Learn marks these "PSS Restricted Only") - Windows `ContainerAdministrator` → Windows node pools only, when the constraint is active **Per workload type:** - Deployments/StatefulSets with replicas > 1: podAntiAffinity or topologySpreadConstraints → `safeguard-pod-enforce-antiaffinity` - StorageClass: CSI provisioner (not in-tree) → `safeguard-csi-driver-storage-class` ### Severity Classification | Severity | Meaning | Action | |----------|---------|--------| | `incompatible` | Fundamental architecture issue; cannot run on Automatic without redesign | Must fix before migration — flag prominently | | `requiresChanges` | Manifest changes needed; will be denied at admission | Generate fix diffs | | `autoFixed` | AKS Automatic will mutate this at admission; no user action needed | Informational — show what will change | | `informational` | Warning-only, advisory, or not enforced on the default Automatic Baseline | Mention briefly; never list as a blocker | | conditional (`enforcement: conditional`) | Enforced only under PSS Restricted, on Windows nodes, or when the cluster's active constraints include it | Report with its `appliesWhen` condition; confirm with `kubectl get constraints` when possible | ### Step 3: Present Findings Always start with the summary: ``` ## AKS Automatic Readiness Assessment | Status | Count | |--------|-------| | ✅ Compatible | X workloads | | ⚠️ Requires changes | Y workloads | | ❌ Incompatible | Z workloads | | 🔧 Auto-fixed by Automatic | W workloads | | 🏗️ Cluster config issues | N issues | ``` Grouping: ≤ 10 issues → list individually; > 10 → group by constraint ID. Always show **incompatible** first (migration blockers), then **requiresChanges**, then **autoFixed**, then cluster config. Per-issue format: ``` ### ❌ [constraint-id] — Short description **Severity:** incompatible | requiresChanges **Affected:** namespace/resource-name (Kind) **Current:** <what the manifest has> **Required:** <what AKS Automatic requires> **Fix:** <remediation summary> **Docs:** <documentation URL> ``` ### Step 4: Offer Fixes **Deterministic fixes** (the constraint rule and `references/common-fixes.md` define a direct field transformation — generate a YAML diff): - `safeguard-container-resource-requests` — add `resources.requests` - `safeguard-container-capabilities` — remove `capabilities.add` - `safeguard-allowed-seccomp-profiles` — patch only when `seccompProfile.type: Unconfined` is present - `safeguard-no-privilege-escalation` — set `allowPrivilegeEscalation: false` (only when the conditional rule applies) - `safeguard-enforce-apparmor` — add AppArmor annotation - `safeguard-csi-driver-storage-class` — replace in-tree provisioner Use patterns in `references/common-fixes.md` and generate a before/after diff. Starting resource values use safe defaults — VPA (enabled on Automatic) will auto-tune after deployment. **Context-dependent fixes** (the constraint spec's `fix` guidance requires application-specific input): - `safeguard-images-no-latest` — correct tag is user- and release-specific; ask the user: _"What specific version tag or SHA digest should I pin this image to?"_ Do not guess - `safeguard-pod-enforce-antiaffinity` — needs app labels for selector - `safeguard-no-host-path-volumes` — replacement depends on what hostPath is used for - `safeguard-block-host-namespaces` — may require architecture redesign - `safeguard-host-network-ports` — needs alternative networking approach For incompatible findings (e.g., hostPath volumes), explain the issue and propose alternatives. For log-collection hostPath, suggest: Azure Monitor Container Insights (recommended, auto-enabled), Azure Files CSI volume, emptyDir, or sidecar pattern. **Fix application flow:** 1. Generate the fix as a YAML diff 2. Show the diff with explanation 3. Wait for explicit approval: "apply", "edit", or "skip" 4. On approval, apply the change to the file 5. Move to the next finding If the user says "fix all" or "apply all deterministic fixes", first generate a single combined diff containing only the constraint rules with direct, context-independent transformations, show that combined diff with an explanation, and wait for one explicit approval before applying any writes. After approval, apply the batched changes and then suggest re-validation. ### Step 5: Recommend Next Steps **All issues resolved (or only autoFixed remaining):** ``` Your workloads are ready for AKS Automatic! Next steps: 1. Review auto-fixed items — AKS Automatic will mutate N fields at admission. 2. Apply cluster configuration changes (see cluster config issues above). 3. Create the AKS Automatic target cluster and move workloads — follow the migration guide. 4. Verify — after migration, check all workloads are running and healthy. ``` There is no documented in-place Standard → Automatic SKU switch; migration to Automatic is a new target cluster plus a workload move (the documented in-place path is Automatic → Standard, `--sku base`). See `references/migration-guide-summary.md` for supported journeys and the full checklist. **Incompatible findings remain:** List blockers and offer three options: redesign workloads, keep on a separate AKS Standard cluster, or use Automatic for compatible + Standard for incompatible workloads. **Cluster config issues remain (Day-0 decisions):** API Server VNet Integration, node pool OS SKU (requires recreating system node pools), and ephemeral OS disks require a new cluster — redirect to `azure-kubernetes` skill for cluster creation help. ## Error Handling | Error / Symptom | Likely Cause | Remediation | |-----------------|--------------|-------------| | No Azure MCP AKS capability in the host's tools | Host uses another approved surface or does not expose these reads | Use approved equivalent metadata reads, including governed ARM/Azure CLI capabilities, or continue offline. Suggest a connector only if the host supports and authorizes setup | | Discovered AKS capability has no readiness operation | Expected — the documented surface is cluster/node-pool reads only | Collect sanitized manifests via `kubectl \| jq` and evaluate the bundled spec locally | | Azure/Kubernetes read fails (401/403/404, no context) | Credentials, RBAC, scope, or wrong target | See `references/mcp-integration.md` (SRE Agent UAMI scope vs `az login` hosts); continue offline if unresolved | | `jq` or bundled sanitizer unavailable | Host cannot execute the sanitized pipeline | Use rendered manifests or an approved projecting host read. Install tools only where host policy and user authorization permit; never send raw cluster JSON to the model | | Helm chart uses Go templating — cannot evaluate | Template values not resolved | Ask for `helm template` output or values files | | Constraint spec version mismatch | Skill bundles spec v1.2.0 | Note version in output; recommend re-running after spec update | ## Reference Files | File | When to load | |------|--------------| | `references/constraint-spec-v1.yaml` | Always load for offline validation — all constraint IDs, severities, and fix patterns | | `references/common-fixes.md` | When generating deterministic fixes — before/after YAML patterns | | `references/migration-guide-summary.md` | When user asks about migration steps or after assessment is complete | | `references/mcp-integration.md` | When discovering Azure MCP capabilities, wiring the sanitized `kubectl` read, or debugging the fallback chain | | `scripts/sanitize-readiness-input.jq` | Allowlist projection for `kubectl -o json` output before it reaches the model (requires `jq`) | > ⚠️ **Warning:** This skill bundles **constraint spec v1.2.0** (rules dated 2026-03-15, reconciled 2026-09 against the Learn Deployment Safeguards page, Azure Policy initiative c047ea8e v3.0.0, and the AKS Automatic SKU migration article). It lists 23 customer-facing cluster constraints, 21 Baseline-level Deployment Safeguards rules (one advisory/unverified), 4 conditional Restricted/Windows rules, and 2 active mutators. Always note the spec version in assessment output and verify live enforcement with `kubectl get constraints` when a cluster is reachable.
Original on GitHubazure-kustoQuery and analyze data in Azure Data Explorer (Kusto/ADX) using KQL for log analytics, telemetry, and time series analysis. WHEN: KQL queries, Kusto database queries, Azure Data Explorer, ADX clusters, log analytics, time series data, IoT telemetry, anomaly detection.ReadClose
--- name: azure-kusto description: "Query and analyze data in Azure Data Explorer (Kusto/ADX) using KQL for log analytics, telemetry, and time series analysis. WHEN: KQL queries, Kusto database queries, Azure Data Explorer, ADX clusters, log analytics, time series data, IoT telemetry, anomaly detection." license: MIT metadata: author: Microsoft version: "1.2.2" --- # Azure Data Explorer (Kusto) Query & Analytics Execute KQL queries and manage Azure Data Explorer resources for fast, scalable big data analytics on log, telemetry, and time series data. ## Overview This skill enables querying and managing Azure Data Explorer (Kusto), a fast and highly scalable data exploration service optimized for log and telemetry data. Azure Data Explorer provides sub-second query performance on billions of records using the Kusto Query Language (KQL). Key capabilities: - **Query Execution**: Run KQL queries against massive datasets - **Schema Exploration**: Discover tables, columns, and data types - **Resource Management**: List clusters and databases - **Analytics**: Aggregations, time series, anomaly detection, machine learning ## Core Workflow 1. **Discover Resources**: List available clusters and databases in subscription. If the target table's location is unknown and multiple candidate clusters, databases, or Log Analytics workspaces exist, batch the search (see Pattern 6) and only report "not found" after all candidates are checked. 2. **Explore Schema**: Retrieve table structures to understand data model 3. **Query Data**: Execute KQL queries for analysis, filtering, aggregation 4. **Analyze Results**: Process query output for insights and reporting ## Query Patterns ### Pattern 1: Basic Data Retrieval Fetch recent records from a table with simple filtering. **Example KQL**: ```kql Events | where Timestamp > ago(1h) | take 100 ``` **Use for**: Quick data inspection, recent event retrieval ### Pattern 2: Aggregation Analysis Summarize data by dimensions for insights and reporting. **Example KQL**: ```kql Events | summarize count() by EventType, bin(Timestamp, 1h) | order by count_ desc ``` **Use for**: Event counting, distribution analysis, top-N queries ### Pattern 3: Time Series Analytics Analyze data over time windows for trends and patterns. **Example KQL**: ```kql Telemetry | where Timestamp > ago(24h) | summarize avg(ResponseTime), percentiles(ResponseTime, 50, 95, 99) by bin(Timestamp, 5m) | render timechart ``` **Use for**: Performance monitoring, trend analysis, anomaly detection ### Pattern 4: Join and Correlation Combine multiple tables for cross-dataset analysis. **Example KQL**: ```kql Events | where EventType == "Error" | join kind=inner ( Logs | where Severity == "Critical" ) on CorrelationId | project Timestamp, EventType, LogMessage, Severity ``` **Use for**: Root cause analysis, correlated event tracking ### Pattern 5: Schema Discovery Explore table structure before querying. **Tools**: `kusto_table_schema_get` **Use for**: Understanding data model, query planning ### Pattern 6: Batch Search Across Candidate Sources When a table's location is unknown and there are several candidate clusters, databases, or workspaces, batch read-only metadata discovery instead of querying candidates one at a time. List tables in each candidate database or workspace and match the exact table name before querying data. After confirming which sources contain the table, query those sources together when needed: ```kql union workspace('ws1').Requests, workspace('ws2').Requests | take 1 ``` **Use for**: Locating a table among many candidate resources without confusing an empty result with a missing table ## Key Data Fields When executing queries, common field patterns: - **Timestamp**: Time of event (datetime) - use `ago()`, `between()`, `bin()` for time filtering - **EventType/Category**: Classification field for grouping - **CorrelationId/SessionId**: For tracing related events - **Severity/Level**: For filtering by importance - **Dimensions**: Custom properties for grouping and filtering ## Result Format Query results include: - **Columns**: Field names and data types - **Rows**: Data records matching query - **Statistics**: Row count, execution time, resource utilization - **Visualization**: Chart rendering hints (timechart, barchart, etc.) ## KQL Best Practices **🔵 Query Patterns:** - Use `summarize` for aggregations instead of `count()` alone - Use `bin()` for time bucketing in time series - Use `project` to select only needed columns - Use `extend` to add calculated fields **🟡 Common Functions:** - `ago(timespan)`: Relative time (ago(1h), ago(7d)) - `between(start .. end)`: Range filtering - `startswith()`, `contains()`, `matches regex`: String filtering - `parse`, `extract`: Extract values from strings - `percentiles()`, `avg()`, `sum()`, `max()`, `min()`: Aggregations ## Best Practices - Filter early with time range filters to optimize query performance and use indexed columns first - Use `take` or `limit` for exploratory queries to avoid large result sets - Leverage `summarize` for aggregations instead of client-side processing - Store frequently-used queries as functions in the database - Use materialized views for repeated aggregations - Monitor query performance and resource consumption - Apply data retention policies to manage storage costs - Use streaming ingestion for real-time analytics (< 1 second latency) - Integrate with Azure Monitor for operational insights ## MCP Tools Used | Tool | Purpose | |------|---------| | `kusto_cluster_list` | List all Azure Data Explorer clusters in a subscription | | `kusto_database_list` | List all databases in a specific Kusto cluster | | `kusto_query` | Execute KQL queries against a Kusto database | | `kusto_table_schema_get` | Retrieve schema information for a specific table | **Required Parameters**: - `subscription`: Azure subscription ID or display name - `cluster`: Kusto cluster name (e.g., "mycluster") - `database`: Database name - `query`: KQL query string (for query operations) - `table`: Table name (for schema operations) **Optional Parameters**: - `resource-group`: Resource group name (for listing operations) - `tenant`: Azure AD tenant ID ## Fallback Strategy: Azure CLI Commands If Azure MCP Kusto tools fail, timeout, or are unavailable, use Azure CLI commands as fallback. ### CLI Command Reference | Operation | Azure CLI Command | |-----------|-------------------| | List clusters | `az kusto cluster list --resource-group <rg-name>` | | List databases | `az kusto database list --cluster-name <cluster> --resource-group <rg-name>` | | Show cluster | `az kusto cluster show --name <cluster> --resource-group <rg-name>` | | Show database | `az kusto database show --cluster-name <cluster> --database-name <db> --resource-group <rg-name>` | ### KQL Query via Azure CLI For queries, use the Kusto REST API or direct cluster URL: ```bash az rest --method post \ --url "https://<cluster>.<region>.kusto.windows.net/v1/rest/query" \ --body "{ \"db\": \"<database>\", \"csl\": \"<kql-query>\" }" ``` ### When to Fallback Switch to Azure CLI when: - MCP tool returns timeout error (queries > 60 seconds) - MCP tool returns "service unavailable" or connection errors - Authentication failures with MCP tools - Empty response when database is known to have data ## Common Issues - **Access Denied**: Verify database permissions (Viewer role minimum for queries) - **Query Timeout**: Optimize query with time filters, reduce result set, or increase timeout - **Syntax Error**: Validate KQL syntax - common issues: missing pipes, incorrect operators - **Empty Results**: Check time range filters (may be too restrictive), verify table name - **Table Location Unknown**: Use Pattern 6 to batch-search all candidate sources before concluding the data does not exist - **Cluster Not Found**: Check cluster name format (exclude ".kusto.windows.net" suffix) - **High CPU Usage**: Query too broad - add filters, reduce time range, limit aggregations - **Ingestion Lag**: Streaming data may have 1-30 second delay depending on ingestion method ## Use Cases - **Log Analytics**: Application logs, system logs, audit logs - **IoT Analytics**: Sensor data, device telemetry, real-time monitoring - **Security Analytics**: SIEM data, threat detection, security event correlation - **APM**: Application performance metrics, user behavior, error tracking - **Business Intelligence**: Clickstream analysis, user analytics, operational KPIsOriginal on GitHubazure-messagingTroubleshoot and resolve issues with Azure Messaging SDKs for Event Hubs and Service Bus. Covers connection failures, authentication errors, message processing issues, and SDK configuration problems. WHEN: event hub SDK error, service bus SDK issue, messaging connection failure, AMQP error, event processor host issue, message lock lost, message lock expired, lock renewal, lock renewal batch, send timeout, receiver disconnected, SDK troubleshooting, azure messaging SDK, event hub consumer, service bus queue issue, topic subscription error, enable logging event hub, service bus logging, eventhub python, servicebus java, eventhub javascript, servicebus dotnet, event hub checkpoint, event hub not receiving messages, service bus dead letter, batch processing lock, session lock expired, idle timeout, connection inactive, link detach, slow reconnect, session error, duplicate events, offset reset, receive batch.ReadClose
--- name: azure-messaging description: "Troubleshoot and resolve issues with Azure Messaging SDKs for Event Hubs and Service Bus. Covers connection failures, authentication errors, message processing issues, and SDK configuration problems. WHEN: event hub SDK error, service bus SDK issue, messaging connection failure, AMQP error, event processor host issue, message lock lost, message lock expired, lock renewal, lock renewal batch, send timeout, receiver disconnected, SDK troubleshooting, azure messaging SDK, event hub consumer, service bus queue issue, topic subscription error, enable logging event hub, service bus logging, eventhub python, servicebus java, eventhub javascript, servicebus dotnet, event hub checkpoint, event hub not receiving messages, service bus dead letter, batch processing lock, session lock expired, idle timeout, connection inactive, link detach, slow reconnect, session error, duplicate events, offset reset, receive batch." license: MIT metadata: author: Microsoft version: "1.2.1" --- # Azure Messaging SDK Troubleshooting ## Quick Reference | Property | Value | |----------|-------| | **Services** | Azure Event Hubs, Azure Service Bus | | **MCP Tools** | `mcp_azure_mcp_eventhubs`, `mcp_azure_mcp_servicebus` | | **Best For** | Diagnosing SDK connection, auth, and message processing issues | ## When to Use This Skill - SDK connection failures, auth errors, or AMQP link errors - Idle timeout, connection inactivity, or slow reconnection after disconnect - AMQP link detach or detach-forced errors - Message lock lost, message lock expired, lock renewal failures, or batch lock timeouts - Session lock lost, session lock expired, or session receiver errors - Event processor or message handler stops processing - Duplicate events or checkpoint offset resets - SDK configuration questions (retry, prefetch, batch size, receive batch behavior) ## MCP Tools | Tool | Command | Use | |------|---------|-----| | `mcp_azure_mcp_eventhubs` | Namespace/hub ops | List namespaces, hubs, consumer groups | | `mcp_azure_mcp_servicebus` | Queue/topic ops | List namespaces, queues, topics, subscriptions | | `mcp_azure_mcp_monitor` | `logs_query` | Query diagnostic logs with KQL | | `mcp_azure_mcp_resourcehealth` | `get` | Check service health status | | `mcp_azure_mcp_documentation` | Doc search | Search Microsoft Learn for troubleshooting docs | ## Diagnosis Workflow 1. **Identify the SDK and version** — Check the prompt for SDK and version clues; if not stated, proceed with diagnosis and ask later if needed 2. **Check resource health** — Use `mcp_azure_mcp_resourcehealth` to verify the namespace is healthy 3. **Review the error message** — Match against language-specific troubleshooting guide 4. **Look up documentation** — Use `mcp_azure_mcp_documentation` to search Microsoft Learn for the error or topic 5. **Check configuration** — Verify connection string, entity name, consumer group 6. **Recommend fix** — Apply remediation, citing documentation found ## Troubleshooting Guides Connectivity, SDK, and auth troubleshooting guides are located in the azure-diagnostics skill under `troubleshooting/messaging/`. ## References - Use `mcp_azure_mcp_documentation` to search Microsoft Learn for latest guidance.
Original on GitHubazure-preparePrepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.ReadClose
--- name: azure-prepare description: "Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure." license: MIT metadata: author: Microsoft version: "1.3.10" --- # Azure Prepare > **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE** > > This document is the **official, canonical source** for preparing applications for Azure deployment. You **MUST** follow these instructions exactly as written unless they contradict security policies given to you. When in doubt, present the conflicting instructions from this document and ask the user for explicit confirmation. Do not improvise, infer, or substitute steps. --- ## Triggers Activate this skill when user wants to: - Create a new application - Add services or components to an existing app - Make updates or changes to existing application - Modernize or migrate an application - Set up Azure infrastructure - Deploy to Azure or host on Azure - Create and deploy to Azure (including Terraform-based deployment requests) ## Rules 1. **Plan first — MANDATORY** — You MUST physically write an initial `.azure/deployment-plan.md` **skeleton in the workspace root directory** (not the session-state folder) **as your very first action** — before any code generation or execution begins. Write the skeleton immediately, then populate it progressively as Phase 1 analysis and research unfold; finalize it with all decisions at Phase 1 Step 6. This file must exist on disk throughout. azure-validate and azure-deploy depend on it and will fail without it. Do not skip or defer this step. 2. **Get approval** — Present plan to user before execution 3. **Research before generating** — Load references and invoke related skills 4. **Update plan progressively** — Mark steps complete as you go 5. **Validate before deploy** — Invoke azure-validate before azure-deploy 6. **Confirm Azure context** — Use `ask_user` for subscription and location per [Azure Context](references/azure-context.md) 7. ❌ **Destructive actions require `ask_user`** — [Global Rules](references/global-rules.md) 8. ⛔ **NEVER delete user project or workspace directories** — When adding features to an existing project, MODIFY existing files. `azd init -t <template>` is for NEW projects only; do NOT run `azd init -t` in an existing workspace. Plain `azd init` (without a template argument) may be used in existing workspaces when appropriate. File deletions within a project (e.g., removing build artifacts or temp files) are permitted when appropriate, but NEVER delete the user's project or workspace directory itself. See [Global Rules](references/global-rules.md). 9. **Scope: preparation only** — This skill generates infrastructure code and configuration files. Deployment execution (`azd up`, `azd deploy`, `terraform apply`) is handled by the **azure-deploy** skill, which provides built-in error recovery and deployment verification. 10. ⛔ **SQL Server Bicep: NEVER generate `administratorLogin` or `administratorLoginPassword`** — not in direct properties, not in conditional/ternary branches, not anywhere in the file. Always use Entra-only authentication (`azureADOnlyAuthentication: true`) unconditionally. See [references/services/sql-database/bicep.md](references/services/sql-database/bicep.md). 11. **Remove stale template IaC after conversion** — If you converted Bicep templates from the selected `azd` template into Terraform templates, remove the Bicep templates that were introduced by that `azd` template and are now fully replaced by Terraform equivalents. Do not remove user-authored Bicep files. Only remove those template-provided Bicep files after the Terraform IaC is complete and Terraform has been selected as the deployment path. Before handing off to azure-validate skill, keep only the IaC templates required by the chosen deployment path. --- ## ❌ PLAN-FIRST WORKFLOW — MANDATORY > **YOU MUST CREATE A PLAN BEFORE DOING ANY WORK** > > 1. **STOP** — Do not generate any code, infrastructure, or configuration yet > 2. **CREATE SKELETON** - Write an initial `.azure/deployment-plan.md` skeleton to disk **immediately** (before any code generation or execution begins), then populate it progressively as Phase 1 steps 1-5 reveal details; finalize it at Step 6 > 3. **CONFIRM** — Present the completed plan to the user and get approval > 4. **EXECUTE** — Only after approval, execute the plan step by step > > The `.azure/deployment-plan.md` file is the **source of truth** for this workflow and for azure-validate and azure-deploy skills. Without it, those skills will fail. > > ⚠️ **CRITICAL: `.azure/deployment-plan.md` must be WRITTEN TO DISK inside the workspace root** (e.g., `<workspace-root>/.azure/deployment-plan.md`), not in the session-state folder. Use a file-write tool to create this file. This is the deployment plan artifact read by azure-validate and azure-deploy. **You MUST create this file — do not proceed without it.** > ⚠️ **CRITICAL: You must create the file with the name `.azure/deployment-plan.md` as is**. You must not use other names such as `.azure/plan.md`. > > ⛔ **Critical:** Skipping the plan file creation will cause azure-validate and azure-deploy to fail. This requirement has no exceptions. --- ## ❌ STEP 0: Specialized Technology Check — MANDATORY FIRST ACTION **BEFORE starting Phase 1**, check if the user's prompt OR workspace codebase matches a specialized technology that has a dedicated skill with tested templates. If matched, **invoke that skill FIRST** — then resume azure-prepare for validation and deployment. ### Check 1: Prompt keywords | Prompt keywords | Invoke FIRST | |----------------|-------------| | Python + App Service (e.g., "deploy Python to App Service", "Flask on Azure App Service", "publish Python web app to App Service") | **python-appservice-deploy** | | Lambda, AWS Lambda, migrate AWS, migrate GCP, Lambda to Functions, migrate from AWS, migrate from GCP | **azure-cloud-migrate** | | Azure Functions, function app, serverless function, timer trigger, HTTP trigger, func new | Stay in **azure-prepare** — prefer Azure Functions templates in Step 4; for plan choice/cold starts see [hosting-plans.md](references/services/functions/hosting-plans.md) and [cold-start.md](references/services/functions/cold-start.md) | | APIM, API Management, API gateway, deploy APIM | Stay in **azure-prepare** — see [APIM Deployment Guide](references/apim.md) | | AI gateway, AI gateway policy, AI gateway backend, AI gateway configuration | **azure-aigateway** | | workflow, orchestration, multi-step, pipeline, fan-out/fan-in, saga, long-running process, durable, order processing | Stay in **azure-prepare** — select **durable** recipe in Step 4. **MUST** load [durable.md](references/services/functions/durable.md), [DTS reference](references/services/durable-task-scheduler/README.md), and [DTS Bicep patterns](references/services/durable-task-scheduler/bicep.md). | > ⚠️ Check the user's **prompt text** — not just existing code. Critical for greenfield projects with no codebase to scan. See [full routing table](references/specialized-routing.md). After the specialized skill completes, **resume azure-prepare** at Phase 1 Step 4 (Select Recipe) for remaining infrastructure, validation, and deployment. --- ## Phase 1: Planning (BLOCKING — Complete Before Any Execution) Create `.azure/deployment-plan.md` by completing these steps. Do NOT generate any artifacts until the plan is approved. | # | Action | Reference | |---|--------|-----------| | 0 | If the prompt matches a specialized technology with a dedicated skill, invoke that skill first | [specialized-routing.md](references/specialized-routing.md) | | 1 | **Analyze Workspace** — Determine mode: NEW, MODIFY, or MODERNIZE | [analyze.md](references/analyze.md) | | 2 | **Gather Requirements** — Classification, scale, budget | [requirements.md](references/requirements.md) | | 3 | **Scan Codebase** — Identify components, technologies, dependencies | [scan.md](references/scan.md) | | 4 | **Select Recipe** — Choose AZD (default), AZCLI, Bicep, or Terraform | [recipe-selection.md](references/recipe-selection.md) | | 5 | **Plan Architecture** — Select stack + map components to Azure services | [architecture.md](references/architecture.md) | | 6 | **Finalize Plan (MANDATORY)** - Use a file-write tool to finalize `.azure/deployment-plan.md` with all decisions from steps 1-5. Update the skeleton written at the start of Phase 1 with the complete content. The file must be fully populated before you present the plan to the user. | [plan-template.md](references/plan-template.md) | | 7 | **Present Plan** — Show plan to user and ask for approval | `.azure/deployment-plan.md` | | 8 | **Destructive actions require `ask_user`** | [Global Rules](references/global-rules.md) | --- > **❌ STOP HERE** — Do NOT proceed to Phase 2 until the user approves the plan. --- ## Phase 2: Execution (Only After Plan Approval) Execute the approved plan. Update `.azure/deployment-plan.md` status after each step. | # | Action | Reference | |---|--------|-----------| | 1 | **Research Components** — Load service references + invoke related skills | [research.md](references/research.md) | | 2 | **Confirm Azure Context** — Detect and confirm subscription + location and check the resource provisioning limit | [Azure Context](references/azure-context.md) | | 3 | **Generate Artifacts** — Create infrastructure and configuration files | [generate.md](references/generate.md) | | 4 | **Harden Security** — Apply security best practices | [security.md](references/security.md) | | 5 | **Functional Verification** — Verify the app works (UI + backend), locally if possible | [functional-verification.md](references/functional-verification.md) | | 6 | **⛔ Update Plan (MANDATORY before hand-off)** — Use the `edit` tool to change the Status in `.azure/deployment-plan.md` to `Ready for Validation`. You **MUST** complete this edit **BEFORE** invoking azure-validate. Do NOT skip this step. | `.azure/deployment-plan.md` | | 7 | **⛔ MANDATORY Hand Off** — Invoke **azure-validate** skill. Your preparation work is done. Do NOT run `azd up`, `azd deploy`, or any deployment command directly — all deployment execution is handled by azure-deploy after azure-validate completes. **PREREQUISITE:** Step 6 must be completed first — `.azure/deployment-plan.md` status must say `Ready for Validation`. | — | --- ## Outputs | Artifact | Location | |----------|----------| | **Plan** | `.azure/deployment-plan.md` | | Infrastructure | `./infra/` | | AZD Config | `azure.yaml` (AZD only) | | Dockerfiles | `src/<component>/Dockerfile` | --- ## SDK Quick References - **Azure Developer CLI**: [azd](references/sdk/azd-deployment.md) - **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md) - **App Configuration**: [Python](references/sdk/azure-appconfiguration-py.md) | [TypeScript](references/sdk/azure-appconfiguration-ts.md) | [Java](references/sdk/azure-appconfiguration-java.md) --- ## Next > **⛔ MANDATORY NEXT STEP — DO NOT SKIP** > > After completing preparation, you **MUST** invoke **azure-validate** before any deployment attempt. Do NOT skip validation. Do NOT go directly to azure-deploy. Do NOT run `azd up` or any deployment command directly. The workflow is: > > `azure-prepare` → `azure-validate` → `azure-deploy` > > **⛔ BEFORE invoking azure-validate**, you MUST use the `edit` tool to update `.azure/deployment-plan.md` status to `Ready for Validation`. If the plan status has not been updated, the validation will fail. > > This applies to ALL deployment scenarios including containerized apps, Container Apps, App Service, Azure Functions, static sites, and any other Azure target. No exceptions. > > Skipping validation leads to deployment failures. Be patient and follow the complete workflow for the highest success outcome. **→ Update plan status to `Ready for Validation`, then invoke azure-validate**
Original on GitHubazure-quotasCheck/manage Azure quotas and usage across providers. For deployment planning, capacity validation, region selection. WHEN: \"check quotas\", \"service limits\", \"current usage\", \"request quota increase\", \"quota exceeded\", \"validate capacity\", \"regional availability\", \"provisioning limits\", \"vCPU limit\", \"how many vCPUs available in my subscription\".ReadClose
--- name: azure-quotas description: "Check/manage Azure quotas and usage across providers. For deployment planning, capacity validation, region selection. WHEN: \"check quotas\", \"service limits\", \"current usage\", \"request quota increase\", \"quota exceeded\", \"validate capacity\", \"regional availability\", \"provisioning limits\", \"vCPU limit\", \"how many vCPUs available in my subscription\"." license: MIT metadata: author: Microsoft version: "1.2.2" --- # Azure Quotas - Service Limits & Capacity Management > **AUTHORITATIVE GUIDANCE** — Follow these instructions exactly for quota management and capacity validation. ## Overview **What are Azure Quotas?** Azure quotas (also called service limits) are the maximum number of resources you can deploy in a subscription. Quotas: - Prevent accidental over-provisioning - Ensure fair resource distribution across Azure - Represent **available capacity** in each region - Can be increased (adjustable quotas) or are fixed (non-adjustable) **Key Concept:** **Quotas = Resource Availability** If you don't have quota, you cannot deploy resources. Always check quotas when planning deployments or selecting regions. ## When to Use This Skill Invoke this skill when: - **Planning a new deployment** - Validate capacity before deployment - **Selecting an Azure region** - Compare quota availability across regions - **Troubleshooting quota exceeded errors** - Check current usage vs limits - **Requesting quota increases** - Submit increase requests via CLI or Portal - **Comparing regional capacity** - Find regions with available quota - **Validating provisioning limits** - Ensure deployment won't exceed quotas ## Quick Reference | **Property** | **Details** | |--------------|-------------| | **Primary Tool** | Azure CLI (`az quota`) - **USE THIS FIRST, ALWAYS** | | **Extension Required** | `az extension add --name quota` (MUST install first) | | **Key Commands** | `az quota list`, `az quota show`, `az quota usage list`, `az quota usage show` | | **Complete CLI Reference** | [commands.md](./references/commands.md) | | **Azure Portal** | [My quotas](https://portal.azure.com/#blade/Microsoft_Azure_Capacity/QuotaMenuBlade/myQuotas) - Use only as fallback | | **REST API** | Microsoft.Quota provider - **Unreliable, do NOT use first** | | **MCP Server** | `azure-quota` MCP server — **NEVER use this. It is unreliable. Always use `az quota` CLI instead.** | | **Required Permission** | Reader (view) or Quota Request Operator (manage) | > **⚠️ ALWAYS USE CLI FIRST** > > REST API and Portal can show misleading "No Limit" values — this does **not** mean unlimited capacity. It means the quota API doesn't support that resource type. Always start with `az quota` commands; fall back to [Azure service limits docs](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits) if CLI returns `BadRequest`. > > For complete CLI reference, see [commands.md](./references/commands.md). ## Quota Types | **Type** | **Adjustability** | **Approval** | **Examples** | |----------|-------------------|--------------|--------------| | **Adjustable** | Can increase via Portal/CLI/API | Usually auto-approved | VM vCPUs, Public IPs, Storage accounts | | **Non-adjustable** | Fixed limits | Cannot be changed | Subscription-wide hard limits | **Important:** Requesting quota increases is **free**. You only pay for resources you actually use, not for quota allocation. ## Understanding Resource Name Mapping **⚠️ CRITICAL:** There is **NO 1:1 mapping** between ARM resource types and quota resource names. ### Example Mappings | ARM Resource Type | Quota Resource Name | |-------------------|---------------------| | `Microsoft.App/managedEnvironments` | `ManagedEnvironmentCount` | | `Microsoft.Compute/virtualMachines` | `standardDSv3Family`, `cores`, `virtualMachines` | | `Microsoft.Network/publicIPAddresses` | `PublicIPAddresses`, `IPv4StandardSkuPublicIpAddresses` | ### Discovery Workflow **Never assume the quota resource name from the ARM type.** Always use this workflow: 1. **List all quotas** for the resource provider: ```bash az quota list --scope /subscriptions/<id>/providers/<ProviderNamespace>/locations/<region> ``` 2. **Match by `localizedValue`** (human-readable description) to find the relevant quota 3. **Use the `name` field** (not ARM resource type) in subsequent commands: ```bash az quota show --resource-name ManagedEnvironmentCount --scope ... az quota usage show --resource-name ManagedEnvironmentCount --scope ... ``` > **📖 Detailed mapping examples and workflow:** See [commands.md - Resource Name Mapping](./references/commands.md#resource-name-mapping) ## Scripts Pre-built scripts handle quota extension installation, usage queries, and capacity calculation. Use these instead of constructing commands manually. A single call returns limits, usage, and available capacity. | Script | Purpose | Usage | |--------|---------|-------| | `scripts/check-quota.ps1` | Returns limit, usage, and available capacity for all quotas (or a single quota when resource name is provided) | Primary script for quota checks | | `scripts/check-quota.sh` | Same as above (bash) | Primary script for quota checks | ## Core Workflows ### Workflow 1: Check Quota for a Specific Resource **Scenario:** Verify quota limits and current usage before deployment Run the script with the resource provider and region. It returns a table of **all** quotas with their limit, current usage, and available capacity in a single call: ```powershell .\scripts\check-quota.ps1 -ResourceProvider <provider> -Region <region> ``` ```bash ./scripts/check-quota.sh <provider> <region> ``` To check a single resource, add the resource name: ```powershell .\scripts\check-quota.ps1 -ResourceProvider <provider> -Region <region> -ResourceName <resource-name> ``` ```bash ./scripts/check-quota.sh <provider> <region> <resource-name> ``` **Example:** ```powershell .\scripts\check-quota.ps1 -ResourceProvider Microsoft.Compute -Region eastus ``` **Example Output:** | Resource | Region | Limit | Usage | Available | |----------|--------|-------|-------|-----------| | cores | eastus | 100 | 50 | 50 | | standardDSv3Family | eastus | 350 | 50 | 300 | | virtualMachines | eastus | 25000 | 5 | 24995 | | ... | ... | ... | ... | ... | > **📖 See also:** [az quota show](./references/commands.md#az-quota-show), [az quota usage show](./references/commands.md#az-quota-usage-show) ### Workflow 2: Compare Quotas Across Regions **Scenario:** Find the best region for deployment based on available capacity ```bash # Define candidate regions REGIONS=("eastus" "eastus2" "westus2" "centralus") VM_FAMILY="standardDSv3Family" SUBSCRIPTION_ID="<subscription-id>" # Check quota availability across regions for region in "${REGIONS[@]}"; do echo "=== Checking $region ===" # Get limit LIMIT=$(az quota show \ --resource-name $VM_FAMILY \ --scope "/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.Compute/locations/$region" \ --query "properties.limit.value" -o tsv) # Get current usage USAGE=$(az quota usage show \ --resource-name $VM_FAMILY \ --scope "/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.Compute/locations/$region" \ --query "properties.usages.value" -o tsv) # Calculate available AVAILABLE=$((LIMIT - USAGE)) echo "Region: $region | Limit: $LIMIT | Usage: $USAGE | Available: $AVAILABLE" done ``` > **📖 See also:** [commands.md](./references/commands.md#az-quota-show) for full scripted multi-region loop patterns ### Workflow 3: Request Quota Increase **Scenario:** Current quota is insufficient for deployment ```bash # Request increase for VM quota az quota update \ --resource-name standardDSv3Family \ --scope /subscriptions/<subscription-id>/providers/Microsoft.Compute/locations/eastus \ --limit-object value=500 \ --resource-type dedicated # Check request status az quota request status list \ --scope /subscriptions/<subscription-id>/providers/Microsoft.Compute/locations/eastus ``` **Approval Process:** - Most adjustable quotas are auto-approved within minutes - Some requests require manual review (hours to days) - Non-adjustable quotas require Azure Support ticket > **📖 See also:** [az quota update](./references/commands.md#az-quota-update), [az quota request status](./references/advanced-commands.md#az-quota-request-status-list) ### Workflow 4: List All Quotas for Planning **Scenario:** Understand all quotas for a resource provider in a region ```bash # List all compute quotas in East US (table format) az quota list \ --scope /subscriptions/<subscription-id>/providers/Microsoft.Compute/locations/eastus \ --output table # List all network quotas az quota list \ --scope /subscriptions/<subscription-id>/providers/Microsoft.Network/locations/eastus \ --output table # List all Container Apps quotas az quota list \ --scope /subscriptions/<subscription-id>/providers/Microsoft.App/locations/eastus \ --output table ``` > **📖 See also:** [az quota list](./references/commands.md#az-quota-list) ## Troubleshooting ### Common Errors | **Error** | **Cause** | **Solution** | |-----------|-----------|--------------| | REST API "No Limit" | Misleading — not unlimited | Use CLI instead; see warning in Quick Reference | | `ExtensionNotFound` | Quota extension not installed | `az extension add --name quota` | | `BadRequest` | Resource provider not supported by quota API | Check [service limits docs](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits) | | `MissingRegistration` | Microsoft.Quota provider not registered | `az provider register --namespace Microsoft.Quota` | | `QuotaExceeded` | Deployment would exceed quota | Request increase or choose different region | | `InvalidScope` | Incorrect scope format | Use pattern: `/subscriptions/<id>/providers/<namespace>/locations/<region>` | | CLI commands fail entirely | Auth, extension, or environment issue | Verify Azure CLI login (`az account show`), reinstall quota extension, check network. Do NOT use the `azure-quota` MCP server — it is unreliable. | ### Unsupported Resource Providers **Known unsupported providers:** - ❌ Microsoft.DocumentDB (Cosmos DB) - Use Portal or [Cosmos DB limits docs](https://learn.microsoft.com/en-us/azure/cosmos-db/concepts-limits) **Confirmed working providers:** - ✅ Microsoft.Compute (VMs, disks, cores) - ✅ Microsoft.Network (VNets, IPs, load balancers) - ✅ Microsoft.App (Container Apps) - ✅ Microsoft.Storage (storage accounts) - ✅ Microsoft.MachineLearningServices (ML compute) > **📖 See also:** [Troubleshooting Guide](./references/commands.md#troubleshooting) ## Additional Resources | Resource | Link | |----------|------| | **CLI Commands Reference** | [commands.md](./references/commands.md) - Complete syntax, parameters, examples | | **Azure Quotas Overview** | [Microsoft Learn](https://learn.microsoft.com/en-us/azure/quotas/quotas-overview) | | **Service Limits Documentation** | [Azure subscription limits](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits) | | **Azure Portal - My Quotas** | [Portal Link](https://portal.azure.com/#blade/Microsoft_Azure_Capacity/QuotaMenuBlade/myQuotas) | | **Request Quota Increases** | [How to request increases](https://learn.microsoft.com/en-us/azure/quotas/quickstart-increase-quota-portal) | ## Best Practices 1. ✅ **Always check quotas before deployment** - Prevent quota exceeded errors 2. ✅ **Run `az quota list` first** - Discover correct quota resource names 3. ✅ **Compare regions** - Find regions with available capacity 4. ✅ **Account for growth** - Request 20% buffer above immediate needs 5. ✅ **Use table output for overview** - `--output table` for quick scanning 6. ✅ **Monitor usage trends** - Set up alerts at 80% threshold (via Portal)Original on GitHubazure-reliabilityAssess and improve the reliability posture of PaaS Applications (Azure Functions and Azure App Service). Scans deployed resources for zone redundancy, ZRS storage, health probes, and multi-region failover. Presents a feature-pivoted checklist, then drives staged remediation (CLI or IaC patches) end-to-end with user confirmation. WHEN: \"assess reliability\", \"check reliability\", \"zone redundant\", \"multi-region failover\", \"high availability\", \"disaster recovery\", \"single points of failure\", \"reliability posture\", \"resiliency\".ReadClose
--- name: azure-reliability description: "Assess and improve the reliability posture of PaaS Applications (Azure Functions and Azure App Service). Scans deployed resources for zone redundancy, ZRS storage, health probes, and multi-region failover. Presents a feature-pivoted checklist, then drives staged remediation (CLI or IaC patches) end-to-end with user confirmation. WHEN: \"assess reliability\", \"check reliability\", \"zone redundant\", \"multi-region failover\", \"high availability\", \"disaster recovery\", \"single points of failure\", \"reliability posture\", \"resiliency\"." license: MIT metadata: author: Microsoft version: "1.1.2" --- # Azure Reliability Assessment & Configuration ## Quick Reference | Property | Details | |---|---| | Best for | Reliability posture assessment, zone redundancy enablement, multi-region failover setup | | Primary capabilities | Reliability assessment table, Zone Redundancy Configuration, Multi-Region IaC Generation | | Supported services | Azure Functions, App Service (Container Apps planned for a future version) | | MCP tools | Azure Resource Graph queries, Azure CLI commands | ## When to Use This Skill Activate this skill when user wants to: - "Assess my Function app's reliability" - "Assess my Web app's reliability" - "Check the reliability of my resource group" (App Service and Functions resources only) - "Is my app zone redundant?" (App Service and Functions resources only) - "Is my app service plan zone redundant?" - "Make my app zone redundant" (App Service and Functions resources only) - "Make my app service plan zone redundant" - "Set up multi-region failover for my app" (App Service and Functions resources only) - "Check my reliability posture" - "Find single points of failure" (App Service and Functions resources only) - "Enable high availability for my app" (App Service and Functions resources only) - "Check disaster recovery readiness" - "Improve my app's resilience" (App Service and Functions resources only) > **Scope note:** This skill currently covers **Azure Functions and Azure App Service** only. If the user asks about Azure Container Apps reliability, acknowledge that support is planned but not yet available, and only proceed with the parts that apply to App Service and Functions resources in scope. ## Prerequisites - Authentication: user is logged in to Azure via `az login` - Permissions: Reader access on target subscription/resource group (for assessment) - Permissions: Contributor access (for configuration changes) - Azure Resource Graph extension: `az extension add --name resource-graph` ## MCP Tools | Tool | Purpose | |------|---------| | `mcp_azure_mcp_extension_cli_generate` | Generate `az` CLI commands for resource queries and configuration | | `mcp_azure_mcp_subscription_list` | List available subscriptions | | `mcp_azure_mcp_group_list` | List resource groups | Primary query method: Azure Resource Graph via `az graph query` (requires `az extension add --name resource-graph`). ## Assessment Workflow ### Phase 1: Discover Resources 1. **Identify scope** — Ask user for resource group, subscription, or app name 2. **Query Azure Resource Graph** to discover all resources in scope 3. **Classify resources** by service type (Functions, Storage, etc.). If Container Apps is found, **note it but do not deep-dive**. **Important:** Always scope queries to the user's specified resource group or subscription. Add these filters to every Resource Graph query: - Resource group: `| where resourceGroup =~ '<rg-name>'` - Subscription: Use `--subscriptions <sub-id>` flag on `az graph query` - App name: `| where name =~ '<app-name>'` ### Phase 2: Assess Reliability Two-step assessment: **platform-level discovery first, then per-service deep dive.** **Step 1 — Platform discovery (find what's there).** Use these to enumerate resources in scope and detect cross-cutting reliability gaps: | Platform check | Reference | |---|---| | Zone redundancy — discovery | [references/zone-redundancy-checks.md](references/zone-redundancy-checks.md) | | Storage redundancy (cross-service) | [references/storage-redundancy-checks.md](references/storage-redundancy-checks.md) | | Multi-region & global load balancers | [references/multi-region-checks.md](references/multi-region-checks.md) | | Front Door / Traffic Manager / App Insights probes | [references/health-probe-checks.md](references/health-probe-checks.md) | **Step 2 — Per-service deep dive.** For each compute resource discovered in Step 1, load the matching service reference. The service reference is the single source of truth for that service's plan/SKU rules, assessment queries, CLI commands, IaC patches (Bicep + Terraform + AVM), and reporting hints. This skill version ships **only the Azure Functions and App Service** per-service references. Other compute services are listed below explicitly so the dispatch logic is unambiguous: if a resource matches an unsupported row, do **not** attempt to load a reference, fabricate CLI commands, or generate IaC patches for it. | Service detected | Reference | |---|---| | Azure Functions (`microsoft.web/serverfarms` with `kind contains 'functionapp'`) | [references/services/functions/reliability.md](references/services/functions/reliability.md) | | Azure App Service (non-Functions sites: `microsoft.web/sites` without `kind contains 'functionapp'`, `microsoft.web/serverfarms` without `kind contains 'functionapp'`) | [references/services/app-service/reliability.md](references/services/app-service/reliability.md) | | Azure Container Apps (`microsoft.app/containerapps`, `microsoft.app/managedenvironments`) | ⚪ Not yet shipped — planned for a future version | > **Handling unsupported services:** If a resource matches an unsupported row above, surface it in the discovery summary, mark it as `⚪ not assessed (planned)` in the Phase 3 table, and skip the per-service remediation steps for it. Do **not** attempt to fabricate CLI commands or IaC patches for those services. ### Phase 3: Generate Reliability Checklist Present findings as a **feature-pivoted** table: one row per reliability feature (Zone redundancy on compute, Zone-redundant storage, Health probes, Multi-region failover), with a single status indicator and the **specific resources** that are relevant to that feature. This avoids the noise of one-row-per-resource with mostly `n/a` cells. Do **not** assign numeric scores or grades. ``` 🔍 Reliability Assessment — {scope} ───────────────────────────────────────────────────────────────────────────────────────────── Reliability Feature Status Resources ───────────────────────────────────────────────────────────────────────────────────────────── Zone redundancy — compute 🔴 OFF • plan-web-ii5trxva2ark4 (P1v3) • plan-ii5trxva2ark4 (FC1) Zone-redundant storage 🔴 GRS • stii5trxva2ark4 (defaulted; no SKU set in IaC) Health probes 🔴 OFF • func-api-ii5trxva2ark4 — needs code change (FC1) • app-web-ii5trxva2ark4 — no health check path Multi-region failover 🔴 OFF • Single region (eastus) only — Front Door not configured ───────────────────────────────────────────────────────────────────────────────────────────── Want me to fix the 🔴 items? I'll do the quick wins first (App plan zone redundancy + health checks on supported plans), then ask before storage migration and multi-region setup. (yes/no) ``` **Rules for the table:** - **Four feature rows, in this order:** Zone redundancy — compute · Zone-redundant storage · Health probes · Multi-region failover. Omit a row entirely only if no resource in scope could ever apply to it. - **Status column** is one symbol + one short word, no other characters: - `🟢 ON` — feature is fully enabled across all relevant resources in scope - `🟡 PARTIAL` — some resources have it, some don't (or partial config like liveness-only) - `🔴 OFF` — feature is missing on all relevant resources - For storage, replace `OFF` with the current SKU when relevant (`🔴 LRS`, `🔴 GRS`, `🟢 ZRS`, `🟢 GZRS`). When no SKU is set in IaC, label as `🔴 GRS` (ARM/AVM default) and note that in the resource line. - **Resources column** lists only what's relevant to that feature, one bullet per resource: - For "needs fixing" resources, include a short inline reason (`(FC1)`, `(defaulted; no SKU set)`, `liveness only`, `needs code change (FC1)`). - For resources that are **already ON** for that feature, mention them on the same row with `— already ON` so the user sees credit for what's right. - **Do not** include `n/a`, `—`, or empty cells. If a feature doesn't apply to any resource in scope, drop the row. - **Do not** include numeric scores, grades, or point totals. - End the assessment with a **single yes/no question** that kicks off the staged remediation flow. Do not enumerate the per-resource fix list here — the user will see it after they say yes (Configuration Workflow Step 1). > **UX Note:** If the assessment finds the app **already has** all core reliability features (zone redundancy, ZRS/GZRS storage, health probes), skip the fix-it question and jump straight to Configuration Workflow [Step 3](#step-3-both-paths-multi-region-followup--ask-and-wait) (Multi-region follow-up). Do **NOT** start any multi-region work without explicit consent. ## Configuration Workflow When user wants to **fix** findings from the assessment: > **⛔ ALWAYS confirm with user before executing changes.** Show what will change, any cost implications, and any destructive actions (e.g., environment recreation). ### Step 1: Present Fix Plan + Choose Path After assessment, if user says "fix it" / "improve my reliability" / "enable zone redundancy": 1. List each fixable finding with the specific action 2. Flag any cost implications or breaking changes 3. **Ask user which path they want:** ``` I'll start with the quick wins (no downtime, fast): 1. ✏️ Enable zone redundancy on plan-ii5trxva2ark4 (Flex Consumption — no cost change) 2. ✏️ Set health check path to /api/health on func-api-ii5trxva2ark4 Then, separately, I'll ask if you want to upgrade storage: 3. 🕒 Upgrade stii5trxva2ark4 from LRS → ZRS (small cost increase, migration takes hours) — Required for full zone redundancy, but I'll confirm with you before starting. How would you like to apply these changes? A) Fix now — Run az CLI commands against your live resources (immediate, one-time) B) Patch my IaC — Update your Bicep/Terraform files so changes persist across deploys (If you use azd or Terraform, option B is recommended so `azd up` won't overwrite changes.) ``` ### Path A: Fix Now (CLI) Run fixes against live resources using `az` CLI commands. **Quick wins first, then ask before the slow storage migration.** The exact CLI commands per service live in the per-service references — pick the one(s) matching the resources discovered in Phase 2: | Fix | Reference | |---|---| | Enable zone redundancy / configure health probes (Functions) | [references/services/functions/reliability.md](references/services/functions/reliability.md) | | Enable zone redundancy / configure health probes (App Service) | [references/services/app-service/reliability.md](references/services/app-service/reliability.md) | | Upgrade storage replication (cross-service) | [references/configure-storage.md](references/configure-storage.md) | | Set up multi-region (cross-service) | [references/configure-multi-region.md](references/configure-multi-region.md) | | Platform overview / verification | [references/configure-zone-redundancy.md](references/configure-zone-redundancy.md), [references/configure-health-probes.md](references/configure-health-probes.md) | **Execution order — always quick wins first:** 1. **Zone redundancy on compute** (fast, in-place property update on the App's plan). 2. **Health probes** (Premium / Dedicated only — in-place; for FC1 / Consumption, follow the consent gate in [configure-health-probes.md](references/configure-health-probes.md)). 3. **Verify** the compute changes succeeded before doing anything else. 4. **⛔ STOP — Ask about storage upgrade.** Compute is now zone-redundant, but storage may still be LRS or GRS. Ask the user explicitly: ``` ✅ Compute is now zone-redundant. To be **fully zone-redundant**, your storage account also needs to be upgraded: • stii5trxva2ark4: currently `Standard_LRS` → needs `Standard_ZRS` ⚠️ This is a live storage redundancy conversion: • Takes hours to days depending on data volume • Small ongoing cost increase (~$0.01/GB/month more) • Only supported for Standard general-purpose v2 accounts Do you want me to start the storage migration now? (yes / no / later) ``` - **yes** → run `az storage account update --sku Standard_ZRS` (or `migration start` if needed); poll `az storage account show --query sku.name` until it reports `Standard_ZRS`. - **no / later** → leave storage as-is; note in the re-assessment that ZR storage remains a gap. 5. **Multi-region** — do NOT auto-run. Handled in **Step 3** below as an explicit follow-up after re-assessment. > **⚠️ Warning:** If the user uses `azd up` or `terraform apply` later, CLI-only changes may be overwritten by the IaC definitions. Recommend also patching IaC after CLI fixes. ### Path B: Patch IaC Update the user's Bicep or Terraform files so reliability settings are persistent. **Step 1: Detect IaC type** 1. Look for `infra/` folder in project root 2. If not found, check project root for `*.bicep` or `*.tf` files 3. If still not found, ask user: "Where are your IaC files located?" 4. Check for `*.bicep` files → use Bicep patching 5. Check for `*.tf` files → use Terraform patching 6. If both exist, ask user which to patch 7. If no IaC exists, fall back to Path A (CLI) and inform user **Step 2: Classify each fix by risk level** | Fix | Risk Level | What Happens | |-----|-----------|--------------| | Zone redundancy (App plan) | 🟢 Safe patch | In-place property update on next deploy | | Storage LRS → ZRS | 🟡 Pre-migration required | Live storage migration must complete before the IaC SKU change can deploy. **Never bundle with safe patches** — use the two-deploy flow in Steps 3–5. | | Health check path (Basic/Standard/Premium / Dedicated) | 🟢 Safe patch | In-place update, but causes app restart | | Health check path (FC1 / Consumption) | ⚪ Code-only — ask first | `healthCheckPath` is unsupported. Adding a health endpoint requires adding an HTTP-triggered `/api/health` function to **app code**. **Always ask the user for explicit consent before touching source code.** Do **not** patch IaC. | **Step 3: Apply patches in two deploys (quick wins first)** The IaC patching framework (detection, AVM-module guidance, deploy-order rule, storage SKU patch) lives in: | IaC Type | Framework reference | |---|---| | Bicep | [references/iac-patching-bicep.md](references/iac-patching-bicep.md) | | Terraform | [references/iac-patching-terraform.md](references/iac-patching-terraform.md) | The actual **per-service compute patches** (Function App plan ZR, App Service Plan ZR, etc.) live in the per-service references — load the matching service file from Phase 2 for the exact Bicep / Terraform / AVM snippets. Only Azure Functions and App Service have per-service references in this skill version; Container Apps is out of scope. **Deploy 1 — Quick wins only.** Patch the 🟢 Safe items (zone redundancy on the App Service/Function App plan, health probes on Basic/Standard/Premium / Dedicated). Do **NOT** include the storage SKU patch in this deploy. After patching, **the skill runs the deploy itself** (do not stop and tell the user to run it). Detect the deployment tool and confirm once before executing: ``` 📦 Patches applied to your IaC. Ready to deploy: Tool detected: azd (found azure.yaml) Command: azd up Proceed with deployment? (yes / no) ``` On **yes**, run the appropriate command, stream output back to the user, and continue to the next step on success: - AZD project (has `azure.yaml`): `azd up` - Bicep-only: `az deployment group create --resource-group <rg> --template-file infra/main.bicep --parameters @infra/main.parameters.json` - Terraform: `terraform plan -out tfplan` → (show plan summary) → `terraform apply tfplan` On **no**, stop and report the patched files; do not proceed to Step 4 / Re-Assess. If deployment fails, surface the error and stop — do not continue to the storage step. **⛔ STOP — Ask about storage upgrade before Deploy 2.** After Deploy 1 succeeds, ask the user explicitly: ``` ✅ Quick-win patches deployed. Compute is now zone-redundant. To be **fully zone-redundant**, your storage account also needs to be upgraded: • stii5trxva2ark4: currently `Standard_LRS` → needs `Standard_ZRS` ⚠️ This is a two-part change: 1. Live storage migration (`az storage account migration start`) — takes hours to days 2. A second deploy to update your IaC's storage SKU to match Do you want me to start the storage migration now? (yes / no / later) ``` - **yes** → the skill runs the migration command itself, polls until complete, then patches the storage SKU in IaC and runs **Deploy 2** (now a no-op confirmation). The user does not need to run anything manually. - **no / later** → leave the storage SKU patch unapplied. Note in the re-assessment that ZR storage remains a gap; suggest revisiting later. **Step 4: Storage migration (only if user said yes in Step 3)** The skill runs these commands itself — do not ask the user to run them. Show progress as you go: ``` 🔄 Starting storage migration (this can take up to 72 hours)... az storage account migration start --name stii5trxva2ark4 \ --resource-group rg-example --sku Standard_ZRS --no-wait Polling: az storage account show --name stii5trxva2ark4 --query sku.name ... ✅ Migration complete: sku.name = Standard_ZRS ``` For very long migrations, you may surface a checkpoint to the user ("this is still running, check back later") rather than blocking the entire conversation. **Step 5: Deploy 2 — storage SKU patch** After the migration completes, the skill patches the storage SKU in IaC and runs the same deploy command as Step 3 (e.g. `azd up`). This deploy is a no-op confirmation that the IaC matches the live state. Confirm once with the user before executing, then run it directly. ### Step 2 (both paths): Re-Assess After changes are applied (CLI) or deployed (IaC), automatically re-run the assessment and show the **same feature-pivoted table** as Phase 3, with each feature row's status updated to reflect the new state. Briefly call out what changed since the previous run. ``` 🔄 Reliability Re-Assessment — rg-eventhubs-python-jan13 (eastus) ─────────────────────────────────────────────────────────────────────────────────────── Reliability Feature Status Resources ─────────────────────────────────────────────────────────────────────────────────────── Zone redundancy — compute 🟢 ON • plan-ii5trxva2ark4 (FC1) — now ON • plan-web-ii5trxva2ark4 (P1v3) — now ON Zone-redundant storage 🟢 ZRS • stii5trxva2ark4 — GRS → ZRS Health probes 🟡 PARTIAL • func-api-ii5trxva2ark4 — still off (FC1, code change declined) • app-web-ii5trxva2ark4 — now ON Multi-region failover 🔴 OFF • Single region (eastus) only ─────────────────────────────────────────────────────────────────────────────────────── What changed: Function App and App Service plan zone redundancy, storage replication and health probes on App Service. (Multi-region offered next — see Step 3.) ``` ### Step 3 (both paths): Multi-region follow-up — ASK and WAIT Multi-region is a significant cost/complexity step. Do **NOT** start it automatically. After re-assessment, only if **all core single-region reliability features are 🟢 ON** (zone-redundant compute, ZRS/GZRS storage, health probes), explicitly ask the user and **wait for their response** before doing anything: ``` 🟢 Your app is now fully zone-redundant in {region}. The next step (optional) is multi-region failover with Azure Front Door: • Deploys compute + storage in a second region (paired region recommended) • Adds Azure Front Door for global load balancing with health-probe-driven failover • Protects against full region outages • Estimated additional cost: ~2x compute (active-passive); Front Door ~$35/month base Do you want me to set up multi-region failover now? (yes / no / later) ``` - **yes** → proceed with [references/configure-multi-region.md](references/configure-multi-region.md). Confirm secondary region choice with the user, then: 1. Generate the multi-region IaC (Bicep / Terraform additions for the secondary region + Front Door). 2. Confirm once with the user: `📦 Multi-region IaC generated. Ready to deploy with \`azd up\`. Proceed? (yes / no)` 3. On **yes**, **the skill runs the deploy itself** (`azd up` / `az deployment group create` / `terraform apply`) and streams output. Do not stop and tell the user to run it. 4. After successful deploy, run a final re-assessment so the user sees Multi-region failover flip to 🟢 ON. - **no / later** → leave the deployment as-is. Note that single-region zone-redundant is a reliable end state; multi-region can be revisited anytime. > **⛔ Do not skip the wait.** Do not generate multi-region IaC, deploy a Front Door, or modify any files until the user has explicitly said yes. If core reliability is not yet all 🟢, do **not** ask about multi-region — finish the core gaps first. ## Priority Classification | Priority | Criteria | Action | |---|---|---| | Critical | No zone redundancy AND production workload | Fix immediately | | High | LRS storage on zone-redundant compute | Fix within days | | Medium | No multi-region (single region but zone-redundant) | Plan for next sprint | | Low | Missing health probes or monitoring gaps | Track and fix | ## Error Handling | Error | Message | Remediation | |---|---|---| | Authentication required | "Please login" | Run `az login` and retry | | Access denied | "Forbidden" | Confirm Reader/Contributor role assignment | | Plan doesn't support ZR | "Upgrade required" | Inform user of plan upgrade path + cost delta | | Region doesn't support AZ | "Region limitation" | Suggest supported regions | ## Best Practices - Run reliability assessments after every significant infrastructure change - Test failover scenarios periodically (at least quarterly) ## Skill Boundaries | Action | This skill does | Hand off to | |---|---|---| | Assess reliability posture | ✅ Yes | — | | Recommend improvements | ✅ Yes | — | | Enable zone redundancy (CLI commands) | ✅ Yes | — | | Patch Bicep/Terraform for reliability | ✅ Yes | — | | Generate multi-region IaC | ✅ Yes (additions for the secondary region + Front Door) | `azure-prepare` for full new-app IaC scaffolding | | Deploy IaC for reliability changes | ✅ Yes (runs `azd up` / `terraform apply` / `az deployment` itself, after user confirmation) | `azure-deploy` for general/non-reliability deploys | | Validate pre-deployment | Reliability checks only | `azure-validate` for full validation |Original on GitHubazure-resource-lookupList, find, and show Azure resources across subscriptions or resource groups. Handles prompts like \"list the websites in my subscription\", \"list my web apps\", \"show my app services\", \"list virtual machines\", \"list my VMs\", \"show storage accounts\", \"find container apps\", and \"what resources do I have\". USE FOR: list websites, list web apps, list app services, show websites in subscription, resource inventory, find resources by tag, tag analysis, orphaned resource discovery (not for cost analysis), unattached disks, count resources by type, cross-subscription lookup, and Azure Resource Graph queries. DO NOT USE FOR: deploying/changing resources (use azure-deploy), cost optimization (use cost-optimization from the optional azure-cost plugin), or non-Azure clouds.ReadClose
--- name: azure-resource-lookup description: "List, find, and show Azure resources across subscriptions or resource groups. Handles prompts like \"list the websites in my subscription\", \"list my web apps\", \"show my app services\", \"list virtual machines\", \"list my VMs\", \"show storage accounts\", \"find container apps\", and \"what resources do I have\". USE FOR: list websites, list web apps, list app services, show websites in subscription, resource inventory, find resources by tag, tag analysis, orphaned resource discovery (not for cost analysis), unattached disks, count resources by type, cross-subscription lookup, and Azure Resource Graph queries. DO NOT USE FOR: deploying/changing resources (use azure-deploy), cost optimization (use cost-optimization from the optional azure-cost plugin), or non-Azure clouds." license: MIT metadata: author: Microsoft version: "1.2.3" --- # Azure Resource Lookup List, find, and discover Azure resources of any type across subscriptions and resource groups. Use Azure Resource Graph (ARG) for fast, cross-cutting queries when dedicated MCP tools don't cover the resource type. ## When to Use This Skill Use this skill when the user wants to: - **List resources** of any type (VMs, web apps, storage accounts, container apps, databases, etc.) - **Show resources** in a specific subscription or resource group - Query resources **across multiple subscriptions** or resource types - Find **orphaned resources** (unattached disks, unused NICs, idle IPs) - Discover resources **missing required tags** or configurations - Get a **resource inventory** spanning multiple types - Find resources in a **specific state** (unhealthy, failed provisioning, stopped) - Answer "**what resources do I have?**" or "**show me my Azure resources**" - **List web apps, websites, or App Services** > ⚠️ **Warning:** App Service / Web Apps have no dedicated MCP `list` command. Prompts like "list websites", "list web apps", or "list app services" **must** route through this skill to use Azure Resource Graph. > 💡 **Tip:** For single-resource-type queries, first check if a dedicated MCP tool can handle it (see routing table below). If none exists, use Azure Resource Graph. ## Quick Reference | Property | Value | |----------|-------| | **Query Language** | KQL (Kusto Query Language subset) | | **CLI Command** | `az graph query -q "<KQL>" -o table` | | **Extension** | `az extension add --name resource-graph` | | **MCP Tool** | `extension_cli_generate` with intent for `az graph query` | | **Best For** | Cross-subscription queries, orphaned resources, tag audits | ## MCP Tools | Tool | Purpose | When to Use | |------|---------|-------------| | `extension_cli_generate` | Generate `az graph query` commands | Primary tool — generate ARG queries from user intent | | `mcp_azure_mcp_subscription_list` | List available subscriptions | Discover subscription scope before querying | | `mcp_azure_mcp_group_list` | List resource groups | Narrow query scope | ## Workflow ### Step 1: Check for a Dedicated MCP Tool For single-resource-type queries, check if a dedicated MCP tool can handle it: | Resource Type | MCP Tool | Coverage | |---|---|---| | Virtual Machines | `compute` | ✅ Full — list, details, sizes | | Storage Accounts | `storage` | ✅ Full — accounts, blobs, tables | | Cosmos DB | `cosmos` | ✅ Full — accounts, databases, queries | | Key Vault | `keyvault` | ⚠️ Partial — secrets/keys only, no vault listing | | SQL Databases | `sql` | ⚠️ Partial — requires resource group name | | Container Registries | `acr` | ✅ Full — list registries | | Kubernetes (AKS) | `aks` | ✅ Full — clusters, node pools | | App Service / Web Apps | `appservice` | ❌ No list command — use ARG | | Container Apps | — | ❌ No MCP tool — use ARG | | Event Hubs | `eventhubs` | ✅ Full — namespaces, hubs | | Service Bus | `servicebus` | ✅ Full — queues, topics | If a dedicated tool is available with full coverage, use it. Otherwise proceed to Step 2. ### Step 2: Generate the ARG Query Use `extension_cli_generate` to build the `az graph query` command: ```yaml mcp_azure_mcp_extension_cli_generate intent: "query Azure Resource Graph to <user's request>" cli-type: "az" ``` See [Azure Resource Graph Query Patterns](references/azure-resource-graph.md) for common KQL patterns. ### Step 3: Execute and Format Results Run the generated command. Use `--query` (JMESPath) to shape output: ```bash az graph query -q "<KQL>" --query "data[].{name:name, type:type, rg:resourceGroup}" -o table ``` Use `--first N` to limit results. Use `--subscriptions` to scope. ## Error Handling | Error | Cause | Fix | |-------|-------|-----| | `resource-graph extension not found` | Extension not installed | `az extension add --name resource-graph` | | `AuthorizationFailed` | No read access to subscription | Check RBAC — need Reader role | | `BadRequest` on query | Invalid KQL syntax | Verify table/column names; use `=~` for case-insensitive type matching | | Empty results | No matching resources or wrong scope | Check `--subscriptions` flag; verify resource type spelling | ## Constraints - ✅ **Always** use `=~` for case-insensitive type matching (types are lowercase) - ✅ **Always** scope queries with `--subscriptions` or `--first` for large tenants - ✅ **Prefer** dedicated MCP tools for single-resource-type queries - ❌ **Never** use ARG for real-time monitoring (data has slight delay) - ❌ **Never** attempt mutations through ARG (read-only)Original on GitHubazure-resource-visualizerAnalyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. WHEN: create architecture diagram, visualize Azure resources, show resource relationships, generate Mermaid diagram, analyze resource group, diagram my resources, architecture visualization, resource topology, map Azure infrastructure.ReadClose
--- name: azure-resource-visualizer description: "Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. WHEN: create architecture diagram, visualize Azure resources, show resource relationships, generate Mermaid diagram, analyze resource group, diagram my resources, architecture visualization, resource topology, map Azure infrastructure." license: MIT metadata: author: Microsoft version: "1.2.3" --- # Azure Resource Visualizer - Architecture Diagram Generator A user may ask for help understanding how individual resources fit together, or to create a diagram showing their relationships. Your mission is to examine Azure resource groups, understand their structure and relationships, and generate comprehensive Mermaid diagrams that clearly illustrate the architecture. ## Core Responsibilities 1. **Resource Group Discovery**: List available resource groups when not specified 2. **Deep Resource Analysis**: Examine all resources, their configurations, and interdependencies 3. **Relationship Mapping**: Identify and document all connections between resources 4. **Diagram Generation**: Create detailed, accurate Mermaid diagrams 5. **Documentation Creation**: Produce clear markdown files with embedded diagrams ## Workflow Process ### Step 1: Resource Group Selection If the user hasn't specified a resource group: 1. Use your tools to query available resource groups. If you do not have a tool for this, use `az`. 2. Present a numbered list of resource groups with their locations 3. Ask the user to select one by number or name 4. Wait for user response before proceeding If a resource group is specified, validate it exists and proceed. ### Step 2: Resource Discovery & Analysis For bulk resource discovery across subscriptions, use Azure Resource Graph queries. See [Azure Resource Graph Queries](references/azure-resource-graph.md) for cross-subscription inventory and relationship discovery patterns. Once you have the resource group: 1. **Query all resources** in the resource group using Azure MCP tools or `az`. 2. **Analyze each resource** type and capture: - Resource name and type - SKU/tier information - Location/region - Key configuration properties - Network settings (VNets, subnets, private endpoints) - Identity and access (Managed Identity, RBAC) - Dependencies and connections 3. **Map relationships** by identifying: - **Network connections**: VNet peering, subnet assignments, NSG rules, private endpoints - **Data flow**: Apps → Databases, Functions → Storage, API Management → Backends - **Identity**: Managed identities connecting to resources - **Configuration**: App Settings pointing to Key Vaults, connection strings - **Dependencies**: Parent-child relationships, required resources > **Important**: You must only use placeholder names to represent secret values, such as keys, connection strings, Key Vault secrets, etc. Use meaningful placeholder names to represent each secret in the diagram. Never put secret values in the resource diagram. ### Step 3: Diagram Construction Create a **detailed Mermaid diagram** using the `graph TB` (top-to-bottom) or `graph LR` (left-to-right) format. See [example-diagram.md](./assets/example-diagram.md) for a complete sample architecture diagram. **Key Diagram Requirements:** - **Group by layer or purpose**: Network, Compute, Data, Security, Monitoring - **Include details**: SKUs, tiers, important settings in node labels (use `<br/>` for line breaks) - **Label all connections**: Describe what flows between resources (data, identity, network) - **Use meaningful node IDs**: Abbreviations that make sense (APP, FUNC, SQL, KV) - **Visual hierarchy**: Subgraphs for logical grouping - **Connection types**: - `-->` for data flow or dependencies - `-.->` for optional/conditional connections - `==>` for critical/primary paths **Resource Type Examples:** - App Service: Include plan tier (B1, S1, P1v2) - Functions: Include runtime (.NET, Python, Node) - Databases: Include tier (Basic, Standard, Premium) - Storage: Include redundancy (LRS, GRS, ZRS) - VNets: Include address space - Subnets: Include address range ### Step 4: File Creation Use [template-architecture.md](./assets/template-architecture.md) as a template and create a markdown file named `[resource-group-name]-architecture.md` with: 1. **Header**: Resource group name, subscription, region 2. **Summary**: Brief overview of the architecture (2-3 paragraphs) 3. **Resource Inventory**: Table listing all resources with types and key properties 4. **Architecture Diagram**: The complete Mermaid diagram 5. **Relationship Details**: Explanation of key connections and data flows 6. **Notes**: Any important observations, potential issues, or recommendations ## Operating Guidelines ### Quality Standards - **Accuracy**: Verify all resource details before including in diagram - **Completeness**: Don't omit resources; include everything in the resource group - **Clarity**: Use clear, descriptive labels and logical grouping - **Detail Level**: Include configuration details that matter for architecture understanding - **Relationships**: Show ALL significant connections, not just obvious ones ### Tool Usage Patterns 1. **Azure MCP Search**: - Use `intent="list resource groups"` to discover resource groups - Use `intent="list resources in group"` with group name to get all resources - Use `intent="get resource details"` for individual resource analysis - Use `command` parameter when you need specific Azure operations 2. **File Creation**: - Always create in workspace root or a `docs/` folder if it exists - Use clear, descriptive filenames: `[rg-name]-architecture.md` - Ensure Mermaid syntax is valid (test syntax mentally before output) 3. **Terminal (when needed)**: - Use Azure CLI for complex queries not available via MCP - Example: `az resource list --resource-group <name> --output json` - Example: `az network vnet show --resource-group <name> --name <vnet-name>` ### Constraints & Boundaries **Always Do:** - ✅ List resource groups if not specified - ✅ Wait for user selection before proceeding - ✅ Analyze ALL resources in the group - ✅ Create detailed, accurate diagrams - ✅ Include configuration details in node labels - ✅ Group resources logically with subgraphs - ✅ Label all connections descriptively - ✅ Create a complete markdown file with diagram **Never Do:** - ❌ Skip resources because they seem unimportant - ❌ Make assumptions about resource relationships without verification - ❌ Create incomplete or placeholder diagrams - ❌ Omit configuration details that affect architecture - ❌ Proceed without confirming resource group selection - ❌ Generate invalid Mermaid syntax - ❌ Modify or delete Azure resources (read-only analysis) ### Edge Cases & Error Handling - **No resources found**: Inform user and verify resource group name - **Permission issues**: Explain what's missing and suggest checking RBAC - **Complex architectures (50+ resources)**: Consider creating multiple diagrams by layer - **Cross-resource-group dependencies**: Note external dependencies in diagram notes - **Resources without clear relationships**: Group in "Other Resources" section ## Output Format Specifications ### Mermaid Diagram Syntax - Use `graph TB` (top-to-bottom) for vertical layouts - Use `graph LR` (left-to-right) for horizontal layouts (better for wide architectures) - Subgraph syntax: `subgraph "Descriptive Name"` - Node syntax: `ID["Display Name<br/>Details"]` - Connection syntax: `SOURCE -->|"Label"| TARGET` ### Markdown Structure - Use H1 for main title - Use H2 for major sections - Use H3 for subsections - Use tables for resource inventories - Use bullet lists for notes and recommendations - Use code blocks with `mermaid` language tag for diagrams ## Success Criteria A successful analysis includes: - ✅ Valid resource group identified - ✅ All resources discovered and analyzed - ✅ All significant relationships mapped - ✅ Detailed Mermaid diagram with proper grouping - ✅ Complete markdown file created - ✅ Clear, actionable documentation - ✅ Valid Mermaid syntax that renders correctly - ✅ Professional, architect-level output Your goal is to provide clarity and insight into Azure architectures, making complex resource relationships easy to understand through excellent visualization.
Original on GitHubazure-storageAzure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier, and tier comparison. Provides object storage, SMB file shares, async messaging, NoSQL key-value, and big data analytics. Includes lifecycle management. USE FOR: blob storage, file shares, queue storage, table storage, data lake, upload files, download blobs, storage accounts, access tiers, storage tiers, hot cool cold archive, storage tier comparison, when to use storage tiers, lifecycle management, Azure Storage concepts. DO NOT USE FOR: SQL databases, Cosmos DB (use azure-prepare), messaging with Event Hubs or Service Bus (use azure-messaging).ReadClose
--- name: azure-storage description: "Azure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier, and tier comparison. Provides object storage, SMB file shares, async messaging, NoSQL key-value, and big data analytics. Includes lifecycle management. USE FOR: blob storage, file shares, queue storage, table storage, data lake, upload files, download blobs, storage accounts, access tiers, storage tiers, hot cool cold archive, storage tier comparison, when to use storage tiers, lifecycle management, Azure Storage concepts. DO NOT USE FOR: SQL databases, Cosmos DB (use azure-prepare), messaging with Event Hubs or Service Bus (use azure-messaging)." license: MIT metadata: author: Microsoft version: "1.2.2" --- # Azure Storage Services ## Services | Service | Use When | MCP Tools | CLI | |---------|----------|-----------|-----| | Blob Storage | Objects, files, backups, static content | `azure__storage` | `az storage blob` | | File Shares | SMB file shares, lift-and-shift | - | `az storage file` | | Queue Storage | Async messaging, task queues | - | `az storage queue` | | Table Storage | NoSQL key-value (consider Cosmos DB) | - | `az storage table` | | Data Lake | Big data analytics, hierarchical namespace | - | `az storage fs` | ## MCP Server (Preferred) When Azure MCP is enabled: - `azure__storage` with command `storage_account_list` - List storage accounts - `azure__storage` with command `storage_container_list` - List containers in account - `azure__storage` with command `storage_blob_list` - List blobs in container - `azure__storage` with command `storage_blob_get` - Download blob content - `azure__storage` with command `storage_blob_put` - Upload blob content **If Azure MCP is not enabled:** In Copilot CLI or Claude Code, ask the user to run `/mcp` and enable Azure MCP; in other hosts, ask the user to enable Azure MCP through the host's MCP configuration. ## CLI Fallback ```bash # List storage accounts az storage account list --output table # List containers az storage container list --account-name ACCOUNT --output table # List blobs az storage blob list --account-name ACCOUNT --container-name CONTAINER --output table # Download blob az storage blob download --account-name ACCOUNT --container-name CONTAINER --name BLOB --file LOCAL_PATH # Upload blob az storage blob upload --account-name ACCOUNT --container-name CONTAINER --name BLOB --file LOCAL_PATH ``` ## Storage Account Tiers | Tier | Use Case | Performance | |------|----------|-------------| | Standard | General purpose, backup | Milliseconds | | Premium | Databases, high IOPS | Sub-millisecond | ## Blob Access Tiers | Tier | Access Frequency | Cost | |------|-----------------|------| | Hot | Frequent | Higher storage, lower access | | Cool | Infrequent (30+ days) | Lower storage, higher access | | Cold | Rare (90+ days) | Lower still | | Archive | Rarely (180+ days) | Lowest storage, rehydration required | ## Redundancy Options | Type | Durability | Use Case | |------|------------|----------| | LRS | 11 nines | Dev/test, recreatable data | | ZRS | 12 nines | Regional high availability | | GRS | 16 nines | Disaster recovery | | GZRS | 16 nines | Best durability | ## Service Details For deep documentation on specific services: - Blob storage patterns and lifecycle -> [Blob Storage documentation](https://learn.microsoft.com/azure/storage/blobs/storage-blobs-overview) - File shares and Azure File Sync -> [Azure Files documentation](https://learn.microsoft.com/azure/storage/files/storage-files-introduction) - Queue patterns and poison handling -> [Queue Storage documentation](https://learn.microsoft.com/azure/storage/queues/storage-queues-introduction) ## SDK Quick References For building applications with Azure Storage SDKs, see the condensed guides: - **Blob Storage**: [Python](references/sdk/azure-storage-blob-py.md) | [TypeScript](references/sdk/azure-storage-blob-ts.md) | [Java](references/sdk/azure-storage-blob-java.md) | [Rust](references/sdk/azure-storage-blob-rust.md) - **Queue Storage**: [Python](references/sdk/azure-storage-queue-py.md) | [TypeScript](references/sdk/azure-storage-queue-ts.md) - **File Shares**: [Python](references/sdk/azure-storage-file-share-py.md) | [TypeScript](references/sdk/azure-storage-file-share-ts.md) - **Data Lake**: [Python](references/sdk/azure-storage-file-datalake-py.md) - **Tables**: [Python](references/sdk/azure-data-tables-py.md) | [Java](references/sdk/azure-data-tables-java.md) For full package listing across all languages, see [SDK Usage Guide](references/sdk-usage.md). ## Azure SDKs For building applications that interact with Azure Storage programmatically, Azure provides SDK packages in multiple languages (.NET, Java, JavaScript, Python, Go, Rust). See [SDK Usage Guide](references/sdk-usage.md) for package names, installation commands, and quick start examples.
Original on GitHubazure-upgradeAssess and upgrade Azure workloads between plans, tiers, or SKUs, or modernize Azure SDK dependencies in source code. WHEN: upgrade Consumption to Flex Consumption, upgrade Azure Functions plan, change hosting plan, function app SKU, migrate App Service to Container Apps, modernize legacy Azure Java SDKs (com.microsoft.azure to com.azure), migrate Azure Cache for Redis (ACR/ACRE) to Azure Managed Redis (AMR).ReadClose
--- name: azure-upgrade description: "Assess and upgrade Azure workloads between plans, tiers, or SKUs, or modernize Azure SDK dependencies in source code. WHEN: upgrade Consumption to Flex Consumption, upgrade Azure Functions plan, change hosting plan, function app SKU, migrate App Service to Container Apps, modernize legacy Azure Java SDKs (com.microsoft.azure to com.azure), migrate Azure Cache for Redis (ACR/ACRE) to Azure Managed Redis (AMR)." license: MIT compatibility: python3.10+ metadata: author: Microsoft version: "1.2.3" --- # Azure Upgrade > This skill handles **assessment and automated upgrades** of existing Azure workloads from one Azure service, hosting plan, or SKU to another — all within Azure. This includes plan/tier upgrades (e.g. Consumption → Flex Consumption), cross-service migrations (e.g. App Service → Container Apps), and SKU changes. It also covers **Azure SDK for Java source-code modernization** (e.g. legacy Java `com.microsoft.azure.*` → modern `com.azure.*`). This is NOT for cross-cloud migration — use `azure-cloud-migrate` for that. ## Triggers | User Intent | Example Prompts | |-------------|-----------------| | Upgrade Azure Functions plan | "Upgrade my function app from Consumption to Flex Consumption" | | Discover Functions upgrade candidates | "What Consumption Function Apps do I have that can be upgraded to Flex Consumption?" | | Change hosting tier | "Move my function app to a better plan" | | Assess upgrade readiness | "Is my function app ready for Flex Consumption?" | | Automate plan migration | "Automate the steps to upgrade my Functions plan" | | Modernize legacy Azure Java SDK | "Migrate legacy Azure SDKs for Java", "Upgrade legacy Azure Java SDK", "Migrate my Java project from com.microsoft.azure to com.azure" | | Migrate Azure Cache for Redis (ACR/OSS) to Azure Managed Redis (AMR) | "Migrate my Redis cache to AMR", "ACR to AMR", "OSS to AMR", "Upgrade my Premium P2 cache to Managed Redis", "Pick an AMR SKU", "Convert my Redis IaC template to AMR" | | Migrate Azure Cache for Redis Enterprise (ACRE) to Azure Managed Redis (AMR) | "Migrate my Enterprise_E10 cache to AMR", "ACRE to AMR", "Update my ACRE IaC template for AMR", "Migrate EnterpriseFlash to AMR", "Migrate my geo-replicated Enterprise Redis" | ## Rules 1. Follow phases in order. Skip or defer work only when the selected scenario explicitly permits it, and record the reason in the migration status. 2. Generate an assessment before any upgrade operations 3. Load the scenario reference and follow its rules 4. Use `mcp_azure_mcp_get_azure_bestpractices` and `mcp_azure_mcp_documentation` MCP tools 5. Destructive actions require `ask_user` — [global-rules](references/global-rules.md) 6. Always confirm the target plan/SKU with the user before proceeding 7. **Propose a name for any new resource** (default: `<source>-<target-suffix>`, e.g. `<source>-flex` for Flex Consumption migrations) and **announce the proposed name to the user before creating it** so they can override without a blocking prompt. Same pattern applies to other newly-created resources (storage accounts, App Insights, etc.) — see the scenario reference for service-specific defaults. 8. **Windows Consumption → Flex source-change gate**: treat the source app as read-only by default. Immediately before every command that would change its settings, triggers, state, deployment, bindings, or existence, use `ask_user` to describe the exact change and obtain explicit approval. Approval is action-specific and cannot be reused for later source changes. 9. Never delete or stop the original app without explicit user confirmation 10. **Keep approval-gated workflows moving**: after each completed step, immediately perform the next read-only preflight. If the next action requires approval, invoke `ask_user` in the same turn — never stop after merely announcing the next step and wait for the user to re-engage. 11. All automation scripts must be idempotent and resumable ## Upgrade Scenarios | Source | Target | Reference | |--------|--------|-----------| | Azure Functions Consumption Plan (Linux) | Azure Functions Flex Consumption Plan | [workflow.md](references/services/functions/consumption-to-flex/linux/workflow.md) | | Azure Functions Consumption Plan (Windows) | Azure Functions Flex Consumption Plan | [workflow.md](references/services/functions/consumption-to-flex/windows/workflow.md) | | Legacy Azure Java SDK (`com.microsoft.azure.*`) | Modern Azure Java SDK (`com.azure.*`) | [languages/java/README.md](references/languages/java/README.md) | | Azure Cache for Redis (ACR/OSS) Basic/Standard/Premium | Azure Managed Redis (AMR) | [services/redis/redis-to-amr.md](references/services/redis/redis-to-amr.md) | | Azure Cache for Redis Enterprise (ACRE) / Enterprise Flash | Azure Managed Redis (AMR) | [services/redis/redis-to-amr.md](references/services/redis/redis-to-amr.md) | > **Functions Consumption-to-Flex routing:** For a named app, inspect its Azure platform and load only the matching Linux or Windows workflow. For subscription-wide discovery, evaluate both platforms: use `az functionapp flex-migration list` for Linux and the Windows workflow's manual discovery and compatibility checks for Windows. Label Windows results as candidates until per-app code compatibility is assessed. > SDK upgrade scenarios (e.g. Java legacy → modern) run a **source-code modernization flow** that is distinct from Azure service/plan/SKU upgrades: follow the scenario reference, **not** the Steps below. > No matching scenario? Use `mcp_azure_mcp_documentation` and `mcp_azure_mcp_get_azure_bestpractices` tools to research the upgrade path. ## MCP Tools | Tool | Purpose | |------|---------| | `mcp_azure_mcp_get_azure_bestpractices` | Get Azure best practices for the target service | | `mcp_azure_mcp_documentation` | Look up Azure documentation for upgrade scenarios | | `mcp_azure_mcp_appservice` | Query App Service and Functions plan details | | `mcp_azure_mcp_applicationinsights` | Verify monitoring configuration | ## Steps 1. **Identify** — Determine the source and target Azure plans/SKUs. Ask user to confirm. 2. **Assess** — Analyze existing app for upgrade readiness → load scenario reference (e.g., [workflow.md](references/services/functions/consumption-to-flex/linux/workflow.md)) 3. **Pre-migrate** — Collect settings, identities, configs from the existing app 4. **Upgrade** — Execute the automated upgrade steps (create new resources, migrate settings, deploy code) 5. **Validate** — Use the checks defined by the selected scenario: verify target resource state, applicable HTTP endpoints and non-HTTP triggers, and monitoring. If access restrictions or unavailable test resources prevent execution, record validation as deferred — never relax security automatically or report functional success. 6. **Ask User** — Offer performance validation and IaC updates. Offer source cleanup only when the selected scenario confirms production cutover and all cleanup prerequisites are complete. 7. **Hand off** to `azure-validate` for deep validation or `azure-deploy` for CI/CD setup Track progress in `<UPGRADE_DIR>/upgrade-status.md` — see [Artifact Output Policy](references/global-rules.md#artifact-output-policy) for path resolution. ## References - [Global Rules](references/global-rules.md) - [Workflow Details](references/workflow-details.md) - **Functions** - Linux - [Consumption to Flex Consumption](references/services/functions/consumption-to-flex/linux/workflow.md) - [Assessment](references/services/functions/consumption-to-flex/linux/assessment.md) - [Automation Scripts](references/services/functions/consumption-to-flex/linux/automation.md) - Windows - [Consumption to Flex Consumption](references/services/functions/consumption-to-flex/windows/workflow.md) - [Assessment](references/services/functions/consumption-to-flex/windows/assessment.md) - [Automation Scripts](references/services/functions/consumption-to-flex/windows/automation.md) - **Redis** - [Redis (ACR or ACRE) to AMR Migration](references/services/redis/redis-to-amr.md) — routes to dedicated [amr-migration-skill](https://github.com/AzureManagedRedis/amr-migration-skill) (ACR/OSS) or [acre-to-amr-migration-skill](https://github.com/AzureManagedRedis/acre-to-amr-migration-skill) (Enterprise) - **Java SDK Migration Templates** - [Plan Template](references/languages/java/templates/PLAN_TEMPLATE.md) - [Progress Template](references/languages/java/templates/PROGRESS_TEMPLATE.md) - [Summary Template](references/languages/java/templates/SUMMARY_TEMPLATE.md) ## Next After upgrade is validated, hand off to: - `azure-validate` — for thorough post-upgrade validation - `azure-deploy` — if the user wants to set up CI/CD for the new appOriginal on GitHubazure-validatePre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.ReadClose
--- name: azure-validate description: "Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment." license: MIT metadata: author: Microsoft version: "1.2.5" --- # Azure Validate > **AUTHORITATIVE GUIDANCE** — Follow these instructions exactly unless they contradict security policies given to you. > **⛔ STOP — PREREQUISITE CHECK REQUIRED** > > Before proceeding, verify this prerequisite is met: > > **azure-prepare** was invoked and completed → `.azure/deployment-plan.md` exists with status `Approved` or later > > If the plan is missing, **STOP IMMEDIATELY** and invoke **azure-prepare** first. > > The complete workflow ensures success: > > `azure-prepare` → `azure-validate` → `azure-deploy` ## Triggers - Check if app is ready to deploy - Validate azure.yaml or Bicep - Run preflight checks - Troubleshoot deployment errors ## Rules 1. Run after azure-prepare, before azure-deploy 2. All checks must pass—do not deploy with failures 3. ⛔ **Destructive actions require `ask_user`** — [global-rules](references/global-rules.md) ## Steps Run the workflow script and follow its instructions. It walks you through each validation step one at a time, recording progress in `.azure/validate-status.json`. Use [references/scripts/workflow.ps1](references/scripts/workflow.ps1) on Windows or [references/scripts/workflow.sh](references/scripts/workflow.sh) on macOS/Linux. Start by calling the script **without** the completed-step argument: ```bash pwsh references/scripts/workflow.ps1 -WorkspacePath <workspace-path> # macOS/Linux: bash references/scripts/workflow.sh --workspace-path <workspace-path> ``` Each run prints the next action and the value to pass next. Perform the action, then re-run with that value (`-CompletedStep <value>` for pwsh, `--completed-step <value>` for bash). Repeat until it reports the azure-validate workflow is complete. Read [references/recipes/README.md](references/recipes/README.md) and apply its Node.js runtime check for **every recipe** before provisioning or deployment. The steps also reference [role checks](references/role-verification.md). > **⛔ VALIDATION AUTHORITY** > > This skill is the officially verified way to set plan status to `Validated`. You MUST follow the script's instructions to completion before setting status to `Validated`. > Do NOT set status to `Validated` without doing so. --- > **⚠️ NEXT STEP — DEPENDS ON USER INTENT** > > After ALL validations pass, check whether the user asked to deploy: > - **If the user explicitly requested deployment**, you **MUST** invoke **azure-deploy** to execute it. Do NOT run `azd up`, `azd deploy`, or any deployment commands directly — let azure-deploy handle execution. > - **If the user only asked to validate or prepare** (not deploy), STOP after recording proof and setting status to `Validated`. Report the validation results and do NOT invoke azure-deploy. > > If any validation failed, fix the issues and re-run azure-validate before proceeding.
Original on GitHubcapacityDiscovers available Azure OpenAI model capacity across regions and projects. Analyzes quota limits, compares availability, and recommends optimal deployment locations based on capacity requirements. USE FOR: find capacity, check quota, where can I deploy, capacity discovery, best region for capacity, multi-project capacity search, quota analysis, model availability, region comparison, check TPM availability. DO NOT USE FOR: actual deployment (hand off to preset or customize after discovery), quota increase requests (direct user to Azure Portal), listing existing deployments.ReadClose
--- name: capacity description: "Discovers available Azure OpenAI model capacity across regions and projects. Analyzes quota limits, compares availability, and recommends optimal deployment locations based on capacity requirements. USE FOR: find capacity, check quota, where can I deploy, capacity discovery, best region for capacity, multi-project capacity search, quota analysis, model availability, region comparison, check TPM availability. DO NOT USE FOR: actual deployment (hand off to preset or customize after discovery), quota increase requests (direct user to Azure Portal), listing existing deployments." license: MIT metadata: author: Microsoft version: "1.0.0" --- # Capacity Discovery Finds available Azure OpenAI model capacity across all accessible regions and projects. Recommends the best deployment location based on capacity requirements. ## Quick Reference | Property | Description | |----------|-------------| | **Purpose** | Find where you can deploy a model with sufficient capacity | | **Scope** | All regions and projects the user has access to | | **Output** | Ranked table of regions/projects with available capacity | | **Action** | Read-only analysis — does NOT deploy. Hands off to preset or customize | | **Authentication** | Azure CLI (`az login`) | ## When to Use This Skill - ✅ User asks "where can I deploy gpt-4o?" - ✅ User specifies a capacity target: "find a region with 10K TPM for gpt-4o" - ✅ User wants to compare availability: "which regions have gpt-4o available?" - ✅ User got a quota error and needs to find an alternative location - ✅ User asks "best region and project for deploying model X" **After discovery → hand off to [preset](../preset/SKILL.md) or [customize](../customize/SKILL.md) for actual deployment.** ## Scripts Pre-built scripts handle the complex REST API calls and data processing. Use these instead of constructing commands manually. | Script | Purpose | Usage | |--------|---------|-------| | `scripts/discover_and_rank.ps1` | Full discovery: capacity + projects + ranking | Primary script for capacity discovery | | `scripts/discover_and_rank.sh` | Same as above (bash) | Primary script for capacity discovery | | `scripts/query_capacity.ps1` | Raw capacity query (no project matching) | Quick capacity check or version listing | | `scripts/query_capacity.sh` | Same as above (bash) | Quick capacity check or version listing | ## Workflow ### Phase 1: Validate Prerequisites ```bash az account show --query "{Subscription:name, SubscriptionId:id}" --output table ``` ### Phase 2: Identify Model and Version Extract model name from user prompt. If version is unknown, query available versions: ```powershell .\scripts\query_capacity.ps1 -ModelName <model-name> ``` ```bash ./scripts/query_capacity.sh <model-name> ``` This lists available versions. Use the latest version unless user specifies otherwise. ### Phase 3: Run Discovery Run the full discovery script with model name, version, and minimum capacity target: ```powershell .\scripts\discover_and_rank.ps1 -ModelName <model-name> -ModelVersion <version> -MinCapacity <target> ``` ```bash ./scripts/discover_and_rank.sh <model-name> <version> <min-capacity> ``` > 💡 The script automatically queries capacity across ALL regions, cross-references with the user's existing projects, and outputs a ranked table sorted by: meets target → project count → available capacity. ### Phase 3.5: Validate Subscription Quota After discovery identifies candidate regions, validate that the user's subscription actually has available quota in each region. Model capacity (from Phase 3) shows what the platform can support, but subscription quota limits what this specific user can deploy. ```powershell # For each candidate region from discovery results: $usageData = az cognitiveservices usage list --location <region> --subscription $SUBSCRIPTION_ID -o json 2>$null | ConvertFrom-Json # Check quota for each SKU the model supports # Quota names follow pattern: OpenAI.<SKU>.<model-name> $usageEntry = $usageData | Where-Object { $_.name.value -eq "OpenAI.<SKU>.<model-name>" } if ($usageEntry) { $quotaAvailable = $usageEntry.limit - $usageEntry.currentValue } else { $quotaAvailable = 0 # No quota allocated } ``` ```bash # For each candidate region from discovery results: usage_json=$(az cognitiveservices usage list --location <region> --subscription "$SUBSCRIPTION_ID" -o json 2>/dev/null) # Extract quota for specific SKU+model quota_available=$(echo "$usage_json" | jq -r --arg name "OpenAI.<SKU>.<model-name>" \ '.[] | select(.name.value == $name) | .limit - .currentValue') ``` **Annotate discovery results:** Add a "Quota Available" column to the ranked output from Phase 3: | Region | Available Capacity | Meets Target | Projects | Quota Available | |--------|-------------------|--------------|----------|-----------------| | eastus2 | 120K TPM | ✅ | 3 | ✅ 80K | | westus3 | 90K TPM | ✅ | 1 | ❌ 0 (at limit) | | swedencentral | 100K TPM | ✅ | 0 | ✅ 100K | Regions/SKUs where `quotaAvailable = 0` should be marked with ❌ in the results. If no region has available quota, hand off to the [quota skill](../../../quota/quota.md) for increase requests and troubleshooting. ### Phase 4: Present Results and Hand Off After the script outputs the ranked table (now annotated with quota info), present it to the user and ask: 1. 🚀 **Quick deploy** to top recommendation with defaults → route to [preset](../preset/SKILL.md) 2. ⚙️ **Custom deploy** with version/SKU/capacity/RAI selection → route to [customize](../customize/SKILL.md) 3. 📊 **Check another model** or capacity target → re-run Phase 2 4. ❌ Cancel ### Phase 5: Confirm Project Before Deploying Before handing off to preset or customize, **always confirm the target project** with the user. See the [Project Selection](../SKILL.md#project-selection-all-modes) rules in the parent router. If the discovery table shows a sample project for the chosen region, suggest it as the default. Otherwise, query projects in that region and let the user pick. ## Error Handling | Error | Cause | Resolution | |-------|-------|------------| | "No capacity found" | Model not available or all at quota | Hand off to [quota skill](../../../quota/quota.md) for increase requests and troubleshooting | | Script auth error | `az login` expired | Re-run `az login` | | Empty version list | Model not in region catalog | Try a different region: `./scripts/query_capacity.sh <model> "" eastus` | | "No projects found" | No AI Services resources | Guide to `project/create` skill or Azure Portal | ## Related Skills - **[preset](../preset/SKILL.md)** — Quick deployment after capacity discovery - **[customize](../customize/SKILL.md)** — Custom deployment after capacity discovery - **[quota](../../../quota/quota.md)** — For quota viewing, increase requests, and troubleshooting quota errors, defer to this skill instead of duplicating guidanceOriginal on GitHubcustomizeInteractive guided deployment flow for Azure OpenAI models with full customization control. Step-by-step selection of model version, SKU (GlobalStandard/Standard/ProvisionedManaged), capacity, RAI policy (content filter), and advanced options (dynamic quota, priority processing, spillover). USE FOR: custom deployment, customize model deployment, choose version, select SKU, set capacity, configure content filter, RAI policy, deployment options, detailed deployment, advanced deployment, PTU deployment, provisioned throughput. DO NOT USE FOR: quick deployment to optimal region (use preset).ReadClose
--- name: customize description: "Interactive guided deployment flow for Azure OpenAI models with full customization control. Step-by-step selection of model version, SKU (GlobalStandard/Standard/ProvisionedManaged), capacity, RAI policy (content filter), and advanced options (dynamic quota, priority processing, spillover). USE FOR: custom deployment, customize model deployment, choose version, select SKU, set capacity, configure content filter, RAI policy, deployment options, detailed deployment, advanced deployment, PTU deployment, provisioned throughput. DO NOT USE FOR: quick deployment to optimal region (use preset)." license: MIT metadata: author: Microsoft version: "1.0.1" --- # Customize Model Deployment Interactive guided workflow for deploying Azure OpenAI models with full customization control over version, SKU, capacity, content filtering, and advanced options. ## Quick Reference | Property | Description | |----------|-------------| | **Flow** | Interactive step-by-step guided deployment | | **Customization** | Version, SKU, Capacity, RAI Policy, Advanced Options | | **SKU Support** | GlobalStandard, Standard, ProvisionedManaged, DataZoneStandard | | **Best For** | Precise control over deployment configuration | | **Authentication** | Azure CLI (`az login`) | | **Tools** | Azure CLI, MCP tools (optional) | ## When to Use This Skill Use this skill when you need **precise control** over deployment configuration: - ✅ **Choose specific model version** (not just latest) - ✅ **Select deployment SKU** (GlobalStandard vs Standard vs PTU) - ✅ **Set exact capacity** within available range - ✅ **Configure content filtering** (RAI policy selection) - ✅ **Enable advanced features** (dynamic quota, priority processing, spillover) - ✅ **PTU deployments** (Provisioned Throughput Units) **Alternative:** Use `preset` for quick deployment to the best available region with automatic configuration. ### Comparison: customize vs preset | Feature | customize | preset | |---------|---------------------|----------------------------| | **Focus** | Full customization control | Optimal region selection | | **Version Selection** | User chooses from available | Uses latest automatically | | **SKU Selection** | User chooses (GlobalStandard/Standard/PTU) | GlobalStandard only | | **Capacity** | User specifies exact value | Auto-calculated (50% of available) | | **RAI Policy** | User selects from options | Default policy only | | **Region** | Current region first, falls back to all regions if no capacity | Checks capacity across all regions upfront | | **Use Case** | Precise deployment requirements | Quick deployment to best region | ## Prerequisites - Azure subscription with Cognitive Services Contributor or Owner role - Microsoft Foundry project resource ID (format: `/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}`) - Azure CLI installed and authenticated (`az login`) - Optional: Set `PROJECT_RESOURCE_ID` environment variable ## Workflow Overview ### Complete Flow (14 Phases) ``` 1. Verify Authentication 2. Get Project Resource ID 3. Verify Project Exists 4. Get Model Name (if not provided) 5. List Model Versions → User Selects 6. List SKUs for Version → User Selects 7. Get Capacity Range → User Configures 7b. If no capacity: Cross-Region Fallback → Query all regions → User selects region/project 8. List RAI Policies → User Selects 9. Configure Advanced Options (if applicable) 10. Configure Version Upgrade Policy 11. Generate Deployment Name 12. Review Configuration 13. Execute Deployment & Monitor ``` ### Fast Path (Defaults) If user accepts all defaults (latest version, GlobalStandard SKU, recommended capacity, default RAI policy, standard upgrade policy), deployment completes in ~5 interactions. --- ## Phase Summaries > ⚠️ **MUST READ:** Before executing any phase, load [references/customize-workflow.md](references/customize-workflow.md) for the full scripts and implementation details. The summaries below describe *what* each phase does — the reference file contains the *how* (CLI commands, quota patterns, capacity formulas, cross-region fallback logic). | Phase | Action | Key Details | |-------|--------|-------------| | **1. Verify Auth** | Check `az account show`; prompt `az login` if needed | Verify correct subscription is active | | **2. Get Project ID** | Read `PROJECT_RESOURCE_ID` env var or prompt user | ARM resource ID format required | | **3. Verify Project** | Parse resource ID, call `az cognitiveservices account show` | Extracts subscription, RG, account, project, region | | **4. Get Model** | List models via `az cognitiveservices account list-models` | User selects from available or enters custom name | | **5. Select Version** | Query versions for chosen model | Recommend latest; user picks from list | | **6. Select SKU** | Query model catalog + subscription quota, show only deployable SKUs | ⚠️ Never hardcode SKU lists — always query live data | | **7. Configure Capacity** | Query capacity API, validate min/max/step, user enters value | Cross-region fallback if no capacity in current region | | **8. Select RAI Policy** | Present content filter options | Default: `Microsoft.DefaultV2` | | **9. Advanced Options** | Dynamic quota (GlobalStandard), priority processing (PTU), spillover | SKU-dependent availability | | **10. Upgrade Policy** | Choose: OnceNewDefaultVersionAvailable / OnceCurrentVersionExpired / NoAutoUpgrade | Default: auto-upgrade on new default | | **11. Deployment Name** | Auto-generate unique name, allow custom override | Validates format: `^[\w.-]{2,64}$` | | **12. Review** | Display full config summary, confirm before proceeding | User approves or cancels | | **13. Deploy & Monitor** | `az cognitiveservices account deployment create`, poll status | Timeout after 5 min; show endpoint + portal link | --- ## Error Handling ### Common Issues and Resolutions | Error | Cause | Resolution | |-------|-------|------------| | **Model not found** | Invalid model name | List available models with `az cognitiveservices account list-models` | | **Version not available** | Version not supported for SKU | Select different version or SKU | | **Insufficient quota** | Capacity > available quota | Skill auto-searches all regions; fails only if no region has quota | | **SKU not supported** | SKU not available in region | Cross-region fallback searches other regions automatically | | **Capacity out of range** | Invalid capacity value | **PREVENTED**: Skill validates min/max/step at input (Phase 7) | | **Deployment name exists** | Name conflict | Auto-incremented name generation | | **Authentication failed** | Not logged in | Run `az login` | | **Permission denied** | Insufficient permissions | Assign Cognitive Services Contributor role | | **Capacity query fails** | API/permissions/network error | **DEPLOYMENT BLOCKED**: Will not proceed without valid quota data | ### Troubleshooting Commands ```bash # Check deployment status az cognitiveservices account deployment show --name <account> --resource-group <rg> --deployment-name <name> # List all deployments az cognitiveservices account deployment list --name <account> --resource-group <rg> -o table # Check quota usage az cognitiveservices usage list --name <account> --resource-group <rg> # Delete failed deployment az cognitiveservices account deployment delete --name <account> --resource-group <rg> --deployment-name <name> ``` --- ## Selection Guides & Advanced Topics > For SKU comparison tables, PTU sizing formulas, and advanced option details, load [references/customize-guides.md](references/customize-guides.md). **SKU selection:** GlobalStandard (production/HA) → Standard (dev/test) → ProvisionedManaged (high-volume/guaranteed throughput) → DataZoneStandard (data residency). **Capacity:** TPM-based SKUs range from 1K (dev) to 100K+ (large production). PTU-based use formula: `(Input TPM × 0.001) + (Output TPM × 0.002) + (Requests/min × 0.1)`. **Advanced options:** Dynamic quota (GlobalStandard only), priority processing (PTU only, extra cost), spillover (overflow to backup deployment). --- ## Related Skills - **preset** - Quick deployment to best region with automatic configuration - **microsoft-foundry** - Parent skill for all Microsoft Foundry operations - **[quota](../../../quota/quota.md)** — For quota viewing, increase requests, and troubleshooting quota errors, defer to this skill instead of duplicating guidance - **rbac** - Manage permissions and access control --- ## Notes - Set `PROJECT_RESOURCE_ID` environment variable to skip prompt - Not all SKUs available in all regions; capacity varies by subscription/region/model - Custom RAI policies can be configured in Azure Portal - Automatic version upgrades occur during maintenance windows - Use Azure Monitor and Application Insights for production deploymentsOriginal on GitHubdeploy-modelUnified Azure OpenAI model deployment skill with intelligent intent-based routing. Handles quick preset deployments, fully customized deployments (version/SKU/capacity/RAI policy), and capacity discovery across regions and projects. USE FOR: deploy model, deploy gpt, create deployment, model deployment, deploy openai model, set up model, provision model, find capacity, check model availability, where can I deploy, best region for model, capacity analysis. DO NOT USE FOR: listing existing deployments (use foundry_models_deployments_list MCP tool), deleting deployments, agent creation (use agent/create), project creation (use project/create).ReadClose
--- name: deploy-model description: "Unified Azure OpenAI model deployment skill with intelligent intent-based routing. Handles quick preset deployments, fully customized deployments (version/SKU/capacity/RAI policy), and capacity discovery across regions and projects. USE FOR: deploy model, deploy gpt, create deployment, model deployment, deploy openai model, set up model, provision model, find capacity, check model availability, where can I deploy, best region for model, capacity analysis. DO NOT USE FOR: listing existing deployments (use foundry_models_deployments_list MCP tool), deleting deployments, agent creation (use agent/create), project creation (use project/create)." license: MIT metadata: author: Microsoft version: "1.0.0" --- # Deploy Model > **Scope — read this first.** This skill creates model deployments **out-of-band** via Azure CLI / MCP / portal. For azd-managed Foundry projects (those scaffolded from `azd ai agent init`), declare deployments in `azure.yaml services.ai-project.deployments[]` instead — `azd ai agent init` writes the entry from the sample manifest and `azd provision` creates the deployment through Bicep. See [foundry-agent/create/create-hosted.md](../../foundry-agent/create/create-hosted.md) for the Golden Path. Use this skill only for: (a) Foundry projects not managed by an azd project, (b) ad-hoc deployments outside the azd lifecycle. Unified entry point for all Azure OpenAI model deployment workflows. Analyzes user intent and routes to the appropriate deployment mode. ## Quick Reference | Mode | When to Use | Sub-Skill | |------|-------------|-----------| | **Preset** | Quick deployment, no customization needed | [preset/SKILL.md](preset/SKILL.md) | | **Customize** | Full control: version, SKU, capacity, RAI policy | [customize/SKILL.md](customize/SKILL.md) | | **Capacity Discovery** | Find where you can deploy with specific capacity | [capacity/SKILL.md](capacity/SKILL.md) | ## Intent Detection Analyze the user's prompt and route to the correct mode: ``` User Prompt │ ├─ Simple deployment (no modifiers) │ "deploy gpt-4o", "set up a model" │ └─> PRESET mode │ ├─ Customization keywords present │ "custom settings", "choose version", "select SKU", │ "set capacity to X", "configure content filter", │ "PTU deployment", "with specific quota" │ └─> CUSTOMIZE mode │ ├─ Capacity/availability query │ "find where I can deploy", "check capacity", │ "which region has X capacity", "best region for 10K TPM", │ "where is this model available" │ └─> CAPACITY DISCOVERY mode │ └─ Ambiguous (has capacity target + deploy intent) "deploy gpt-4o with 10K capacity to best region" └─> CAPACITY DISCOVERY first → then PRESET or CUSTOMIZE ``` ### Routing Rules | Signal in Prompt | Route To | Reason | |------------------|----------|--------| | Just model name, no options | **Preset** | User wants quick deployment | | "custom", "configure", "choose", "select" | **Customize** | User wants control | | "find", "check", "where", "which region", "available" | **Capacity** | User wants discovery | | Specific capacity number + "best region" | **Capacity → Preset** | Discover then deploy quickly | | Specific capacity number + "custom" keywords | **Capacity → Customize** | Discover then deploy with options | | "PTU", "provisioned throughput" | **Customize** | PTU requires SKU selection | | "optimal region", "best region" (no capacity target) | **Preset** | Region optimization is preset's specialty | ### Multi-Mode Chaining Some prompts require two modes in sequence: **Pattern: Capacity → Deploy** When a user specifies a capacity requirement AND wants deployment: 1. Run **Capacity Discovery** to find regions/projects with sufficient quota 2. Present findings to user 3. Ask: "Would you like to deploy with **quick defaults** or **customize settings**?" 4. Route to **Preset** or **Customize** based on answer > 💡 **Tip:** If unsure which mode the user wants, default to **Preset** (quick deployment). Users who want customization will typically use explicit keywords like "custom", "configure", or "with specific settings". ## Project Selection (All Modes) Before any deployment, resolve which project to deploy to. This applies to **all** modes (preset, customize, and after capacity discovery). ### Resolution Order 1. **Check `PROJECT_RESOURCE_ID` env var** — if set, use it as the default 2. **Check user prompt** — if user named a specific project or region, use that 3. **If neither** — query the user's projects and suggest the current one ### Confirmation Step (Required) **Always confirm the target before deploying.** Show the user what will be used and give them a chance to change it: ``` Deploying to: Project: <project-name> Region: <region> Resource: <resource-group> Is this correct? Or choose a different project: 1. ✅ Yes, deploy here (default) 2. 📋 Show me other projects in this region 3. 🌍 Choose a different region ``` If user picks option 2, show top 5 projects in that region: ``` Projects in <region>: 1. project-alpha (rg-alpha) 2. project-beta (rg-beta) 3. project-gamma (rg-gamma) ... ``` > ⚠️ **Never deploy without showing the user which project will be used.** This prevents accidental deployments to the wrong resource. ## Pre-Deployment Validation (All Modes) Before presenting any deployment options (SKU, capacity), always validate both of these: 1. **Model supports the SKU** — query the model catalog to confirm the selected model+version supports the target SKU: ```bash az cognitiveservices model list --location <region> --subscription <sub-id> -o json ``` Filter for the model, extract `.model.skus[].name` to get supported SKUs. 2. **Subscription has available quota** — check that the user's subscription has unallocated quota for the SKU+model combination: ```bash az cognitiveservices usage list --location <region> --subscription <sub-id> -o json ``` Match by usage name pattern `OpenAI.<SKU>.<model-name>` (e.g., `OpenAI.GlobalStandard.gpt-4o`). Compute `available = limit - currentValue`. > ⚠️ **Warning:** Only present options that pass both checks. Do NOT show hardcoded SKU lists — always query dynamically. SKUs with 0 available quota should be shown as ❌ informational items, not selectable options. > 💡 **Quota management:** For quota increase requests, usage monitoring, and troubleshooting quota errors, defer to the [quota skill](../../quota/quota.md) instead of duplicating that guidance inline. ## Prerequisites All deployment modes require: - Azure CLI installed and authenticated (`az login`) - Active Azure subscription with deployment permissions - Microsoft Foundry project resource ID (or agent will help discover it via `PROJECT_RESOURCE_ID` env var) ## Sub-Skills - **[preset/SKILL.md](preset/SKILL.md)** — Quick deployment to optimal region with sensible defaults - **[customize/SKILL.md](customize/SKILL.md)** — Interactive guided flow with full configuration control - **[capacity/SKILL.md](capacity/SKILL.md)** — Discover available capacity across regions and projectsOriginal on GitHubdiscover-azure-skillsSearches the Azure skills catalog and recommends installable agent skills by matching an Azure task to skill metadata and plugin installation guidance. WHEN: before starting any task that involves an Azure or Microsoft-cloud service, product, or data source, when no currently loaded skill or tool already covers it.ReadClose
--- name: discover-azure-skills description: "Searches the Azure skills catalog and recommends installable agent skills by matching an Azure task to skill metadata and plugin installation guidance. WHEN: before starting any task that involves an Azure or Microsoft-cloud service, product, or data source, when no currently loaded skill or tool already covers it." license: MIT metadata: author: Microsoft version: "1.0.2" --- Follow these steps to discover the available azure skill matching the given task description. 1. List plugins List Azure plugin directories from the GitHub Contents API: https://api.github.com/repos/microsoft/azure-skills/contents/.github/plugins?ref=main In the result, each entry whose `type` is `dir` is a plugin directory. Skills are organized by plugins. 2. List skills For each plugin, list their skills from the GitHub Contents API: https://api.github.com/repos/microsoft/azure-skills/contents/.github/plugins/{plugin-dirname}/skills?ref=main In the result, each entry whose `type` is `dir` is a skill directory. Each skill has a SKILL.md file that explains what this skill should be used for. 3. Discover relevant skills Eliminate the skills that obviously aren't relevant by their names. Then for each remaining skill, read their description from the API: https://raw.githubusercontent.com/microsoft/azure-skills/main/.github/plugins/{plugin-dirname}/skills/{skill-name}/SKILL.md Use the descriptions to further eliminate skills that aren't relevant. 4. Discover the plugin name of the relevant skills For each relevant skill, discover their plugin name by reading the `plugin.json` from the GitHub Contents API: https://raw.githubusercontent.com/microsoft/azure-skills/main/.github/plugins/{plugin-dirname}/.plugin/plugin.json This is important because a plugin's name may be different from its directory name. The installation commands depend on the plugin's name. 5. Report the matched skills Report the matched skills and offer instructions to install them. Skills can be installed by installing their plugin. Read the installation instructions matching the agent client to offer the installation instructions. - [Copilot CLI](./references/install/copilot-cli.md) - [Claude Code](./references/install/claude-code.md) - [Other](./references/install/other.md)Original on GitHubentra-agent-idProvision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmi_path, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmi_path token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).ReadClose
--- name: entra-agent-id description: "Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmi_path, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmi_path token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry)." license: MIT metadata: author: Microsoft version: "1.1.1" --- # Microsoft Entra Agent ID Create and manage OAuth 2.0-capable identities for AI agents using Microsoft Graph. Every agent instance gets a distinct identity, audit trail, and independently-scoped permission grants. ## Quick Reference | Property | Value | |----------|-------| | Service | Microsoft Entra Agent ID | | API | Microsoft Graph (`https://graph.microsoft.com/v1.0`) | | Required role | Agent Identity Developer, Agent Identity Administrator, or Application Administrator | | Object model | Blueprint (application) → BlueprintPrincipal (SP) → Agent Identity (SP) | | Runtime exchange | Two-step `fmi_path` exchange (autonomous and OBO) | | .NET helper | `Microsoft.Identity.Web.AgentIdentities` | | Polyglot helper | Microsoft Entra SDK for AgentID (sidecar container) | ## When to Use This Skill - Provisioning a new Agent Identity Blueprint and BlueprintPrincipal - Creating per-instance Agent Identities under a Blueprint - Configuring credentials (FIC, Managed Identity, or client secret) on the Blueprint - Implementing the two-step `fmi_path` runtime token exchange (autonomous or OBO) - Cross-tenant agent token flows - Deploying the Microsoft Entra SDK for AgentID sidecar for polyglot agents (Python, Node, Go, Java) - Granting per-Agent-Identity application (`appRoleAssignments`) or delegated (`oauth2PermissionGrants`) permissions - Diagnosing Agent ID errors such as `AADSTS82001`, `AADSTS700211`, or `PropertyNotCompatibleWithAgentIdentity` ## MCP Tools | Tool | Use | |------|-----| | `mcp_azure_mcp_documentation` | Search Microsoft Learn for current Agent ID setup, Graph API shapes, and SDK configuration | There is no dedicated Agent Identity MCP server today. This skill guides direct Microsoft Graph API calls (PowerShell or Python `requests`). Use `mcp_azure_mcp_documentation` to verify request bodies and endpoints against current docs before running. ## Before You Start Use the `mcp_azure_mcp_documentation` tool to search Microsoft Learn for current Agent ID documentation: - "Microsoft Entra Agent ID setup instructions" - "Microsoft Entra SDK for AgentID" Verify request bodies and endpoints against the installed SDK version — Graph API shapes evolve. ## Conceptual Model ``` Agent Identity Blueprint (application) ← one per agent type/project └── BlueprintPrincipal (service principal) ← MUST be created explicitly ├── Agent Identity (SP): agent-1 ← one per agent instance ├── Agent Identity (SP): agent-2 └── Agent Identity (SP): agent-3 ``` | Concept | Description | |---------|-------------| | **Blueprint** | Application object that defines a type/class of agent. Holds credentials (secret, certificate, federated identity). | | **BlueprintPrincipal** | Service principal for the Blueprint in the tenant. Not auto-created. | | **Agent Identity** | Service-principal-only identity for a single agent instance. Cannot hold its own credentials. | | **Sponsor** | A User (or Group, for Agent Identity) who is responsible for the identity. Required on creation. | ## Prerequisites ### Required Entra Roles One of: **Agent Identity Developer**, **Agent Identity Administrator**, or **Application Administrator**. ### PowerShell (interactive setup) ```powershell # PowerShell 7+ Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force ``` ### Python (programmatic provisioning) ```bash pip install azure-identity requests ``` ## Authentication > **`DefaultAzureCredential` is not supported.** Azure CLI tokens carry `Directory.AccessAsUser.All`, which Agent Identity APIs hard-reject (403). Use a dedicated app registration with `client_credentials`, or `Connect-MgGraph` with explicit delegated scopes. ### PowerShell (delegated) ```powershell Connect-MgGraph -Scopes @( "AgentIdentityBlueprint.Create", "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentityBlueprintPrincipal.Create", "AgentIdentity.Create.All", "User.Read" ) ``` ### Python (application) ```python import os, requests from azure.identity import ClientSecretCredential credential = ClientSecretCredential( tenant_id=os.environ["AZURE_TENANT_ID"], client_id=os.environ["AZURE_CLIENT_ID"], client_secret=os.environ["AZURE_CLIENT_SECRET"], ) token = credential.get_token("https://graph.microsoft.com/.default") GRAPH = "https://graph.microsoft.com/v1.0" headers = { "Authorization": f"Bearer {token.token}", "Content-Type": "application/json", "OData-Version": "4.0", } ``` ## Core Workflow ### Step 1: Create Agent Identity Blueprint Use the typed endpoint. Sponsors must be **Users** at Blueprint creation. This snippet assumes the `requests` client and `headers` dict from the Python authentication block above. ```python import subprocess import requests user_id = subprocess.run( ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"], capture_output=True, text=True, check=True, ).stdout.strip() blueprint_body = { "displayName": "My Agent Blueprint", "sponsors@odata.bind": [ f"https://graph.microsoft.com/v1.0/users/{user_id}" ], } resp = requests.post( f"{GRAPH}/applications/microsoft.graph.agentIdentityBlueprint", headers=headers, json=blueprint_body, ) resp.raise_for_status() blueprint = resp.json() app_id = blueprint["appId"] blueprint_obj_id = blueprint["id"] ``` ### Step 2: Create BlueprintPrincipal > Mandatory. Creating a Blueprint does NOT auto-create its service principal. Skipping this step produces: > `400: The Agent Blueprint Principal for the Agent Blueprint does not exist.` ```python sp_body = {"appId": app_id} resp = requests.post( f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal", headers=headers, json=sp_body, ) resp.raise_for_status() ``` Make your provisioning scripts idempotent — always check for the BlueprintPrincipal even when the Blueprint already exists. ### Step 3: Create Agent Identities Sponsors for an Agent Identity may be **Users or Groups**. ```python agent_body = { "displayName": "my-agent-instance-1", "agentIdentityBlueprintId": app_id, "sponsors@odata.bind": [ f"https://graph.microsoft.com/v1.0/users/{user_id}" ], } resp = requests.post( f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentity", headers=headers, json=agent_body, ) resp.raise_for_status() agent = resp.json() agent_sp_id = agent["id"] ``` ## Runtime Authentication Agents authenticate at runtime using credentials configured on the **Blueprint** (not on the Agent Identity — Agent Identities can't hold credentials). | Option | Use case | Credential on Blueprint | |--------|----------|------------------------| | **Managed Identity + WIF** | Production (Azure-hosted) | Federated Identity Credential | | **Client secret** | Local dev / testing | Password credential | | **Microsoft Entra SDK for AgentID** | Polyglot / 3P agents | Sidecar container acquires tokens over HTTP | For the two-step `fmi_path` exchange (parent token → per-Agent-Identity Graph token) that gives each agent instance a distinct `sub` claim and audit trail, see [references/runtime-token-exchange.md](references/runtime-token-exchange.md). For OBO (agent acting on behalf of a user), see [references/obo-blueprint-setup.md](references/obo-blueprint-setup.md). For the containerized polyglot auth sidecar (Python, Node, Go, Java — no SDK embedding), see [references/sdk-sidecar.md](references/sdk-sidecar.md). For MI+WIF and client-secret setup details, see [references/oauth2-token-flow.md](references/oauth2-token-flow.md). ### .NET quick path For .NET services, use **`Microsoft.Identity.Web.AgentIdentities`** — it handles Federated Identity Credential management and the two-step exchange for you. See the package README at `github.com/AzureAD/microsoft-identity-web` under `src/Microsoft.Identity.Web.AgentIdentities/`. ## Granting Permissions (Per Agent Identity) Agent Identities support both application permissions (autonomous) and delegated permissions (OBO). Grants are scoped **per Agent Identity**, not to the BlueprintPrincipal. ### Application permissions (autonomous) ```python graph_sp = requests.get( f"{GRAPH}/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'", headers=headers, ).json()["value"][0] user_read_all = next(r for r in graph_sp["appRoles"] if r["value"] == "User.Read.All") requests.post( f"{GRAPH}/servicePrincipals/{agent_sp_id}/appRoleAssignments", headers=headers, json={ "principalId": agent_sp_id, "resourceId": graph_sp["id"], "appRoleId": user_read_all["id"], }, ).raise_for_status() ``` ### Delegated permissions (OBO) ```python from datetime import datetime, timedelta, timezone expiry = (datetime.now(timezone.utc) + timedelta(days=3650)).strftime("%Y-%m-%dT%H:%M:%SZ") requests.post( f"{GRAPH}/oauth2PermissionGrants", headers=headers, json={ "clientId": agent_sp_id, "consentType": "AllPrincipals", "resourceId": graph_sp["id"], "scope": "User.Read Tasks.ReadWrite Mail.Send", "expiryTime": expiry, }, ).raise_for_status() ``` Browser-based admin consent URLs do not work for Agent Identities — use `oauth2PermissionGrants` for programmatic delegated consent. ## Cross-Tenant Agent Identities Blueprints can be multi-tenant (`signInAudience: AzureADMultipleOrgs`). When exchanging tokens cross-tenant: > **Step 1 of the parent token exchange MUST target the Agent Identity's home tenant**, not the Blueprint's. Wrong tenant → `AADSTS700211: No matching federated identity record found`. See [references/runtime-token-exchange.md](references/runtime-token-exchange.md) for full cross-tenant examples. ## API Reference | Operation | Method | Endpoint | |-----------|--------|----------| | Create Blueprint | `POST` | `/applications/microsoft.graph.agentIdentityBlueprint` | | Create BlueprintPrincipal | `POST` | `/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal` | | Create Agent Identity | `POST` | `/servicePrincipals/microsoft.graph.agentIdentity` | | Add FIC to Blueprint | `POST` | `/applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials` | | List Agent Identities | `GET` | `/servicePrincipals/microsoft.graph.agentIdentity` | | Grant app permission | `POST` | `/servicePrincipals/{id}/appRoleAssignments` | | Grant delegated permission | `POST` | `/oauth2PermissionGrants` | | Delete Agent Identity | `DELETE` | `/servicePrincipals/{id}` | | Delete Blueprint | `DELETE` | `/applications/{id}` | Base URL: `https://graph.microsoft.com/v1.0`. ## Required Graph Permissions | Permission | Purpose | |-----------|---------| | `AgentIdentityBlueprint.Create` | Create Blueprints | | `AgentIdentityBlueprint.ReadWrite.All` | Read/update Blueprints | | `AgentIdentityBlueprintPrincipal.Create` | Create BlueprintPrincipals | | `AgentIdentity.Create.All` | Create Agent Identities | | `AgentIdentity.ReadWrite.All` | Read/update Agent Identities | | `Application.ReadWrite.All` | Blueprint CRUD on application objects | | `AppRoleAssignment.ReadWrite.All` | Grant application permissions | | `DelegatedPermissionGrant.ReadWrite.All` | Grant delegated permissions | Grant admin consent (required for application permissions): ```bash az ad app permission admin-consent --id <client-id> ``` After admin consent, tokens may not include new claims for 30–120 seconds — retry with exponential backoff. ## Best Practices 1. **Always create BlueprintPrincipal after Blueprint** — not auto-created. 2. **Use typed endpoints** (`/applications/microsoft.graph.agentIdentityBlueprint`) instead of raw `/applications` with `@odata.type`. 3. **Credentials live on the Blueprint** — Agent Identities can't hold secrets/certs (`PropertyNotCompatibleWithAgentIdentity`). 4. **Include `OData-Version: 4.0`** on every Graph request. 5. **Use Workload Identity Federation for production** — client secrets only for local dev. 6. **Set `identifierUris: ["api://{appId}"]` on the Blueprint** before OAuth2 scope resolution. 7. **Never use Azure CLI tokens** for Agent Identity APIs — `Directory.AccessAsUser.All` causes hard 403. 8. **Use `fmi_path`** with `client_credentials` — NOT RFC 8693 `urn:ietf:params:oauth:grant-type:token-exchange` (returns `AADSTS82001`). 9. **Always use `/.default` scope** in both steps of the exchange — individual scopes fail. 10. **Step 1 targets the Agent Identity's home tenant** in cross-tenant flows. 11. **Grant permissions per Agent Identity**, not to the BlueprintPrincipal. 12. **Handle permission-propagation delays** — retry 403s with 30–120s backoff after admin consent. 13. **Keep the Entra SDK for AgentID on localhost** — never expose via LoadBalancer or Ingress. ## Troubleshooting | Error | Cause | Fix | |-------|-------|-----| | `AADSTS82001` | Used RFC 8693 token-exchange grant | Use `client_credentials` with `fmi_path` | | `AADSTS700211` | Step 1 parent token targeted wrong tenant | Target Agent Identity's home tenant | | `AADSTS50013` | OBO user token targets Graph, not Blueprint | Use `api://{blueprint_app_id}/access_as_user` | | `AADSTS65001` | Missing grant or used individual scopes | Use `/.default` and verify `oauth2PermissionGrants` | | `403 Authorization_RequestDenied` | No grant on this Agent Identity | Add via `appRoleAssignments` or `oauth2PermissionGrants` | | `PropertyNotCompatibleWithAgentIdentity` | Tried to add credential to Agent Identity SP | Put credentials on the Blueprint | | `Agent Blueprint Principal does not exist` | BlueprintPrincipal not created | Step 2 of the Core Workflow | | `AADSTS650051` on admin consent | SP already exists from partial consent | Grant directly via `appRoleAssignments` | ## References | File | Contents | |------|----------| | [references/runtime-token-exchange.md](references/runtime-token-exchange.md) | Two-step `fmi_path` exchange: autonomous + OBO, cross-tenant | | [references/oauth2-token-flow.md](references/oauth2-token-flow.md) | MI + WIF (production) and client secret (local dev) | | [references/obo-blueprint-setup.md](references/obo-blueprint-setup.md) | Configuring the Blueprint as an OAuth2 API for OBO | | [references/sdk-sidecar.md](references/sdk-sidecar.md) | Microsoft Entra SDK for AgentID — architecture, configuration, endpoints | | [references/sdk-sidecar-deployment.md](references/sdk-sidecar-deployment.md) | SDK code patterns (Python/TypeScript), Docker/Kubernetes manifests, security, troubleshooting | | [references/known-limitations.md](references/known-limitations.md) | Documented gaps organized by category | ### External Links | Resource | URL | |----------|-----| | Agent ID Setup Guide | https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-setup-instructions | | AI-Guided Setup | https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-ai-guided-setup | | Microsoft Entra SDK for AgentID | https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/overview | | Microsoft.Identity.Web.AgentIdentities (.NET) | https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.AgentIdentities/README.AgentIdentities.md |Original on GitHubentra-app-registrationGuides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.ReadClose
--- name: entra-app-registration description: "Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance." license: MIT metadata: author: Microsoft version: "1.2.1" --- ## Overview Microsoft Entra ID (formerly Azure Active Directory) is Microsoft's cloud-based identity and access management service. App registrations allow applications to authenticate users and access Azure resources securely. ### Key Concepts | Concept | Description | |---------|-------------| | **App Registration** | Configuration that allows an app to use Microsoft identity platform | | **Application (Client) ID** | Unique identifier for your application | | **Tenant ID** | Unique identifier for your Azure AD tenant/directory | | **Client Secret** | Password for the application (confidential clients only) | | **Redirect URI** | URL where authentication responses are sent | | **API Permissions** | Access scopes your app requests | | **Service Principal** | Identity created in your tenant when you register an app | ### Application Types | Type | Use Case | |------|----------| | **Web Application** | Server-side apps, APIs | | **Single Page App (SPA)** | JavaScript/React/Angular apps | | **Mobile/Native App** | Desktop, mobile apps | | **Daemon/Service** | Background services, APIs | ## Core Workflow ### Step 1: Register the Application Create an app registration in the Azure portal or using Azure CLI. **Portal Method:** 1. Navigate to Azure Portal → Microsoft Entra ID → App registrations 2. Click "New registration" 3. Provide name, supported account types, and redirect URI 4. Click "Register" **CLI Method:** See [references/cli-commands.md](references/cli-commands.md) **IaC Method:** See [references/BICEP-EXAMPLE.bicep](references/BICEP-EXAMPLE.bicep) It's highly recommended to use the IaC to manage Entra app registration if you already use IaC in your project, need a scalable solution for managing lots of app registrations or need fine-grained audit history of the configuration changes. ### Step 2: Configure Authentication Set up authentication settings based on your application type. - **Web Apps**: Add redirect URIs, enable ID tokens if needed - **SPAs**: Add redirect URIs, enable implicit grant flow if necessary - **Mobile/Desktop**: Use `http://localhost` or custom URI scheme - **Services**: No redirect URI needed for client credentials flow ### Step 3: Configure API Permissions Grant your application permission to access Microsoft APIs or your own APIs. **Common Microsoft Graph Permissions:** - `User.Read` - Read user profile - `User.ReadWrite.All` - Read and write all users - `Directory.Read.All` - Read directory data - `Mail.Send` - Send mail as a user **Details:** See [references/api-permissions.md](references/api-permissions.md) ### Step 4: Create Client Credentials (if needed) For confidential client applications (web apps, services), create a client secret, certificate or federated identity credential. **Client Secret:** - Navigate to "Certificates & secrets" - Create new client secret - Copy the value immediately (only shown once) - Store securely (Key Vault recommended) **Certificate:** For production environments, use certificates instead of secrets for enhanced security. Upload certificate via "Certificates & secrets" section. **Federated Identity Credential:** For dynamically authenticating the confidential client to Entra platform. ### Step 5: Implement OAuth Flow Integrate the OAuth flow into your application code. **See:** - [references/oauth-flows.md](references/oauth-flows.md) - OAuth 2.0 flow details - [references/console-app-example.md](references/console-app-example.md) - Console app implementation ## Common Patterns ### Pattern 1: First-Time App Registration Walk user through their first app registration step-by-step. **Required Information:** - Application name - Application type (web, SPA, mobile, service) - Redirect URIs (if applicable) - Required permissions **Script:** See [references/first-app-registration.md](references/first-app-registration.md) ### Pattern 2: Console Application with User Authentication Create a .NET/Python/Node.js console app that authenticates users. **Required Information:** - Programming language (C#, Python, JavaScript, etc.) - Authentication library (MSAL recommended) - Required permissions **Example:** See [references/console-app-example.md](references/console-app-example.md) ### Pattern 3: Service-to-Service Authentication Set up daemon/service authentication without user interaction. **Required Information:** - Service/app name - Target API/resource - Whether to use secret or certificate **Implementation:** Use Client Credentials flow (see [references/oauth-flows.md#client-credentials-flow](references/oauth-flows.md#client-credentials-flow)) ## MCP Tools and CLI ### Azure CLI Commands | Command | Purpose | |---------|---------| | `az ad app create` | Create new app registration | | `az ad app list` | List app registrations | | `az ad app show` | Show app details | | `az ad app permission add` | Add API permission | | `az ad app credential reset` | Generate new client secret | | `az ad sp create` | Create service principal | **Complete reference:** See [references/cli-commands.md](references/cli-commands.md) ### Microsoft Authentication Library (MSAL) MSAL is the recommended library for integrating Microsoft identity platform. **Supported Languages:** - .NET/C# - `Microsoft.Identity.Client` - JavaScript/TypeScript - `@azure/msal-browser`, `@azure/msal-node` - Python - `msal` **Examples:** See [references/console-app-example.md](references/console-app-example.md) ## Security Best Practices | Practice | Recommendation | |----------|---------------| | **Never hardcode secrets** | Use environment variables, Azure Key Vault, or managed identity | | **Rotate secrets regularly** | Set expiration, automate rotation | | **Use certificates over secrets** | More secure for production | | **Least privilege permissions** | Request only required API permissions | | **Enable MFA** | Require multi-factor authentication for users | | **Use managed identity** | For Azure-hosted apps, avoid secrets entirely | | **Validate tokens** | Always validate issuer, audience, expiration | | **Use HTTPS only** | All redirect URIs must use HTTPS (except localhost) | | **Monitor sign-ins** | Use Entra ID sign-in logs for anomaly detection | ## SDK Quick References - **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md) | [Rust](references/sdk/azure-identity-rust.md) - **Key Vault (secrets)**: [Python](references/sdk/azure-keyvault-py.md) | [TypeScript](references/sdk/azure-keyvault-secrets-ts.md) - **Auth Events**: [.NET](references/sdk/microsoft-azure-webjobs-extensions-authentication-events-dotnet.md) ## References - [OAuth Flows](references/oauth-flows.md) - Detailed OAuth 2.0 flow explanations - [CLI Commands](references/cli-commands.md) - Azure CLI reference for app registrations - [Console App Example](references/console-app-example.md) - Complete working examples - [First App Registration](references/first-app-registration.md) - Step-by-step guide for beginners - [API Permissions](references/api-permissions.md) - Understanding and configuring permissions - [Troubleshooting](references/troubleshooting.md) - Common issues and solutions ## External Resources - [Microsoft Identity Platform Documentation](https://learn.microsoft.com/entra/identity-platform/) - [OAuth 2.0 and OpenID Connect protocols](https://learn.microsoft.com/entra/identity-platform/v2-protocols) - [MSAL Documentation](https://learn.microsoft.com/entra/msal/) - [Microsoft Graph API](https://learn.microsoft.com/graph/)
Original on GitHubfinetuningFine-tune models on Microsoft Foundry using SFT (supervised), DPO (preference), or RFT (reinforcement with graders). Covers dataset preparation, training job submission, deployment, and evaluation. USE FOR: fine-tune, SFT, DPO, RFT, training data, grader, distillation, fine-tuned model, training job, large file upload, calibrate grader, deploy fine-tuned model, evaluate fine-tuned model. DO NOT USE FOR: general model deployment without fine-tuning (use deploy-model), agent creation (use agents), prompt optimization without training (use prompt-optimizer).ReadClose
--- name: finetuning description: "Fine-tune models on Microsoft Foundry using SFT (supervised), DPO (preference), or RFT (reinforcement with graders). Covers dataset preparation, training job submission, deployment, and evaluation. USE FOR: fine-tune, SFT, DPO, RFT, training data, grader, distillation, fine-tuned model, training job, large file upload, calibrate grader, deploy fine-tuned model, evaluate fine-tuned model. DO NOT USE FOR: general model deployment without fine-tuning (use deploy-model), agent creation (use agents), prompt optimization without training (use prompt-optimizer)." license: MIT metadata: author: Microsoft version: "0.0.0-placeholder" --- # Fine-Tuning on Microsoft Foundry Fine-tune models using SFT (supervised), DPO (preference), or RFT (reinforcement with graders). Covers dataset prep, training, deployment, and evaluation. ## When to Use Use this sub-skill when the user asks about: - Fine-tuning a model (SFT, DPO, or RFT) - Preparing, validating, or formatting training data - Submitting, monitoring, or diagnosing training jobs - Calibrating graders or pass thresholds for RFT - Deploying or evaluating a fine-tuned model - Choosing between training types (SFT vs DPO vs RFT) - Distillation, synthetic data generation, or dataset quality scoring - Large file uploads for training data - Cleaning up fine-tuning resources (files, deployments) **Do NOT use for:** General model deployment without fine-tuning (use deploy-model), agent creation (use agents), prompt optimization without training (use prompt-optimizer). ## Workflows | Stage | Guide | |-------|-------| | **Quick start** | [workflows/quickstart.md](workflows/quickstart.md) | | **Full pipeline** | [workflows/full-pipeline.md](workflows/full-pipeline.md) | | **Create data** | [workflows/dataset-creation.md](workflows/dataset-creation.md) | | **Iterate** | [workflows/iterative-training.md](workflows/iterative-training.md) | | **Diagnose** | [workflows/diagnose-poor-results.md](workflows/diagnose-poor-results.md) | ## References | Topic | File | |-------|------| | SFT vs DPO vs RFT | [references/training-types.md](references/training-types.md) | | Hyperparameters | [references/hyperparameters.md](references/hyperparameters.md) | | Data formats | [references/dataset-formats.md](references/dataset-formats.md) | | Grader design (RFT) | [references/grader-design.md](references/grader-design.md) | | Reward hacking | [references/reward-hacking.md](references/reward-hacking.md) | | Agentic RFT (tools) | [references/agentic-rft.md](references/agentic-rft.md) | | Deployment | [references/deployment.md](references/deployment.md) | | Training curves | [references/training-curves.md](references/training-curves.md) | | Evaluation | [references/evaluation.md](references/evaluation.md) | | Vision fine-tuning | [references/vision-fine-tuning.md](references/vision-fine-tuning.md) | | Large file uploads | [references/large-file-uploads.md](references/large-file-uploads.md) | | Platform gotchas | [references/platform-gotchas.md](references/platform-gotchas.md) | ## Scripts | Script | Purpose | |--------|---------| | `scripts/submit_training.py` | Submit SFT/DPO/RFT jobs | | `scripts/monitor_training.py` | Poll job until completion | | `scripts/calibrate_grader.py` | Find optimal RFT pass_threshold | | `scripts/check_training.py` | Analyze curves, list checkpoints | | `scripts/deploy_model.py` | Deploy via ARM REST API | | `scripts/evaluate_model.py` | LLM judge evaluation | | `scripts/convert_dataset.py` | Convert between SFT/DPO/RFT formats | | `scripts/generate_distillation_data.py` | Generate synthetic training data | | `scripts/score_dataset.py` | Quality scoring on training data | | `scripts/cleanup.py` | Delete old files and deployments | | `scripts/validate/` | Data validators (SFT, DPO, RFT) + stats | ## Rules 1. **Always baseline first** — evaluate the base model before fine-tuning 2. **Validate data** before submitting — run `scripts/validate/validate_sft.py` 3. **Calibrate RFT graders** — target 25-50% failure rate on the base model 4. **Evaluate checkpoints** — don't blindly deploy the final one 5. **Measure token cost** alongside accuracy when comparing models ## Quick Reference | Task | Command | |------|---------| | Validate SFT data | `python scripts/validate/validate_sft.py data.jsonl` | | Submit SFT job | `python scripts/submit_training.py --model gpt-4.1-mini --training-file train.jsonl --validation-file val.jsonl --type sft` | | Monitor job | `python scripts/monitor_training.py --job-id ftjob-xxx` | | Analyze curves | `python scripts/check_training.py --job-id ftjob-xxx` | | Deploy model | `python scripts/deploy_model.py --model-id ft:gpt-4.1-mini:... --name my-eval` | | Evaluate model | `python scripts/evaluate_model.py --deployment-name my-eval --test-file test.jsonl` | ## Error Handling | Error | Cause | Fix | |-------|-------|-----| | "API version not supported" | Older `openai` SDK on `/v1/` endpoint | Upgrade to `openai>=1.0` | | "does not support fine-tuning with Standard TrainingType" | OSS model needs `globalStandard` | Use `--use-rest` flag or script auto-falls back | | Job stuck in post-training eval | Under-provisioned tool endpoint (RFT) | Scale to S2+, enable Always On | | "DeploymentNotReady" after ARM succeeds | ARM/data-plane race condition | Delete and recreate deployment, wait 5 min | | Content safety block at deployment | PII-dense training data | Remove problematic document types |
Original on GitHubmicrosoft-foundryBuild, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).ReadClose
--- name: microsoft-foundry description: "Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare)." license: MIT metadata: author: Microsoft version: "1.2.36" --- # Microsoft Foundry Skill This skill helps developers work with Microsoft Foundry resources, covering model discovery and deployment, complete dev lifecycle of AI agent, evaluation workflows, and troubleshooting. ## Pre-Execution Requirements Follow each applicable subsection below before starting its corresponding action or workflow. ### Dependency Check and Setup **MANDATORY:** As the first step after this skill loads, run the dependency check and setup script below from this skill's root and wait for it to finish before continuing. The script checks first and installs only missing dependencies; it does not reinstall dependencies that are already available. **You MUST complete this check before reading or entering any sub-skill, workflow, or workflow-specific reference.** ```bash ./scripts/check-and-setup-dependencies.sh # macOS / Linux ./scripts/check-and-setup-dependencies.ps1 # Windows (pwsh) ``` Strictly follow the script output for subsequent actions. ### Workflow Guidance **MANDATORY:** Before executing ANY workflow-specific steps, you MUST read the corresponding sub-skill document. Do not call workflow-specific MCP tools for a workflow without reading its skill document. This applies even if you already know the MCP tool parameters — the skill document contains required workflow steps, pre-checks, and validation logic that must be followed. This rule applies on every new user message that triggers a different workflow, even if the skill is already loaded. ### Foundry MCP **MANDATORY:** Before using Foundry MCP operations, call the Azure MCP `foundry` tool and inspect the available Foundry MCP tools and related parameters. Treat this as the discovery/help step for MCP-based workflows. ### azd **MANDATORY:** Before executing ANY azd command, you MUST read [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) and strictly follow the shared rules defined in it, especially the `AZURE_DEV_USER_AGENT` setting rules. ## Sub-Skills This skill includes specialized sub-skills for specific workflows. **When a sub-skill matches the task, strictly follow its workflow:** | Sub-Skill | When to Use | Reference | |-----------|-------------|-----------| | **deploy** | Deploy hosted agents to Foundry, smoke-test a deployment, create or update prompt agents, and manage agent versions and multi-environment deploys. | [deploy](foundry-agent/deploy/deploy.md) | | **cicd** | Set up a CI/CD deployment pipeline for a Foundry agent. | [cicd](foundry-agent/cicd/cicd.md) | | **invoke** | Send messages to an agent, single or multi-turn conversations | [invoke](foundry-agent/invoke/invoke.md) | | **routine** | Schedule or event-trigger Foundry agents with routines; use `azd` for CRUD, enable/disable, manual dispatch, and viewing past runs, or define routines in `azure.yaml`. | [routine](foundry-agent/routine/routine.md) | | **invocations-ws** | Build, deploy, and connect to custom Hosted agents that use developer-defined duplex real-time or media streams over `invocations_ws`. | [invocations-ws](foundry-agent/invocations-ws/invocations-ws.md) | | **observe** | Evaluate agent quality, run batch evals, analyze failures, optimize prompts, improve agent instructions, compare versions, set up CI/CD monitoring, and enable continuous production evaluation | [observe](foundry-agent/observe/observe.md) | | **insights** | Pull generated agent insights, evidence, and recommendations from an existing monitor; read-only retrieval, not a new analysis run | [insights](foundry-agent/insights/insights.md) | | **trace** | Query traces, analyze latency/failures, correlate eval results to specific responses via App Insights `customEvents` | [trace](foundry-agent/trace/trace.md) | | **troubleshoot** | View hosted agent logs, query telemetry, diagnose failures | [troubleshoot](foundry-agent/troubleshoot/troubleshoot.md) | | **validate** | Use only when the user explicitly asks to use this validation sub-skill or to validate Microsoft Foundry hosted-agent code against best practices. Never invoke it proactively or add it to another workflow. | [validate](foundry-agent/validate/validate.md) | | **create (quick start)** | Create a new hosted Foundry agent from scratch end-to-end — scaffold, provision or use an existing Foundry project, deploy, and smoke-test. Do not use for any work on existing code. For anything not covered by the quickstart, use **create**. | [create/quick-start-hosted.md](foundry-agent/create/quick-start-hosted.md) | | **create** | Use when the standard end-to-end happy path (quick start) doesn't fit. Create a new Foundry agent, update code of an existing agent, continue development of an existing agent, wire connections at scaffold time, or use advanced setup or A2A (Agent2Agent). | [create](foundry-agent/create/create-hosted.md) | | **create managed harness** | Create or continue developing a Prompt Agent that explicitly uses the Foundry-managed Copilot harness. Uses `azd` and `azure.yaml`, not the ordinary Prompt Agent MCP workflow. | [create-managed-harness](foundry-agent/create/create-managed-harness.md) | | **create voice** | Create, configure, or extend a Foundry Voice Agent, defaulting generic requests to managed Prompt Voice and supporting GPT-Live Voice, self-deployed Prompt Voice, or two-agent Hosted Voice. | [create-voice](foundry-agent/create/create-voice.md) | | **agent-optimizer** | Make existing Python hosted-agent code optimization-ready, configure eval.yaml, run Agent Optimizer jobs, apply candidates locally, and deploy through azd after review. | [agent-optimizer](foundry-agent/agent-optimizer/agent-optimizer.md) | | **eval-datasets** | Harvest production traces into evaluation datasets, manage dataset versions and splits, track evaluation metrics over time, detect regressions, and maintain full lineage from trace to deployment. Use for: create dataset from traces, dataset versioning, evaluation trending, regression detection, dataset comparison, eval lineage. | [eval-datasets](foundry-agent/eval-datasets/eval-datasets.md) | | **project/create** | Creating a new Microsoft Foundry project for hosting agents and models. Use when onboarding to Foundry or setting up new infrastructure. | [project/create/create-foundry-project.md](project/create/create-foundry-project.md) | | **resource/create** | Creating Azure AI Services multi-service resource (Foundry resource) using Azure CLI. Use when manually provisioning AI Services resources with granular control. | [resource/create/create-foundry-resource.md](resource/create/create-foundry-resource.md) | | **private-network** | Answer questions about Foundry network isolation **and** deploy Foundry with VNet isolation (BYO VNet, Managed VNet, hybrid). Covers architecture concepts, template selection, deployment, and post-deployment validation. | [resource/private-network/private-network.md](resource/private-network/private-network.md) | | **models/deploy-model** | Unified model deployment with intelligent routing. Handles quick preset deployments, fully customized deployments (version/SKU/capacity/RAI), and capacity discovery across regions. Routes to sub-skills: `preset` (quick deploy), `customize` (full control), `capacity` (find availability). | [models/deploy-model/SKILL.md](models/deploy-model/SKILL.md) | | **quota** | Managing quotas and capacity for Microsoft Foundry resources. Use when checking quota usage, troubleshooting deployment failures due to insufficient quota, requesting quota increases, or planning capacity. | [quota/quota.md](quota/quota.md) | | **rbac** | Managing RBAC permissions, role assignments, managed identities, and service principals for Microsoft Foundry resources. Use for access control, auditing permissions, and CI/CD setup. | [rbac/rbac.md](rbac/rbac.md) | | **finetuning** | Fine-tune models on Microsoft Foundry — SFT distillation, DPO preference optimization, RFT with graders and tool calling. Dataset preparation, grader calibration, training, checkpoint selection, deployment, evaluation. Use for: fine-tune, SFT, DPO, RFT, training data, grader, distillation, fine-tuned model, large file upload. | [finetuning/SKILL.md](finetuning/SKILL.md) | | **azd-guidance** | Provide shared azd knowledge and guidance for managing Foundry agents. Read this first for any workflows related to azd. | [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) | > 💡 **Tip:** For a complete onboarding flow: `project/create` (public) or `private-network` (VNet isolation) → `models/deploy-model` → agent workflows (`create` → `deploy` → `invoke`). > 💡 **Fine-Tuning:** Use `finetuning` for all model customization — SFT distillation, DPO preference optimization, and RFT with graders. Includes quickstart, grader calibration, and training curve analysis. > 💡 **Model Deployment:** Use `models/deploy-model` for all deployment scenarios — it intelligently routes between quick preset deployment, customized deployment with full control, and capacity discovery across regions. > 💡 **Prompt Optimization:** For requests like "optimize my prompt" or "improve my agent instructions," load [observe](foundry-agent/observe/observe.md) and use the `prompt_optimize` MCP tool through that eval-driven workflow. ## Infrastructure Lifecycle Match user intent to the correct infrastructure workflow. | User Intent | Workflow | |-------------|---------| | "Create Foundry" / "Set up Foundry" (ambiguous) | Use `AskUserQuestion`: (a) just an AI Services resource, (b) a project with public access, or (c) a project with network isolation? Route: (a) → [resource/create](resource/create/create-foundry-resource.md), (b) → [project/create](project/create/create-foundry-project.md), (c) → [private-network](resource/private-network/private-network.md) | | Set up Foundry with VNet isolation | [private-network](resource/private-network/private-network.md) | | Create a Foundry project (public) | [project/create](project/create/create-foundry-project.md) | | Create a bare Foundry resource | [resource/create](resource/create/create-foundry-resource.md) | ## Agent Development Lifecycle Match user intent to the correct agent workflow. Read each sub-skill in order before executing. | User Intent | Workflow (read in order) | |-------------|------------------------| | Create or develop a Voice Agent (GPT-Live Voice, Prompt Voice, or Hosted Voice) | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → [create-voice](foundry-agent/create/create-voice.md) → [deploy](foundry-agent/deploy/deploy.md) → [invoke](foundry-agent/invoke/invoke.md) | | Create or develop an explicitly requested Managed Harness Agent / Copilot harness agent | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → [create-managed-harness](foundry-agent/create/create-managed-harness.md) → [deploy](foundry-agent/deploy/deploy.md) → [invoke](foundry-agent/invoke/invoke.md) | | Create a new hosted agent end-to-end (scaffold + deploy + test) | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → [quick-start-hosted](foundry-agent/create/quick-start-hosted.md) (self-contained end-to-end) | | Anything beyond the standard quickstart (existing code, migration, re-hosting, deployment customization, scaffold-time connections, A2A (Agent2Agent), recovery) | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → [create](foundry-agent/create/create-hosted.md) → [deploy](foundry-agent/deploy/deploy.md) → [invoke](foundry-agent/invoke/invoke.md) | | Optimize existing Python hosted agent | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → [agent-optimizer](foundry-agent/agent-optimizer/agent-optimizer.md) → scaffold/review → eval.yaml → optimize → apply candidate → deploy → invoke | | Deploy an agent (code already exists) | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → deploy (includes eval-suite setup) → invoke → observe (evaluate/optimize) | | Update/redeploy an agent after code changes | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → deploy (includes eval-suite setup) → invoke → observe (evaluate/optimize) | | Set up a CI/CD deployment pipeline for a hosted agent | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → cicd | | Invoke/test/chat with an agent | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → invoke | | Schedule/event-trigger an agent, or CRUD/enable/disable/dispatch a routine | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → routine | | Optimize / improve agent prompt or instructions | observe (Step 4: Optimize) | | Evaluate and optimize agent (full loop) | observe | | Enable continuous evaluation monitoring | observe (Step 6: CI/CD & Monitoring) | | Pull agent insights / list generated issues and recommendations | [dependency check and setup](#dependency-check-and-setup) → [insights](foundry-agent/insights/insights.md) (all pages with expanded evidence; read-only) | | Troubleshoot an agent issue | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → invoke → troubleshoot | | Fix a broken agent (troubleshoot + redeploy) | [dependency check and setup](#dependency-check-and-setup) → [azd-guidance](foundry-agent/azd-guidance/azd-guidance.md) → invoke → troubleshoot → apply fixes → deploy → invoke | ## Agent: .foundry Workspace Standard Every agent source folder can keep Foundry-specific cache and overlay state under `.foundry/`: ```text <agent-root>/ .foundry/ agent-metadata.yaml agent-metadata.prod.yaml suites/ datasets/ evaluators/ results/ ``` - In azd projects, derive deployment context (project endpoint, agent name/version, ACR, App Insights) from `azure.yaml` plus `azd env get-values`; do not duplicate those values in metadata when azd already provides them. - `agent-metadata.yaml` is the preferred local/dev overlay for non-azd values, remote Foundry suite references, local cache paths, result summaries, and explicit overrides. Optional sidecar files such as `agent-metadata.prod.yaml` can hold a single prod or CI-targeted overlay without mixing multiple environments in one file. - `suites/`, `datasets/`, and `evaluators/` are local cache folders. Reuse them when they are current, and ask before refreshing or overwriting them. - See [Agent Metadata Contract](references/agent-metadata-contract.md) for the canonical schema and workflow rules. ## Agent: Setup References - [Standard Agent Setup](references/standard-agent-setup.md) — advanced setup for production workloads that need data-residency control (bring-your-own Cosmos DB / Storage / AI Search via a Foundry capability host). The default `azd ai agent` flow uses **Basic Agent Setup** and does **not** provision `capabilityHosts/agents` — do not flag its absence as a bug. For default post-provision state, see the "Expected env-var fingerprint" section in [foundry-agent/create/create-hosted.md](foundry-agent/create/create-hosted.md). ## Agent: Common Project Context Resolution Agent skills should run this step **only when they need configuration values they don't already have**. If a value (for example, agent root, environment, project endpoint, or agent name) is already known from the user's message or a previous skill in the same session, skip resolution for that value. ### Step 1: Discover Agent Roots and azd Context First check whether the workspace has `azure.yaml` with services using `host: azure.ai.agent`. - **One azd agent service** -> classify its top-level agent type from `kind` and `harness`. For `kind: voice` or legacy `kind: prompt-voice`, read [Voice Agent subtypes](foundry-agent/create/references/voice-agent/subtypes.md), then use the service's `project` folder or the `azure.yaml` directory as the agent root. - **Multiple azd agent services** -> classify Voice services with [Voice Agent subtypes](foundry-agent/create/references/voice-agent/subtypes.md): - **Selecting a Hosted Voice wrapper** includes its named `kind: hosted` target as an upstream dependency; deploy and verification must report both services separately. - **Selecting the `kind: hosted` target alone** scopes changes/debugging to the target container and does not automatically modify the wrapper. - **Otherwise** -> require the user to choose the target service/folder. - **No azd agent service** -> search the workspace for `.foundry/` folders that contain `agent-metadata.yaml` or `agent-metadata.<env>.yaml`. - **One match** -> use that agent root. - **Multiple matches** -> require the user to choose the target agent folder. - **No matches** -> for [insights](foundry-agent/insights/insights.md), ask only for missing remote inputs without initializing local files; for create/deploy workflows, seed a new `.foundry/` folder during setup; for other workflows, stop and ask the user which agent source folder to initialize. After selecting an agent root, keep all local `.foundry` cache inspection, source inspection, evaluator suggestions, dataset suggestions, and prompt-optimization context inside that folder only. Do **not** scan sibling agent folders unless the user explicitly switches roots. ### Step 2: Resolve Environment and Deployment Context If `azure.yaml` is present, resolve the azd environment first: 1. Environment explicitly named by the user 2. `AZURE_ENV_NAME` from `azd env get-values` 3. azd default environment from `.azure/config.json` 4. Environment already selected earlier in the session Run `azd env get-values` for the selected environment when project/deployment values are not already known. Prefer azd values for deployment context: | azd Variable | Resolves To | |-------------|-------------| | `AZURE_AI_PROJECT_ENDPOINT` or `AZURE_AIPROJECT_ENDPOINT` | Project endpoint | | `AGENT_<SERVICE>_NAME` | Agent name for the selected azd service | | `AGENT_<SERVICE>_VERSION` | Agent version for the selected azd service | | `AZURE_CONTAINER_REGISTRY_NAME` or `AZURE_CONTAINER_REGISTRY_ENDPOINT` | ACR registry name / image URL prefix | | `AZURE_APPLICATION_INSIGHTS_RESOURCE_ID`, `AZURE_APPLICATION_INSIGHTS_APP_ID`, `AZURE_LOG_ANALYTICS_WORKSPACE_RESOURCE_ID` | Preferred nonsecret tracing destination identifiers | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | Legacy read-only fallback; never copy into new metadata or configuration | | `AZURE_SUBSCRIPTION_ID`, `AZURE_RESOURCE_GROUP`, `AZURE_AI_ACCOUNT_NAME`, `AZURE_AI_PROJECT_NAME` | Azure resource lookup and Playground links | When azd supplies these values, use them as the source of truth and do not copy them into `.foundry/agent-metadata*.yaml` on metadata writes. ### Step 3: Select Metadata Overlay and Resolve Environment Inside the selected agent root, choose the metadata file in this order: 1. Metadata filename or path explicitly provided by the user or workflow 2. If an explicit environment is already known and `.foundry/agent-metadata.<env>.yaml` exists, use that file 3. `.foundry/agent-metadata.yaml` 4. If multiple metadata files remain and no rule above selects one, prompt the user to choose Read the selected metadata file and resolve any remaining environment choice in this order: 1. Environment explicitly named by the user 2. If the selected metadata file defines exactly one environment, use it 3. Environment already selected earlier in the session 4. `defaultEnvironment` from metadata If the selected metadata file still contains multiple environments and none of the rules above selects one, prompt the user to choose. Keep the selected agent root, metadata file, environment, and whether context came from azd or metadata visible in every workflow summary. If the selected environment exposes older `testSuites[]` metadata but not `evaluationSuites[]`, treat `testSuites[]` as the source for this session and normalize each entry in memory to the `evaluationSuites[]` shape before continuing. If the metadata is older still and only exposes legacy `testCases[]`, normalize that list the same way. Preserve dataset and evaluator fields, keep any existing `tags`, and map legacy `priority` to `tags.tier` only when `tags.tier` is missing: `P0` -> `smoke`, `P1` -> `regression`, `P2` -> `coverage`. ### Step 4: Resolve eval.yaml Local Evaluation Intent If `eval.yaml` exists in the selected agent root, parse it before generating new suites: - `agent.name` -> target agent candidate; verify it matches the selected azd/metadata agent before using it. - `dataset.local_uri` -> local seed dataset candidate; legacy `dataset_file` may be normalized in memory. - `dataset.name` / `dataset.version` -> registered dataset candidate. - `validation_dataset` -> optional validation dataset candidate. - `evaluators[]` -> candidate Foundry evaluator names; verify with `evaluator_catalog_get` before treating them as remote evaluators. - `name` -> local eval/suite candidate; verify remotely before persisting as `suiteName`. - `options.eval_model`, `options.optimization_model`, `options.max_candidates`, `options.optimization_config.model_search_space`, `options.pass_threshold`, `max_samples`, `trace_days`, and `generation_instruction` -> setup defaults. Treat `eval.yaml` as local evaluation intent, not proof that a Foundry suite exists. Persist synced suite/dataset/evaluator references to `.foundry` only after remote lookup or registration succeeds. ### Step 5: Resolve Common Configuration Layer sources in this order: 1. Explicit user input and values already selected in the session 2. azd environment values for deployment context 3. `.foundry/agent-metadata*.yaml` overlay values and remote suite/cache references 4. `azure.yaml` and `eval.yaml` local source configuration 5. User prompts for anything still missing If azd and metadata both provide the same value and they differ, stop and ask which source is authoritative. If they match, use the azd value and avoid rewriting the duplicate on future metadata writes. | Effective Value | Preferred Source | Used By | |-----------------|------------------|---------| | Project endpoint | azd env | deploy, invoke, observe, trace, troubleshoot | | Agent name/version | azd agent variables, then `azure.yaml` | invoke, observe, trace, troubleshoot | | ACR | azd env | deploy | | Evaluation suites and cache paths | `.foundry/agent-metadata*.yaml` | observe, eval-datasets | | Local seed dataset/evaluator intent | `eval.yaml` | observe, eval-datasets | ### Step 6: Write Metadata Overlay (Create/Deploy/Observe Only) On any metadata write (deploy, auto-setup, dataset refresh, or trace-to-dataset update), persist only non-derivable overlay/cache state in the selected metadata file: - azd binding (`azd.environmentName`, `azd.service`) when useful for future resolution - `evaluationSuites[]` with remote suite/dataset/evaluator references and local cache paths - `lastEval`, result files, comparison summaries, or explicit non-azd overrides Do not copy azd-owned deployment values into metadata when azd already provides them. If the selected file is a preferred single-environment file, rewrite only that one environment block. If the selected file is a legacy multi-environment file, rewrite only the selected environment block. Never copy or merge environments across sibling metadata files automatically. If the selected environment still uses older `testSuites[]` or legacy `testCases[]`, rewrite it to `evaluationSuites[]` and remove migrated `priority` fields from the rewritten entries. ### Step 7: Collect Missing Values Use the `ask_user` or `askQuestions` tool **only for values not resolved** from the user's message, session context, metadata, or azd bootstrap. Common values skills may need: - **Agent root** — Target azd service project folder or folder containing `.foundry/agent-metadata*.yaml` - **Metadata file** — `agent-metadata.yaml` for local/dev, or an explicit sidecar such as `agent-metadata.prod.yaml` - **Environment** — azd environment, `dev`, `prod`, or another environment key from metadata - **Project endpoint** — Microsoft Foundry project endpoint URL - **Agent name** — Name of the target agent > 💡 **Tip:** If the user already provides the agent path, environment, project endpoint, or agent name, extract it directly — do not ask again. ## Agent: Agent Types Agent workflows distinguish four first-class agent types: | Type | Kind | Description | |------|------|-------------| | **Prompt** | `"prompt"` | LLM-based agents backed by a model deployment; managed via Foundry MCP or SDK | | **Hosted** | `"hosted"` | Container-based agents running custom code; developed and deployed via `azd` | | **Managed Harness Agent** | `"prompt"` with `harness.type: "microsoft_copilot_preview"` for new authoring | Prompt Agent running on the Foundry-managed Copilot harness; developed and deployed via `azd` | | **Voice** | `"voice"` | Managed real-time Voice Agent; read [Voice Agent subtypes](foundry-agent/create/references/voice-agent/subtypes.md) to distinguish GPT-Live Voice, Prompt Voice, and Hosted Voice | Classify an `azure.yaml` service by its definition in this exact order, not by `host` alone: 1. `kind: voice` -> **Voice**. For compatibility, silently classify existing `kind: prompt-voice` services as Voice and normalize them when editing. Then read [Voice Agent subtypes](foundry-agent/create/references/voice-agent/subtypes.md). 2. `kind: hosted` -> **Hosted**. If Voice subtype classification identifies it as a wrapper's named target, treat it as that dependency; otherwise a standalone `invocations_ws` service is a **custom Hosted real-time/audio agent**. 3. `kind: prompt` plus `harness.type: microsoft_copilot_preview` or legacy `github_copilot_preview` -> **Managed Harness Agent**. 4. `kind: prompt` without that harness -> ordinary **Prompt Agent**. Use `agent_get` only when the type cannot be resolved from project context. Preserve the harness discriminator already authored on an existing Managed Harness Agent; do not migrate it during ordinary edits or redeploys. Do not convert an existing Agent between Prompt, Hosted, Managed Harness Agent, and Voice types; create a new Agent instead. Before creating any **Voice Agent**, determine the model strategy first per [create-voice](foundry-agent/create/create-voice.md). ## Tool Usage Conventions - Use the `ask_user` or `askQuestions` tool whenever collecting information from the user - Use the `task` or `runSubagent` tool to delegate long-running or independent sub-tasks (e.g., env var scanning, status polling, Dockerfile generation) - Prefer azd for Hosted Agents, Managed Harness Agents, and Voice Agents; prefer Foundry MCP for ordinary Prompt Agents. - Reference official Microsoft documentation URLs instead of embedding CLI command syntax ## Azure Authentication - [Azure Authentication Best Practices](references/auth-best-practices.md) ## Additional Resources - [Foundry Hosted Agents](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry) - [Foundry Agent Runtime Components](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/runtime-components?view=foundry) ## Network Isolation Errors Applies to **any** call against a Foundry project or its parent Foundry account — Foundry MCP tools, `azd`, `az` CLI, `curl`, REST, or SDK. If an error matches `Public access is disabled` / `PublicNetworkAccessDisabled` / `403 Forbidden` from a private endpoint / connection timeout / the project endpoint FQDN resolves to a public IP, this typically means the parent Foundry account has `publicNetworkAccess=Disabled` or `Enabled from selected IP addresses`, and the current shell is outside its VNet. Only if the error is ambiguous, confirm against the Foundry account using a management-plane call (works from anywhere with reader access): ```bash az cognitiveservices account show \ --name <account> --resource-group <rg> \ --query "properties.{publicNetworkAccess:publicNetworkAccess, networkAcls:networkAcls, privateEndpointConnections:privateEndpointConnections[].properties.privateLinkServiceConnectionState.status}" ``` `publicNetworkAccess: "Disabled"` — or `"Enabled"` together with non-empty `networkAcls.ipRules` / `virtualNetworkRules` — confirms isolation. If `publicNetworkAccess: "Enabled"` and `networkAcls` is empty, the failure is a caller-side network issue (e.g. Private DNS resolving the FQDN to a public IP from inside a VNet with a private endpoint), not an account-config issue. If it's indeed a network isolation issue, supported connection options are documented in [Choose a secure connection method to Foundry](https://learn.microsoft.com/azure/foundry/how-to/configure-private-link#choose-a-secure-connection-method-to-foundry). > ℹ️ Foundry MCP tools cannot reach a VNet-isolated project even from inside the VNet.Original on GitHubpresetIntelligently deploys Azure OpenAI models to optimal regions by analyzing capacity across all available regions. Automatically checks current region first and shows alternatives if needed. USE FOR: quick deployment, optimal region, best region, automatic region selection, fast setup, multi-region capacity check, high availability deployment, deploy to best location. DO NOT USE FOR: custom SKU selection (use customize), specific version selection (use customize), custom capacity configuration (use customize), PTU deployments (use customize).ReadClose
--- name: preset description: "Intelligently deploys Azure OpenAI models to optimal regions by analyzing capacity across all available regions. Automatically checks current region first and shows alternatives if needed. USE FOR: quick deployment, optimal region, best region, automatic region selection, fast setup, multi-region capacity check, high availability deployment, deploy to best location. DO NOT USE FOR: custom SKU selection (use customize), specific version selection (use customize), custom capacity configuration (use customize), PTU deployments (use customize)." license: MIT metadata: author: Microsoft version: "1.0.1" --- # Deploy Model to Optimal Region Automates intelligent Azure OpenAI model deployment by checking capacity across regions and deploying to the best available option. ## What This Skill Does 1. Verifies Azure authentication and project scope 2. Checks capacity in current project's region 3. If no capacity: analyzes all regions and shows available alternatives 4. Filters projects by selected region 5. Supports creating new projects if needed 6. Deploys model with GlobalStandard SKU 7. Monitors deployment progress ## Prerequisites - Azure CLI installed and configured - Active Azure subscription with Cognitive Services read/create permissions - Microsoft Foundry project resource ID (`PROJECT_RESOURCE_ID` env var or provided interactively) - Format: `/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}` - Found in: Microsoft Foundry portal → Project → Overview → Resource ID ## Quick Workflow ### Fast Path (Current Region Has Capacity) ``` 1. Check authentication → 2. Get project → 3. Check current region capacity → 4. Deploy immediately ``` ### Alternative Region Path (No Capacity) ``` 1. Check authentication → 2. Get project → 3. Check current region (no capacity) → 4. Query all regions → 5. Show alternatives → 6. Select region + project → 7. Deploy ``` --- ## Deployment Phases | Phase | Action | Key Commands | |-------|--------|-------------| | 1. Verify Auth | Check Azure CLI login and subscription | `az account show`, `az login` | | 2. Get Project | Parse `PROJECT_RESOURCE_ID` ARM ID, verify exists | `az cognitiveservices account show` | | 3. Get Model | List available models, user selects model + version | `az cognitiveservices account list-models` | | 4. Check Current Region | Query capacity using GlobalStandard SKU | `az rest --method GET .../modelCapacities` | | 5. Multi-Region Query | If no local capacity, query all regions | Same capacity API without location filter | | 6. Select Region + Project | User picks region; find or create project | `az cognitiveservices account list`, `az cognitiveservices account create` | | 7. Deploy | Generate unique name, calculate capacity (50% available, min 50 TPM), create deployment | `az cognitiveservices account deployment create` | For detailed step-by-step instructions, see [workflow reference](references/workflow.md). --- ## Error Handling | Error | Symptom | Resolution | |-------|---------|------------| | Auth failure | `az account show` returns error | Run `az login` then `az account set --subscription <id>` | | No quota | All regions show 0 capacity | Defer to the [quota skill](../../../quota/quota.md) for increase requests and troubleshooting; check existing deployments; try alternative models | | Model not found | Empty capacity list | Verify model name with `az cognitiveservices account list-models`; check case sensitivity | | Name conflict | "deployment already exists" | Append suffix to deployment name (handled automatically by `generate_deployment_name` script) | | Region unavailable | Region doesn't support model | Select a different region from the available list | | Permission denied | "Forbidden" or "Unauthorized" | Verify Cognitive Services Contributor role: `az role assignment list --assignee <user>` | --- ## Advanced Usage ```bash # Custom capacity az cognitiveservices account deployment create ... --sku-capacity <value> # Check deployment status az cognitiveservices account deployment show --name <acct> --resource-group <rg> --deployment-name <name> --query "{Status:properties.provisioningState}" # Delete deployment az cognitiveservices account deployment delete --name <acct> --resource-group <rg> --deployment-name <name> ``` ## Notes - **SKU:** GlobalStandard only — **API Version:** 2024-10-01 (GA stable) --- ## Related Skills - **microsoft-foundry** - Parent skill for Microsoft Foundry operations - **[quota](../../../quota/quota.md)** — For quota viewing, increase requests, and troubleshooting quota errors, defer to this skill - **azure-quick-review** - Review Azure resources for compliance - **cost-estimation** - Estimate costs through the separately installed `azure-cost` plugin - **azure-validate** - Validate Azure infrastructure before deploymentOriginal on GitHubpython-appservice-deployDeploy Python (Flask/Django/FastAPI) code to Azure App Service Linux. WHEN: \"Flask App Service\", \"Django App Service\", \"FastAPI App Service\", \"deploy Python to App Service\". DO NOT USE FOR: Container Apps, Functions, non-Python, Terraform/Bicep/IaC, full infra — use azure-prepare.ReadClose
--- name: python-appservice-deploy description: "Deploy Python (Flask/Django/FastAPI) code to Azure App Service Linux. WHEN: \"Flask App Service\", \"Django App Service\", \"FastAPI App Service\", \"deploy Python to App Service\". DO NOT USE FOR: Container Apps, Functions, non-Python, Terraform/Bicep/IaC, full infra — use azure-prepare." license: MIT metadata: author: Microsoft version: "1.1.3" --- # Python on Azure App Service — Code Deploy Deploys Python (Flask, Django, FastAPI, generic) code to Azure App Service Linux (P0v3, Python 3.14). Creates RG + Plan + Web App if missing. Hand off to `azure-prepare` for VNet, Key Vault, databases, or IaC. **MCP tools used**: `mcp_azure_mcp_subscription_list`, `mcp_azure_mcp_group_list`, `mcp_azure_mcp_appservice`, `mcp_azure_mcp_azd` (when `azure.yaml` is present). ## Workflow **Prerequisite:** Verify the latest stable Azure CLI; update with approval and recheck if needed. 1. **Resolve context — smart defaults, minimal prompts.** Only the app name is interactive; RG (`<app>-rg`), Plan (`<app>-plan`), region (current `az` default or `eastus2`), subscription are derived. [create-app.md](references/create-app.md) §1. 2. **Detect framework** (advisory, never blocks). [detect.md](references/detect.md). 3. **Choose path** — `azure.yaml` host: appservice → [deploy-azd.md](references/deploy-azd.md); else [deploy-azcli.md](references/deploy-azcli.md). 4. **Ensure RG → Plan (`P0v3 --is-linux`) → Web App (`--runtime "PYTHON:3.14"`)** exist. Before creating a plan, invoke `azure-quotas` to check quota availability. On transient ARM errors, follow [transient-retry.md](references/transient-retry.md). [create-app.md](references/create-app.md). 5. **Set startup** — Flask/Django: none (Oryx auto-detects). FastAPI: always `python -m uvicorn main:app --host 0.0.0.0`. Other: warn. [startup-commands.md](references/startup-commands.md). 6. **Set `SCM_DO_BUILD_DURING_DEPLOYMENT=true`**. 7. **Deploy** — `azd deploy` or `az webapp deploy --type zip --track-status false --enriched-errors true`. 8. **STOP. Print the post-deploy message** ([post-deploy-message.md](references/post-deploy-message.md)) and end the turn. ### Hard rules - **LINUX SCRIPTS** — normalize selected shell/startup files to LF, then verify no CR bytes remain. Stop on normalization, validation or packaging failure; deploy only a fresh package. - **DJANGO REMOTE BUILDS** — require `STATIC_ROOT` and successful system/`collectstatic` checks before packaging. - ⛔ **NO POST-DEPLOY VERIFICATION** — after deploy returns, do not run `az webapp log tail`, `curl`, `Invoke-WebRequest`, or any health probe. App Service needs 2–3 min to warm; a quiet log or early 5xx is not failure. - ⛔ **SHELL SAFETY** — for `--runtime` always use `"PYTHON:3.14"` (colon). Never `"PYTHON|3.14"` (pipe is a shell operator). - ⛔ **NEVER `az webapp up`** — deprecated. Use Step 7 commands. - ✅ **URL FORMAT** — present endpoints as `https://...` URLs. ## Error Handling See [errors.md](references/errors.md) for the full symptom → cause → fix matrix. Quick triage: missing plan/app → re-run Step 4; container ping timeout on 8000 → fix startup (Step 5); `ModuleNotFoundError` after deploy → ensure Step 6 ran, redeploy.
Original on GitHub
Author and licence
These skills were written and published by Microsoft at github.com/microsoft/azure-skills under the MIT licence. skillsmcp copies them unchanged, checks the repository once a day, and is not affiliated with Microsoft. A skill is a set of instructions an AI agent may follow, so read a skill before you let an agent use it.
Show the licence
MIT License Copyright 2025 (c) Microsoft Corporation. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE