From 28a6dfe735d29044c9fff1d9b3c15999162792af Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 19 Mar 2026 11:13:20 +0000 Subject: [PATCH] Sync plugin files from GitHub-Copilot-for-Azure --- .../azure-skills/.claude-plugin/plugin.json | 17 +- .github/plugins/azure-skills/.mcp.json | 8 +- .../plugins/azure-skills/.plugin/plugin.json | 24 + .github/plugins/azure-skills/CHANGELOG.md | 49 ++ .github/plugins/azure-skills/LICENSE | 21 + .github/plugins/azure-skills/README.md | 6 +- .../appinsights-instrumentation/SKILL.md | 9 +- ...azure-monitor-opentelemetry-exporter-py.md | 2 + .../sdk/azure-monitor-opentelemetry-py.md | 2 + .../azure-skills/skills/azure-ai/SKILL.md | 6 +- .../references/auth-best-practices.md | 128 +++ .../azure-ai-document-intelligence-dotnet.md | 2 +- .../sdk/azure-ai-document-intelligence-ts.md | 3 + .../sdk/azure-search-documents-dotnet.md | 2 +- .../skills/azure-aigateway/SKILL.md | 784 ++---------------- .../references/auth-best-practices.md | 128 +++ .../azure-aigateway/references/patterns.md | 226 +++++ .../azure-aigateway/references/policies.md | 311 +++++++ .../sdk/azure-mgmt-apimanagement-dotnet.md | 4 +- .../sdk/azure-mgmt-apimanagement-py.md | 2 + .../references/troubleshooting.md | 270 ++++++ .../skills/azure-cloud-migrate/SKILL.md | 43 + .../services/functions/assessment.md | 154 ++++ .../services/functions/code-migration.md | 138 +++ .../services/functions/global-rules.md | 51 ++ .../services/functions/lambda-to-functions.md | 266 ++++++ .../services/functions/runtimes/csharp.md | 225 +++++ .../services/functions/runtimes/java.md | 214 +++++ .../services/functions/runtimes/javascript.md | 325 ++++++++ .../services/functions/runtimes/powershell.md | 221 +++++ .../services/functions/runtimes/python.md | 199 +++++ .../services/functions/runtimes/typescript.md | 119 +++ .../references/workflow-details.md | 26 + .../skills/azure-compliance/SKILL.md | 13 +- .../references/auth-best-practices.md | 128 +++ .../references/sdk/azure-keyvault-keys-ts.md | 2 +- .../references/sdk/azure-keyvault-py.md | 2 +- .../sdk/azure-keyvault-secrets-ts.md | 2 +- .../azure-security-keyvault-keys-dotnet.md | 2 +- .../sdk/azure-security-keyvault-keys-java.md | 3 + .../azure-security-keyvault-secrets-java.md | 3 + .../skills/azure-compute/SKILL.md | 160 ++++ .../references/retail-prices-api.md | 128 +++ .../azure-compute/references/vm-families.md | 70 ++ .../azure-compute/references/vmss-guide.md | 95 +++ .../skills/azure-cost-optimization/SKILL.md | 13 +- .../references/auth-best-practices.md | 128 +++ .../azure-resource-manager-redis-dotnet.md | 5 +- .../azure-skills/skills/azure-deploy/SKILL.md | 33 +- .../references/auth-best-practices.md | 128 +++ .../references/pre-deploy-checklist.md | 41 +- .../references/recipes/azd/README.md | 8 +- .../references/recipes/azd/ef-migrations.md | 158 ++++ .../references/recipes/azd/errors.md | 65 ++ .../recipes/azd/functions-deploy.md | 26 + .../references/recipes/azd/post-deployment.md | 97 +++ .../references/recipes/azd/sql-entra-auth.md | 82 ++ .../recipes/azd/sql-managed-identity.md | 145 ++++ .../references/recipes/azd/verify.md | 79 +- .../references/recipes/bicep/README.md | 10 + .../references/region-availability.md | 22 +- .../references/sdk/azure-identity-dotnet.md | 5 +- .../references/sdk/azure-identity-java.md | 5 +- .../references/sdk/azure-identity-py.md | 5 +- .../references/sdk/azure-identity-ts.md | 5 +- .../references/troubleshooting.md | 34 + .../skills/azure-diagnostics/SKILL.md | 29 +- .../aks-troubleshooting.md | 90 ++ .../general-diagnostics.md | 64 ++ .../aks-troubleshooting/networking.md | 141 ++++ .../aks-troubleshooting/node-issues.md | 228 +++++ .../aks-troubleshooting/pod-failures.md | 147 ++++ .../aks-troubleshooting/references/aks-mcp.md | 38 + .../references/command-flows.md | 87 ++ .../references/structured-input-modes.md | 55 ++ .../references/functions/README.md | 88 ++ .../skills/azure-hosted-copilot-sdk/SKILL.md | 55 ++ .../references/auth-best-practices.md | 128 +++ .../references/azure-model-config.md | 123 +++ .../references/copilot-sdk.md | 78 ++ .../references/deploy-existing.md | 72 ++ .../existing-project-integration.md | 76 ++ .../azure-skills/skills/azure-kusto/SKILL.md | 9 +- .../skills/azure-messaging/SKILL.md | 58 ++ .../references/auth-best-practices.md | 128 +++ .../references/sdk/azure-eventhubs-dotnet.md | 68 ++ .../references/sdk/azure-eventhubs-java.md | 69 ++ .../references/sdk/azure-eventhubs-js.md | 62 ++ .../references/sdk/azure-eventhubs-py.md | 85 ++ .../references/sdk/azure-servicebus-dotnet.md | 35 + .../references/sdk/azure-servicebus-java.md | 49 ++ .../references/sdk/azure-servicebus-js.md | 44 + .../references/sdk/azure-servicebus-py.md | 50 ++ .../references/service-troubleshooting.md | 73 ++ .../skills/azure-observability/SKILL.md | 105 --- .../azure-mgmt-applicationinsights-dotnet.md | 30 - .../sdk/azure-monitor-ingestion-java.md | 31 - .../sdk/azure-monitor-ingestion-py.md | 30 - ...azure-monitor-opentelemetry-exporter-py.md | 22 - .../sdk/azure-monitor-opentelemetry-py.md | 23 - .../sdk/azure-monitor-opentelemetry-ts.md | 26 - .../sdk/azure-monitor-query-java.md | 29 - .../references/sdk/azure-monitor-query-py.md | 24 - .../skills/azure-postgres/SKILL.md | 124 --- .../references/entra-rbac-overview.md | 171 ---- .../azure-postgres/references/group-sync.md | 256 ------ .../references/permission-templates.md | 205 ----- .../references/sdk/azure-identity-py.md | 25 - .../references/sdk/azure-identity-ts.md | 22 - .../references/sdk/azure-postgres-ts.md | 27 - ...zure-resource-manager-postgresql-dotnet.md | 28 - .../references/sql-functions.md | 82 -- .../references/troubleshooting.md | 301 ------- .../azure-postgres/scripts/az-commands.sh | 121 --- .../scripts/migrate-to-entra.sh | 125 --- .../azure-postgres/scripts/setup-group.sh | 193 ----- .../scripts/setup-managed-identity.sh | 157 ---- .../azure-postgres/scripts/setup-user.sh | 135 --- .../skills/azure-prepare/SKILL.md | 47 +- .../azure-prepare/references/analyze.md | 36 +- .../skills/azure-prepare/references/apim.md | 212 +++++ .../azure-prepare/references/architecture.md | 11 +- .../skills/azure-prepare/references/aspire.md | 298 +++++++ .../references/auth-best-practices.md | 128 +++ .../azure-prepare/references/azure-context.md | 68 +- .../azure-prepare/references/generate.md | 36 + .../azure-prepare/references/plan-template.md | 90 +- .../references/recipe-selection.md | 18 +- .../references/recipes/azcli/README.md | 2 +- .../references/recipes/azd/README.md | 19 +- .../references/recipes/azd/aspire.md | 262 ++++++ .../references/recipes/azd/azure-yaml.md | 42 + .../references/recipes/azd/iac-rules.md | 33 +- .../references/recipes/azd/terraform.md | 110 ++- .../references/recipes/bicep/README.md | 2 +- .../references/recipes/bicep/patterns.md | 4 + .../references/recipes/terraform/README.md | 38 +- .../references/region-availability.md | 10 +- .../azure-prepare/references/research.md | 81 +- .../references/resources-limits-quotas.md | 309 +++++++ .../skills/azure-prepare/references/scan.md | 25 + .../sdk/azure-appconfiguration-java.md | 3 + .../sdk/azure-appconfiguration-py.md | 3 + .../sdk/azure-appconfiguration-ts.md | 3 + .../references/sdk/azure-identity-dotnet.md | 5 +- .../references/sdk/azure-identity-java.md | 5 +- .../references/sdk/azure-identity-py.md | 5 +- .../references/sdk/azure-identity-ts.md | 5 +- .../azure-prepare/references/security.md | 24 +- .../services/container-apps/bicep.md | 2 + .../services/durable-task-scheduler/README.md | 77 ++ .../services/durable-task-scheduler/bicep.md | 116 +++ .../services/durable-task-scheduler/dotnet.md | 190 +++++ .../services/durable-task-scheduler/java.md | 243 ++++++ .../durable-task-scheduler/javascript.md | 211 +++++ .../services/durable-task-scheduler/python.md | 219 +++++ .../references/services/functions/README.md | 42 +- .../functions/aspire-containerapps.md | 93 +++ .../references/services/functions/bicep.md | 39 +- .../references/services/functions/durable.md | 12 + .../services/functions/templates/README.md | 31 +- .../templates/SPEC-composable-templates.md | 613 ++++++++++++++ .../functions/templates/base/eval/python.md | 32 + .../functions/templates/base/eval/summary.md | 25 + .../services/functions/templates/http.md | 7 + .../functions/templates/integrations.md | 24 +- .../services/functions/templates/mcp.md | 28 + .../functions/templates/recipes/README.md | 123 +++ .../recipes/blob-eventgrid/README.md | 100 +++ .../recipes/blob-eventgrid/bicep/blob.bicep | 162 ++++ .../recipes/blob-eventgrid/eval/python.md | 39 + .../recipes/blob-eventgrid/eval/summary.md | 59 ++ .../recipes/blob-eventgrid/source/dotnet.md | 102 +++ .../recipes/blob-eventgrid/source/java.md | 100 +++ .../blob-eventgrid/source/javascript.md | 94 +++ .../blob-eventgrid/source/powershell.md | 117 +++ .../recipes/blob-eventgrid/source/python.md | 96 +++ .../blob-eventgrid/source/typescript.md | 108 +++ .../recipes/blob-eventgrid/terraform/blob.tf | 170 ++++ .../recipes/common/dotnet-entry-point.md | 59 ++ .../recipes/common/error-handling.md | 93 +++ .../templates/recipes/common/health-check.md | 120 +++ .../recipes/common/nodejs-entry-point.md | 130 +++ .../templates/recipes/common/uami-bindings.md | 139 ++++ .../templates/recipes/composition.md | 490 +++++++++++ .../templates/recipes/cosmosdb/README.md | 128 +++ .../cosmosdb/bicep/cosmos-network.bicep | 96 +++ .../recipes/cosmosdb/bicep/cosmos.bicep | 189 +++++ .../templates/recipes/cosmosdb/eval/python.md | 35 + .../recipes/cosmosdb/eval/summary.md | 25 + .../recipes/cosmosdb/source/dotnet.md | 82 ++ .../templates/recipes/cosmosdb/source/java.md | 74 ++ .../recipes/cosmosdb/source/javascript.md | 74 ++ .../recipes/cosmosdb/source/powershell.md | 64 ++ .../recipes/cosmosdb/source/python.md | 63 ++ .../recipes/cosmosdb/source/typescript.md | 76 ++ .../recipes/cosmosdb/terraform/cosmos.tf | 196 +++++ .../templates/recipes/durable/README.md | 186 +++++ .../bicep/durable-task-scheduler.bicep | 116 +++ .../templates/recipes/durable/eval/python.md | 75 ++ .../templates/recipes/durable/eval/summary.md | 27 + .../recipes/durable/source/dotnet.md | 118 +++ .../templates/recipes/durable/source/java.md | 91 ++ .../recipes/durable/source/javascript.md | 112 +++ .../recipes/durable/source/powershell.md | 145 ++++ .../recipes/durable/source/python.md | 124 +++ .../recipes/durable/source/typescript.md | 125 +++ .../templates/recipes/eventhubs/README.md | 138 +++ .../eventhubs/bicep/eventhubs-network.bicep | 93 +++ .../recipes/eventhubs/bicep/eventhubs.bicep | 109 +++ .../recipes/eventhubs/eval/python.md | 36 + .../recipes/eventhubs/eval/summary.md | 24 + .../recipes/eventhubs/source/dotnet.md | 107 +++ .../recipes/eventhubs/source/java.md | 112 +++ .../recipes/eventhubs/source/javascript.md | 76 ++ .../recipes/eventhubs/source/powershell.md | 143 ++++ .../recipes/eventhubs/source/python.md | 83 ++ .../recipes/eventhubs/source/typescript.md | 95 +++ .../recipes/eventhubs/terraform/eventhubs.tf | 200 +++++ .../functions/templates/recipes/mcp/README.md | 99 +++ .../templates/recipes/mcp/eval/python.md | 83 ++ .../templates/recipes/mcp/eval/summary.md | 25 + .../templates/recipes/mcp/source/dotnet.md | 117 +++ .../templates/recipes/mcp/source/java.md | 154 ++++ .../recipes/mcp/source/javascript.md | 107 +++ .../recipes/mcp/source/powershell.md | 167 ++++ .../templates/recipes/mcp/source/python.md | 169 ++++ .../recipes/mcp/source/typescript.md | 174 ++++ .../templates/recipes/servicebus/README.md | 115 +++ .../recipes/servicebus/bicep/servicebus.bicep | 87 ++ .../recipes/servicebus/eval/python.md | 35 + .../recipes/servicebus/eval/summary.md | 24 + .../recipes/servicebus/source/dotnet.md | 135 +++ .../recipes/servicebus/source/java.md | 128 +++ .../recipes/servicebus/source/javascript.md | 115 +++ .../recipes/servicebus/source/powershell.md | 169 ++++ .../recipes/servicebus/source/python.md | 106 +++ .../recipes/servicebus/source/typescript.md | 132 +++ .../servicebus/terraform/servicebus.tf | 113 +++ .../functions/templates/recipes/sql/README.md | 101 +++ .../templates/recipes/sql/bicep/sql.bicep | 137 +++ .../templates/recipes/sql/eval/python.md | 39 + .../templates/recipes/sql/eval/summary.md | 68 ++ .../templates/recipes/sql/source/dotnet.md | 119 +++ .../templates/recipes/sql/source/java.md | 124 +++ .../recipes/sql/source/javascript.md | 101 +++ .../recipes/sql/source/powershell.md | 142 ++++ .../templates/recipes/sql/source/python.md | 149 ++++ .../recipes/sql/source/typescript.md | 112 +++ .../templates/recipes/sql/terraform/sql.tf | 162 ++++ .../templates/recipes/timer/README.md | 71 ++ .../templates/recipes/timer/eval/python.md | 49 ++ .../templates/recipes/timer/eval/summary.md | 20 + .../templates/recipes/timer/source/dotnet.md | 99 +++ .../templates/recipes/timer/source/java.md | 93 +++ .../recipes/timer/source/javascript.md | 84 ++ .../recipes/timer/source/powershell.md | 102 +++ .../templates/recipes/timer/source/python.md | 75 ++ .../recipes/timer/source/typescript.md | 93 +++ .../services/functions/templates/selection.md | 52 +- .../services/functions/terraform.md | 301 +++++++ .../references/services/key-vault/sdk.md | 6 + .../services/service-bus/patterns.md | 6 + .../services/sql-database/README.md | 26 +- .../references/services/sql-database/auth.md | 68 +- .../references/services/sql-database/bicep.md | 55 +- .../references/services/sql-database/sdk.md | 26 +- .../references/services/storage/access.md | 27 +- .../references/specialized-routing.md | 50 ++ .../azure-skills/skills/azure-quotas/SKILL.md | 323 ++++++++ .../references/advanced-commands.md | 69 ++ .../azure-quotas/references/commands.md | 323 ++++++++ .../azure-skills/skills/azure-rbac/SKILL.md | 19 +- .../skills/azure-resource-lookup/SKILL.md | 16 +- .../skills/azure-resource-visualizer/SKILL.md | 9 +- .../skills/azure-storage/SKILL.md | 6 +- .../references/auth-best-practices.md | 128 +++ .../azure-storage/references/sdk-usage.md | 2 +- .../references/sdk/azure-data-tables-java.md | 3 + .../references/sdk/azure-data-tables-py.md | 3 + .../references/sdk/azure-storage-blob-java.md | 2 +- .../references/sdk/azure-storage-blob-py.md | 2 +- .../references/sdk/azure-storage-blob-ts.md | 2 +- .../sdk/azure-storage-file-datalake-py.md | 3 + .../sdk/azure-storage-file-share-py.md | 3 + .../sdk/azure-storage-file-share-ts.md | 2 +- .../references/sdk/azure-storage-queue-py.md | 3 + .../references/sdk/azure-storage-queue-ts.md | 2 +- .../skills/azure-upgrade/SKILL.md | 76 ++ .../azure-upgrade/references/global-rules.md | 47 ++ .../services/functions/assessment.md | 119 +++ .../services/functions/automation.md | 421 ++++++++++ .../services/functions/consumption-to-flex.md | 227 +++++ .../references/workflow-details.md | 59 ++ .../skills/azure-validate/SKILL.md | 18 +- .../references/recipes/azd/README.md | 45 +- .../references/recipes/azd/errors.md | 2 +- .../references/region-availability.md | 22 +- .../skills/entra-app-registration/SKILL.md | 9 +- .../references/auth-best-practices.md | 128 +++ .../references/sdk/azure-identity-dotnet.md | 4 +- .../references/sdk/azure-identity-java.md | 4 +- .../references/sdk/azure-identity-py.md | 4 +- .../references/sdk/azure-identity-ts.md | 4 +- .../references/sdk/azure-keyvault-py.md | 2 +- .../sdk/azure-keyvault-secrets-ts.md | 2 +- .../skills/microsoft-foundry/.gitignore | 0 .../skills/microsoft-foundry/SKILL.md | 141 +++- .../agent/create/agent-framework/SKILL.md | 162 ---- .../references/agent-as-server.md | 83 -- .../references/agent-samples.md | 95 --- .../agent-framework/references/debug-setup.md | 202 ----- .../references/workflow-agents.md | 75 -- .../references/workflow-basics.md | 56 -- .../references/workflow-foundry.md | 105 --- .../foundry-agent/create/create-prompt.md | 89 ++ .../foundry-agent/create/create.md | 239 ++++++ .../create/references/agent-tools.md | 45 + .../create/references/agentframework.md | 92 ++ .../create/references/sdk-operations.md | 47 ++ .../create/references/tool-azure-ai-search.md | 69 ++ .../create/references/tool-bing-grounding.md | 50 ++ .../create/references/tool-file-search.md | 60 ++ .../create/references/tool-mcp.md | 66 ++ .../create/references/tool-memory.md | 109 +++ .../create/references/tool-web-search.md | 57 ++ .../foundry-agent/deploy/deploy.md | 381 +++++++++ .../eval-datasets/eval-datasets.md | 85 ++ .../references/dataset-comparison.md | 103 +++ .../references/dataset-curation.md | 102 +++ .../references/dataset-organization.md | 112 +++ .../references/dataset-versioning.md | 169 ++++ .../eval-datasets/references/eval-lineage.md | 127 +++ .../references/eval-regression.md | 121 +++ .../eval-datasets/references/eval-trending.md | 95 +++ .../references/trace-to-dataset.md | 391 +++++++++ .../foundry-agent/invoke/invoke.md | 98 +++ .../foundry-agent/observe/observe.md | 77 ++ .../observe/references/analyze-results.md | 48 ++ .../observe/references/cicd-monitoring.md | 36 + .../observe/references/compare-iterate.md | 52 ++ .../observe/references/deploy-and-setup.md | 82 ++ .../observe/references/evaluate-step.md | 71 ++ .../observe/references/optimize-deploy.md | 32 + .../trace/references/analyze-failures.md | 109 +++ .../trace/references/analyze-latency.md | 116 +++ .../trace/references/conversation-detail.md | 98 +++ .../trace/references/eval-correlation.md | 57 ++ .../trace/references/kql-templates.md | 203 +++++ .../trace/references/search-traces.md | 144 ++++ .../foundry-agent/trace/trace.md | 59 ++ .../troubleshoot/troubleshoot.md | 96 +++ .../models/deploy-model/SKILL.md | 9 +- .../models/deploy-model/capacity/SKILL.md | 9 +- .../models/deploy-model/customize/EXAMPLES.md | 7 + .../models/deploy-model/customize/SKILL.md | 7 +- .../customize/references/customize-guides.md | 2 + .../references/customize-workflow.md | 164 +++- .../models/deploy-model/preset/EXAMPLES.md | 6 + .../models/deploy-model/preset/SKILL.md | 7 +- .../preset/references/preset-workflow.md | 175 +++- .../preset/references/workflow.md | 2 + .../microsoft-foundry/project/connections.md | 61 ++ .../project/create/create-foundry-project.md | 15 +- .../skills/microsoft-foundry/quota/quota.md | 145 +++- .../quota/references/capacity-planning.md | 126 +++ .../quota/references/error-resolution.md | 145 ++++ .../quota/references/optimization.md | 168 ++++ .../quota/references/ptu-guide.md | 2 + .../quota/references/troubleshooting.md | 2 + .../quota/references/workflows.md | 2 + .../references/agent-metadata-contract.md | 104 +++ .../references/auth-best-practices.md | 130 +++ .../private-network-standard-agent-setup.md | 40 + .../references/sdk/foundry-sdk-py.md | 28 +- .../references/standard-agent-setup.md | 51 ++ .../create/create-foundry-resource.md | 2 + .../resource/create/references/patterns.md | 2 + .../resource/create/references/workflows.md | 2 + 379 files changed, 28997 insertions(+), 4130 deletions(-) create mode 100644 .github/plugins/azure-skills/.plugin/plugin.json create mode 100644 .github/plugins/azure-skills/CHANGELOG.md create mode 100644 .github/plugins/azure-skills/LICENSE create mode 100644 .github/plugins/azure-skills/skills/azure-ai/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/azure-aigateway/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/azure-aigateway/references/patterns.md create mode 100644 .github/plugins/azure-skills/skills/azure-aigateway/references/policies.md create mode 100644 .github/plugins/azure-skills/skills/azure-aigateway/references/troubleshooting.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/SKILL.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/assessment.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/code-migration.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/global-rules.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/lambda-to-functions.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/runtimes/csharp.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/runtimes/java.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/runtimes/javascript.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/runtimes/powershell.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/runtimes/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/runtimes/typescript.md create mode 100644 .github/plugins/azure-skills/skills/azure-cloud-migrate/references/workflow-details.md create mode 100644 .github/plugins/azure-skills/skills/azure-compliance/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/azure-compute/SKILL.md create mode 100644 .github/plugins/azure-skills/skills/azure-compute/references/retail-prices-api.md create mode 100644 .github/plugins/azure-skills/skills/azure-compute/references/vm-families.md create mode 100644 .github/plugins/azure-skills/skills/azure-compute/references/vmss-guide.md create mode 100644 .github/plugins/azure-skills/skills/azure-cost-optimization/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/azure-deploy/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/ef-migrations.md create mode 100644 .github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/post-deployment.md create mode 100644 .github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/sql-entra-auth.md create mode 100644 .github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/sql-managed-identity.md create mode 100644 .github/plugins/azure-skills/skills/azure-diagnostics/aks-troubleshooting/aks-troubleshooting.md create mode 100644 .github/plugins/azure-skills/skills/azure-diagnostics/aks-troubleshooting/general-diagnostics.md create mode 100644 .github/plugins/azure-skills/skills/azure-diagnostics/aks-troubleshooting/networking.md create mode 100644 .github/plugins/azure-skills/skills/azure-diagnostics/aks-troubleshooting/node-issues.md create mode 100644 .github/plugins/azure-skills/skills/azure-diagnostics/aks-troubleshooting/pod-failures.md create mode 100644 .github/plugins/azure-skills/skills/azure-diagnostics/aks-troubleshooting/references/aks-mcp.md create mode 100644 .github/plugins/azure-skills/skills/azure-diagnostics/aks-troubleshooting/references/command-flows.md create mode 100644 .github/plugins/azure-skills/skills/azure-diagnostics/aks-troubleshooting/references/structured-input-modes.md create mode 100644 .github/plugins/azure-skills/skills/azure-diagnostics/references/functions/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-hosted-copilot-sdk/SKILL.md create mode 100644 .github/plugins/azure-skills/skills/azure-hosted-copilot-sdk/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/azure-hosted-copilot-sdk/references/azure-model-config.md create mode 100644 .github/plugins/azure-skills/skills/azure-hosted-copilot-sdk/references/copilot-sdk.md create mode 100644 .github/plugins/azure-skills/skills/azure-hosted-copilot-sdk/references/deploy-existing.md create mode 100644 .github/plugins/azure-skills/skills/azure-hosted-copilot-sdk/references/existing-project-integration.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/SKILL.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/references/sdk/azure-eventhubs-dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/references/sdk/azure-eventhubs-java.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/references/sdk/azure-eventhubs-js.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/references/sdk/azure-eventhubs-py.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/references/sdk/azure-servicebus-dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/references/sdk/azure-servicebus-java.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/references/sdk/azure-servicebus-js.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/references/sdk/azure-servicebus-py.md create mode 100644 .github/plugins/azure-skills/skills/azure-messaging/references/service-troubleshooting.md delete mode 100644 .github/plugins/azure-skills/skills/azure-observability/SKILL.md delete mode 100644 .github/plugins/azure-skills/skills/azure-observability/references/sdk/azure-mgmt-applicationinsights-dotnet.md delete mode 100644 .github/plugins/azure-skills/skills/azure-observability/references/sdk/azure-monitor-ingestion-java.md delete mode 100644 .github/plugins/azure-skills/skills/azure-observability/references/sdk/azure-monitor-ingestion-py.md delete mode 100644 .github/plugins/azure-skills/skills/azure-observability/references/sdk/azure-monitor-opentelemetry-exporter-py.md delete mode 100644 .github/plugins/azure-skills/skills/azure-observability/references/sdk/azure-monitor-opentelemetry-py.md delete mode 100644 .github/plugins/azure-skills/skills/azure-observability/references/sdk/azure-monitor-opentelemetry-ts.md delete mode 100644 .github/plugins/azure-skills/skills/azure-observability/references/sdk/azure-monitor-query-java.md delete mode 100644 .github/plugins/azure-skills/skills/azure-observability/references/sdk/azure-monitor-query-py.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/SKILL.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/references/entra-rbac-overview.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/references/group-sync.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/references/permission-templates.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/references/sdk/azure-identity-py.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/references/sdk/azure-identity-ts.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/references/sdk/azure-postgres-ts.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/references/sdk/azure-resource-manager-postgresql-dotnet.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/references/sql-functions.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/references/troubleshooting.md delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/scripts/az-commands.sh delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/scripts/migrate-to-entra.sh delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/scripts/setup-group.sh delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/scripts/setup-managed-identity.sh delete mode 100644 .github/plugins/azure-skills/skills/azure-postgres/scripts/setup-user.sh create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/apim.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/aspire.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/recipes/azd/aspire.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/resources-limits-quotas.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/durable-task-scheduler/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/durable-task-scheduler/bicep.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/durable-task-scheduler/dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/durable-task-scheduler/java.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/durable-task-scheduler/javascript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/durable-task-scheduler/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/aspire-containerapps.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/SPEC-composable-templates.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/base/eval/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/base/eval/summary.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/bicep/blob.bicep create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/eval/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/eval/summary.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/source/dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/source/java.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/source/javascript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/source/powershell.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/source/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/source/typescript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/blob-eventgrid/terraform/blob.tf create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/common/dotnet-entry-point.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/common/error-handling.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/common/health-check.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/common/nodejs-entry-point.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/common/uami-bindings.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/composition.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/bicep/cosmos-network.bicep create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/bicep/cosmos.bicep create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/eval/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/eval/summary.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/source/dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/source/java.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/source/javascript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/source/powershell.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/source/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/source/typescript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/cosmosdb/terraform/cosmos.tf create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/durable/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/durable/bicep/durable-task-scheduler.bicep create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/durable/eval/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/durable/eval/summary.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/durable/source/dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/durable/source/java.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/durable/source/javascript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/durable/source/powershell.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/durable/source/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/durable/source/typescript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/bicep/eventhubs-network.bicep create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/bicep/eventhubs.bicep create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/eval/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/eval/summary.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/source/dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/source/java.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/source/javascript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/source/powershell.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/source/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/source/typescript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/eventhubs/terraform/eventhubs.tf create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/mcp/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/mcp/eval/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/mcp/eval/summary.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/mcp/source/dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/mcp/source/java.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/mcp/source/javascript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/mcp/source/powershell.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/mcp/source/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/mcp/source/typescript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/bicep/servicebus.bicep create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/eval/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/eval/summary.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/source/dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/source/java.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/source/javascript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/source/powershell.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/source/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/source/typescript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/servicebus/terraform/servicebus.tf create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/bicep/sql.bicep create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/eval/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/eval/summary.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/source/dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/source/java.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/source/javascript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/source/powershell.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/source/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/source/typescript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/sql/terraform/sql.tf create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/timer/README.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/timer/eval/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/timer/eval/summary.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/timer/source/dotnet.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/timer/source/java.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/timer/source/javascript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/timer/source/powershell.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/timer/source/python.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/templates/recipes/timer/source/typescript.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/services/functions/terraform.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/specialized-routing.md create mode 100644 .github/plugins/azure-skills/skills/azure-quotas/SKILL.md create mode 100644 .github/plugins/azure-skills/skills/azure-quotas/references/advanced-commands.md create mode 100644 .github/plugins/azure-skills/skills/azure-quotas/references/commands.md create mode 100644 .github/plugins/azure-skills/skills/azure-storage/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/azure-upgrade/SKILL.md create mode 100644 .github/plugins/azure-skills/skills/azure-upgrade/references/global-rules.md create mode 100644 .github/plugins/azure-skills/skills/azure-upgrade/references/services/functions/assessment.md create mode 100644 .github/plugins/azure-skills/skills/azure-upgrade/references/services/functions/automation.md create mode 100644 .github/plugins/azure-skills/skills/azure-upgrade/references/services/functions/consumption-to-flex.md create mode 100644 .github/plugins/azure-skills/skills/azure-upgrade/references/workflow-details.md create mode 100644 .github/plugins/azure-skills/skills/entra-app-registration/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/.gitignore delete mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/agent/create/agent-framework/SKILL.md delete mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/agent/create/agent-framework/references/agent-as-server.md delete mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/agent/create/agent-framework/references/agent-samples.md delete mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/agent/create/agent-framework/references/debug-setup.md delete mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/agent/create/agent-framework/references/workflow-agents.md delete mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/agent/create/agent-framework/references/workflow-basics.md delete mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/agent/create/agent-framework/references/workflow-foundry.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/create-prompt.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/create.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/agent-tools.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/agentframework.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/sdk-operations.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/tool-azure-ai-search.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/tool-bing-grounding.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/tool-file-search.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/tool-mcp.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/tool-memory.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/tool-web-search.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/deploy/deploy.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/eval-datasets/eval-datasets.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/eval-datasets/references/dataset-comparison.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/eval-datasets/references/dataset-curation.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/eval-datasets/references/dataset-organization.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/eval-datasets/references/dataset-versioning.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/eval-datasets/references/eval-lineage.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/eval-datasets/references/eval-regression.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/eval-datasets/references/eval-trending.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/eval-datasets/references/trace-to-dataset.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/invoke/invoke.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/observe/observe.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/observe/references/analyze-results.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/observe/references/cicd-monitoring.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/observe/references/compare-iterate.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/observe/references/deploy-and-setup.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/observe/references/evaluate-step.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/observe/references/optimize-deploy.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/references/analyze-failures.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/references/analyze-latency.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/references/conversation-detail.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/references/eval-correlation.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/references/kql-templates.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/references/search-traces.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/trace.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/troubleshoot/troubleshoot.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/project/connections.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/quota/references/capacity-planning.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/quota/references/error-resolution.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/quota/references/optimization.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/references/agent-metadata-contract.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/references/auth-best-practices.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/references/private-network-standard-agent-setup.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/references/standard-agent-setup.md diff --git a/.github/plugins/azure-skills/.claude-plugin/plugin.json b/.github/plugins/azure-skills/.claude-plugin/plugin.json index 9d66edae..e04ada25 100644 --- a/.github/plugins/azure-skills/.claude-plugin/plugin.json +++ b/.github/plugins/azure-skills/.claude-plugin/plugin.json @@ -1,11 +1,24 @@ { "name": "azure", "description": "Microsoft Azure MCP integration for cloud resource management, deployments, and Azure services. Manage your Azure infrastructure, monitor applications, and deploy resources directly from Claude Code.", - "version": "1.0.0", + "version": "1.0.1", "author": { "name": "Microsoft", "url": "https://www.microsoft.com" }, "homepage": "https://github.com/microsoft/github-copilot-for-azure", - "keywords": ["azure", "cloud", "infrastructure", "deployment", "microsoft", "devops"] + "repository": "https://github.com/microsoft/GitHub-Copilot-for-Azure", + "license": "MIT", + "keywords": [ + "azure", + "cloud", + "infrastructure", + "deployment", + "microsoft", + "devops", + "foundry", + "diagnostics" + ], + "skills": "./skills/", + "mcpServers": "./.mcp.json" } diff --git a/.github/plugins/azure-skills/.mcp.json b/.github/plugins/azure-skills/.mcp.json index 3b6c52b7..b5ae1a6c 100644 --- a/.github/plugins/azure-skills/.mcp.json +++ b/.github/plugins/azure-skills/.mcp.json @@ -4,9 +4,9 @@ "command": "npx", "args": ["-y", "@azure/mcp@latest", "server", "start"] }, - "foundry-mcp": { - "type": "http", - "url": "https://mcp.ai.azure.com" - } + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + } } } diff --git a/.github/plugins/azure-skills/.plugin/plugin.json b/.github/plugins/azure-skills/.plugin/plugin.json new file mode 100644 index 00000000..a70f46fb --- /dev/null +++ b/.github/plugins/azure-skills/.plugin/plugin.json @@ -0,0 +1,24 @@ +{ + "name": "azure", + "description": "Microsoft Azure MCP integration for cloud resource management, deployments, and Azure services. Manage your Azure infrastructure, monitor applications, and deploy resources directly from your development environment.", + "version": "1.0.1", + "author": { + "name": "Microsoft", + "url": "https://www.microsoft.com" + }, + "homepage": "https://github.com/microsoft/github-copilot-for-azure", + "repository": "https://github.com/microsoft/GitHub-Copilot-for-Azure", + "license": "MIT", + "keywords": [ + "azure", + "cloud", + "infrastructure", + "deployment", + "microsoft", + "devops", + "foundry", + "diagnostics" + ], + "skills": "./skills/", + "mcpServers": "./.mcp.json" +} diff --git a/.github/plugins/azure-skills/CHANGELOG.md b/.github/plugins/azure-skills/CHANGELOG.md new file mode 100644 index 00000000..fbc6add1 --- /dev/null +++ b/.github/plugins/azure-skills/CHANGELOG.md @@ -0,0 +1,49 @@ +# Changelog + +All notable changes to the Azure plugin will be documented in this file. + +This project adheres to [Semantic Versioning](https://semver.org/). + +## [1.0.1] - 2026-03-13 + +### Added + +- `azure-upgrade` — Assess and upgrade Azure workloads between plans, tiers, or SKUs. + +### Changed + +- Removed `foundry-mcp` HTTP server from `.mcp.json` (non-spec `type`/`url` fields). +- Updated `azure-diagnostics` description. +- Updated `microsoft-foundry` description and bumped to version 1.0.5. + +## [1.0.0] - 2025-03-12 + +### Added + +- Initial release of the Azure plugin. +- Vendor-neutral `.plugin/plugin.json` manifest following the [Open Plugins Specification](https://open-plugins.com/plugin-builders/specification). +- Claude Code manifest (`.claude-plugin/plugin.json`). +- MCP server configuration (`.mcp.json`) for Azure MCP, Foundry MCP, and Context7. +- MIT `LICENSE` file at the plugin root. +- 21 agent skills: + - `appinsights-instrumentation` — Azure Application Insights telemetry setup. + - `azure-ai` — Azure AI Search, Speech, OpenAI, and Document Intelligence. + - `azure-aigateway` — Azure API Management as an AI Gateway. + - `azure-cloud-migrate` — Cross-cloud migration assessment and code conversion. + - `azure-compliance` — Security auditing and best practices assessment. + - `azure-compute` — VM size recommendation and configuration. + - `azure-cost-optimization` — Cost savings analysis and recommendations. + - `azure-deploy` — Azure deployment execution (azd, Bicep, Terraform). + - `azure-diagnostics` — Production issue debugging and log analysis. + - `azure-hosted-copilot-sdk` — Build and deploy GitHub Copilot SDK apps to Azure. + - `azure-kusto` — Azure Data Explorer KQL queries. + - `azure-messaging` — Event Hubs and Service Bus SDK troubleshooting. + - `azure-prepare` — Application preparation for Azure deployment. + - `azure-quotas` — Quota and usage management. + - `azure-rbac` — RBAC role recommendation and assignment. + - `azure-resource-lookup` — Azure resource discovery and listing. + - `azure-resource-visualizer` — Mermaid architecture diagram generation. + - `azure-storage` — Blob, File, Queue, Table, and Data Lake storage. + - `azure-validate` — Pre-deployment validation checks. + - `entra-app-registration` — Microsoft Entra ID app registration and OAuth setup. + - `microsoft-foundry` — Foundry agent deployment, evaluation, and management. \ No newline at end of file diff --git a/.github/plugins/azure-skills/LICENSE b/.github/plugins/azure-skills/LICENSE new file mode 100644 index 00000000..356b112b --- /dev/null +++ b/.github/plugins/azure-skills/LICENSE @@ -0,0 +1,21 @@ +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 \ No newline at end of file diff --git a/.github/plugins/azure-skills/README.md b/.github/plugins/azure-skills/README.md index 17194766..a7409e47 100644 --- a/.github/plugins/azure-skills/README.md +++ b/.github/plugins/azure-skills/README.md @@ -47,11 +47,13 @@ When running on Azure resources (VMs, Container Apps, etc.), the server automati For more authentication options, see the [Azure Identity documentation](https://learn.microsoft.com/azure/developer/azure-mcp-server/). ### 4. Install the Plugins +```bash # Add the repo as a plugin marketplace -/plugin marketplace add microsoft/github-copilot-for-azure +/plugin marketplace add microsoft/azure-skills # Pull in the Azure plugin -/plugin install azure@github-copilot-for-azure +/plugin install azure@azure-skills +``` ## Available Tools diff --git a/.github/plugins/azure-skills/skills/appinsights-instrumentation/SKILL.md b/.github/plugins/azure-skills/skills/appinsights-instrumentation/SKILL.md index 287fa7c9..716a14dd 100644 --- a/.github/plugins/azure-skills/skills/appinsights-instrumentation/SKILL.md +++ b/.github/plugins/azure-skills/skills/appinsights-instrumentation/SKILL.md @@ -1,9 +1,10 @@ --- name: appinsights-instrumentation -description: | - Guidance for instrumenting webapps with Azure Application Insights. Provides telemetry patterns, SDK setup, and configuration references. - USE FOR: how to instrument app, App Insights SDK, telemetry patterns, what is App Insights, Application Insights guidance, instrumentation examples, APM best practices. - DO NOT USE FOR: adding App Insights to my app (use azure-prepare), add telemetry to my project (use azure-prepare), add monitoring (use azure-prepare). This skill provides guidance—azure-prepare orchestrates component changes. +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.0.2" --- # AppInsights Instrumentation Guide diff --git a/.github/plugins/azure-skills/skills/appinsights-instrumentation/references/sdk/azure-monitor-opentelemetry-exporter-py.md b/.github/plugins/azure-skills/skills/appinsights-instrumentation/references/sdk/azure-monitor-opentelemetry-exporter-py.md index 83389710..ff88e963 100644 --- a/.github/plugins/azure-skills/skills/appinsights-instrumentation/references/sdk/azure-monitor-opentelemetry-exporter-py.md +++ b/.github/plugins/azure-skills/skills/appinsights-instrumentation/references/sdk/azure-monitor-opentelemetry-exporter-py.md @@ -5,7 +5,9 @@ > in the **azure-monitor-opentelemetry-exporter-py** plugin skill if installed. ## Install +```bash pip install azure-monitor-opentelemetry-exporter +``` ## Quick Start ```python diff --git a/.github/plugins/azure-skills/skills/appinsights-instrumentation/references/sdk/azure-monitor-opentelemetry-py.md b/.github/plugins/azure-skills/skills/appinsights-instrumentation/references/sdk/azure-monitor-opentelemetry-py.md index 9b70ea5a..41d98a0e 100644 --- a/.github/plugins/azure-skills/skills/appinsights-instrumentation/references/sdk/azure-monitor-opentelemetry-py.md +++ b/.github/plugins/azure-skills/skills/appinsights-instrumentation/references/sdk/azure-monitor-opentelemetry-py.md @@ -5,7 +5,9 @@ > in the **azure-monitor-opentelemetry-py** plugin skill if installed. ## Install +```bash pip install azure-monitor-opentelemetry +``` ## Quick Start ```python diff --git a/.github/plugins/azure-skills/skills/azure-ai/SKILL.md b/.github/plugins/azure-skills/skills/azure-ai/SKILL.md index 87db64da..e2fcbc87 100644 --- a/.github/plugins/azure-skills/skills/azure-ai/SKILL.md +++ b/.github/plugins/azure-skills/skills/azure-ai/SKILL.md @@ -1,6 +1,10 @@ --- name: azure-ai -description: "Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. USE FOR: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech. DO NOT USE FOR: Function apps/Functions (use azure-functions), databases (azure-postgres/azure-kusto), general Azure resources." +description: "Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech." +license: MIT +metadata: + author: Microsoft + version: "1.0.1" --- # Azure AI Services diff --git a/.github/plugins/azure-skills/skills/azure-ai/references/auth-best-practices.md b/.github/plugins/azure-skills/skills/azure-ai/references/auth-best-practices.md new file mode 100644 index 00000000..6938d5f0 --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-ai/references/auth-best-practices.md @@ -0,0 +1,128 @@ +# Azure Authentication Best Practices + +> Source: [Microsoft — Passwordless connections for Azure services](https://learn.microsoft.com/azure/developer/intro/passwordless-overview) and [Azure Identity client libraries](https://learn.microsoft.com/dotnet/azure/sdk/authentication/). + +## Golden Rule + +Use **managed identities** and **Azure RBAC** in production. Reserve `DefaultAzureCredential` for **local development only**. + +## Authentication by Environment + +| Environment | Recommended Credential | Why | +|---|---|---| +| **Production (Azure-hosted)** | `ManagedIdentityCredential` (system- or user-assigned) | No secrets to manage; auto-rotated by Azure | +| **Production (on-premises)** | `ClientCertificateCredential` or `WorkloadIdentityCredential` | Deterministic; no fallback chain overhead | +| **CI/CD pipelines** | `AzurePipelinesCredential` / `WorkloadIdentityCredential` | Scoped to pipeline identity | +| **Local development** | `DefaultAzureCredential` | Chains CLI, PowerShell, and VS Code credentials for convenience | + +## Why Not `DefaultAzureCredential` in Production? + +1. **Unpredictable fallback chain** — walks through multiple credential types, adding latency and making failures harder to diagnose. +2. **Broad surface area** — checks environment variables, CLI tokens, and other sources that should not exist in production. +3. **Non-deterministic** — which credential actually authenticates depends on the environment, making behavior inconsistent across deployments. +4. **Performance** — each failed credential attempt adds network round-trips before falling back to the next. + +## Production Patterns + +### .NET + +```csharp +using Azure.Identity; + +var credential = Environment.GetEnvironmentVariable("AZURE_FUNCTIONS_ENVIRONMENT") == "Development" + ? new DefaultAzureCredential() // local dev — uses CLI/VS credentials + : new ManagedIdentityCredential(); // production — deterministic, no fallback chain +// For user-assigned identity: new ManagedIdentityCredential("") +``` + +### TypeScript / JavaScript + +```typescript +import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity"; + +const credential = process.env.NODE_ENV === "development" + ? new DefaultAzureCredential() // local dev — uses CLI/VS credentials + : new ManagedIdentityCredential(); // production — deterministic, no fallback chain +// For user-assigned identity: new ManagedIdentityCredential("") +``` + +### Python + +```python +import os +from azure.identity import DefaultAzureCredential, ManagedIdentityCredential + +credential = ( + DefaultAzureCredential() # local dev — uses CLI/VS credentials + if os.getenv("AZURE_FUNCTIONS_ENVIRONMENT") == "Development" + else ManagedIdentityCredential() # production — deterministic, no fallback chain +) +# For user-assigned identity: ManagedIdentityCredential(client_id="") +``` + +### Java + +```java +import com.azure.identity.DefaultAzureCredentialBuilder; +import com.azure.identity.ManagedIdentityCredentialBuilder; + +var credential = "Development".equals(System.getenv("AZURE_FUNCTIONS_ENVIRONMENT")) + ? new DefaultAzureCredentialBuilder().build() // local dev — uses CLI/VS credentials + : new ManagedIdentityCredentialBuilder().build(); // production — deterministic, no fallback chain +// For user-assigned identity: new ManagedIdentityCredentialBuilder().clientId("").build() +``` + +## Local Development Setup + +`DefaultAzureCredential` is ideal for local dev because it automatically picks up credentials from developer tools: + +1. **Azure CLI** — `az login` +2. **Azure Developer CLI** — `azd auth login` +3. **Azure PowerShell** — `Connect-AzAccount` +4. **Visual Studio / VS Code** — sign in via Azure extension + +```typescript +import { DefaultAzureCredential } from "@azure/identity"; + +// Local development only — uses CLI/PowerShell/VS Code credentials +const credential = new DefaultAzureCredential(); +``` + +## Environment-Aware Pattern + +Detect the runtime environment and select the appropriate credential. The key principle: use `DefaultAzureCredential` only when running locally, and a specific credential in production. + +> **Tip:** Azure Functions sets `AZURE_FUNCTIONS_ENVIRONMENT` to `"Development"` when running locally. For App Service or containers, use any environment variable you control (e.g. `NODE_ENV`, `ASPNETCORE_ENVIRONMENT`). + +```typescript +import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity"; + +function getCredential() { + if (process.env.NODE_ENV === "development") { + return new DefaultAzureCredential(); // picks up az login / VS Code creds + } + return process.env.AZURE_CLIENT_ID + ? new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID) // user-assigned + : new ManagedIdentityCredential(); // system-assigned +} +``` + +## Security Checklist + +- [ ] Use managed identity for all Azure-hosted apps +- [ ] Never hardcode credentials, connection strings, or keys +- [ ] Apply least-privilege RBAC roles at the narrowest scope +- [ ] Use `ManagedIdentityCredential` (not `DefaultAzureCredential`) in production +- [ ] Store any required secrets in Azure Key Vault +- [ ] Rotate secrets and certificates on a schedule +- [ ] Enable Microsoft Defender for Cloud on production resources + +## Further Reading + +- [Passwordless connections overview](https://learn.microsoft.com/azure/developer/intro/passwordless-overview) +- [Managed identities overview](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview) +- [Azure RBAC overview](https://learn.microsoft.com/azure/role-based-access-control/overview) +- [.NET authentication guide](https://learn.microsoft.com/dotnet/azure/sdk/authentication/) +- [Python identity library](https://learn.microsoft.com/python/api/overview/azure/identity-readme) +- [JavaScript identity library](https://learn.microsoft.com/javascript/api/overview/azure/identity-readme) +- [Java identity library](https://learn.microsoft.com/java/api/overview/azure/identity-readme) diff --git a/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-ai-document-intelligence-dotnet.md b/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-ai-document-intelligence-dotnet.md index 6b9ee67a..41e9e065 100644 --- a/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-ai-document-intelligence-dotnet.md +++ b/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-ai-document-intelligence-dotnet.md @@ -22,7 +22,7 @@ var adminClient = new DocumentIntelligenceAdministrationClient(new Uri(endpoint) - Entra ID requires custom subdomain, not regional endpoint ## Best Practices -1. Use DefaultAzureCredential for production +1. Use DefaultAzureCredential for **local development only**. In production, use ManagedIdentityCredential — see [auth-best-practices.md](../auth-best-practices.md) 2. Reuse client instances — clients are thread-safe 3. Handle long-running operations with `WaitUntil.Completed` 4. Check field confidence — always verify `Confidence` property diff --git a/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-ai-document-intelligence-ts.md b/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-ai-document-intelligence-ts.md index e9da2323..1e18b149 100644 --- a/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-ai-document-intelligence-ts.md +++ b/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-ai-document-intelligence-ts.md @@ -9,6 +9,9 @@ npm install @azure-rest/ai-document-intelligence @azure/identity ``` ## Quick Start + +> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. + ```typescript import DocumentIntelligence, { isUnexpected, getLongRunningPoller, AnalyzeOperationOutput } from "@azure-rest/ai-document-intelligence"; const client = DocumentIntelligence(endpoint, new DefaultAzureCredential()); diff --git a/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-search-documents-dotnet.md b/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-search-documents-dotnet.md index 436e1f3b..aaa956c8 100644 --- a/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-search-documents-dotnet.md +++ b/.github/plugins/azure-skills/skills/azure-ai/references/sdk/azure-search-documents-dotnet.md @@ -21,7 +21,7 @@ var client = new SearchClient(new Uri(endpoint), indexName, credential); - Semantic answers: `result.Value.SemanticSearch.Answers` / captions on each result ## Best Practices -1. Use `DefaultAzureCredential` over API keys for production +1. Use `DefaultAzureCredential` for **local development only**. In production, use `ManagedIdentityCredential` — see [auth-best-practices.md](../auth-best-practices.md) 2. Use `FieldBuilder` with model attributes for type-safe index definitions 3. Use `CreateOrUpdateIndexAsync` for idempotent index creation 4. Batch document operations for better throughput diff --git a/.github/plugins/azure-skills/skills/azure-aigateway/SKILL.md b/.github/plugins/azure-skills/skills/azure-aigateway/SKILL.md index e78b2e57..50aece7f 100644 --- a/.github/plugins/azure-skills/skills/azure-aigateway/SKILL.md +++ b/.github/plugins/azure-skills/skills/azure-aigateway/SKILL.md @@ -1,755 +1,129 @@ --- name: azure-aigateway -description: | - Configure Azure API Management (APIM) as AI Gateway to secure, observe, control AI models, MCP servers, agents. Helps with rate limiting, semantic caching, content safety, load balancing. - USE FOR: AI Gateway, APIM, setup gateway, configure gateway, add gateway, model gateway, MCP server, rate limit, token limit, semantic cache, content safety, load balance, OpenAPI import, convert API to MCP. - DO NOT USE FOR: deploy models (use microsoft-foundry), Azure Functions (use azure-functions), databases (use azure-postgres). +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.0.1" +compatibility: Requires Azure CLI (az) for configuration and testing --- # Azure AI Gateway -Bootstrap and configure Azure API Management (APIM) as an AI Gateway for securing, observing, and controlling AI models, tools (MCP Servers), and agents. - -## Skill Activation Triggers - -**Use this skill immediately when the user asks to:** -- "Set up a gateway for my model" -- "Set up a gateway for my tools" -- "Set up a gateway for my agents" -- "Add a gateway to my MCP server" -- "Protect my AI model with a gateway" -- "Secure my AI agents" -- "Ratelimit my model requests" -- "Ratelimit my tool requests" -- "Limit tokens for my model" -- "Add rate limiting to my MCP server" -- "Enable semantic caching for my AI API" -- "Add content safety to my AI endpoint" -- "Add my model behind gateway" -- "Import API from OpenAPI spec" -- "Add API to gateway from swagger" -- "Convert my API to MCP" -- "Expose my API as MCP server" - -**Key Indicators:** -- User deploying Azure OpenAI, AI Foundry, or other AI models -- User creating or managing MCP servers -- User needs token limits, rate limiting, or quota management -- User wants to cache AI responses to reduce costs -- User needs content filtering or safety controls -- User wants load balancing across multiple AI backends - -**Secondary Triggers (Proactive Recommendations):** -- After model creation: Recommend AI Gateway for security, caching, and token limits -- After MCP server creation: Recommend AI Gateway for rate limiting, content safety, and auth - -## Overview - -Azure API Management serves as an AI Gateway that provides: -- **Security**: Authentication, authorization, and content safety -- **Observability**: Token metrics, logging, and monitoring -- **Control**: Rate limiting, token limits, and load balancing -- **Optimization**: Semantic caching to reduce costs and latency +Configure Azure API Management (APIM) as an AI Gateway for governing AI models, MCP tools, and agents. -``` -AI Models ──┐ ┌── Azure OpenAI -MCP Tools ──┼── AI Gateway (APIM) ──┼── AI Foundry -Agents ─────┘ └── Custom Models -``` - -## Key Resources - -- **GitHub Repo**: https://github.com/Azure-Samples/AI-Gateway (aka.ms/aigateway) -- **Docs**: - - [GenAI Gateway Capabilities](https://learn.microsoft.com/en-us/azure/api-management/genai-gateway-capabilities) - - [MCP Server Overview](https://learn.microsoft.com/en-us/azure/api-management/mcp-server-overview) - - [Azure AI Foundry API](https://learn.microsoft.com/en-us/azure/api-management/azure-ai-foundry-api) - - [Semantic Caching](https://learn.microsoft.com/en-us/azure/api-management/azure-openai-enable-semantic-caching) - - [Token Limits & LLM Logs](https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-llm-logs) - -## Configuration Rules - -**Default to `Basicv2` SKU** when creating new APIM instances: -- Cheaper than other tiers -- Creates quickly (~5-10 minutes vs 30+ for Premium) -- Supports all AI Gateway policies - -## Pattern 1: Quick Bootstrap AI Gateway - -Deploy APIM with Basicv2 SKU for AI workloads. - -```bash -# Create resource group -az group create --name rg-aigateway --location eastus2 - -# Deploy APIM with Bicep -az deployment group create \ - --resource-group rg-aigateway \ - --template-file main.bicep \ - --parameters apimSku=Basicv2 -``` - -### Bicep Template - -```bicep -param location string = resourceGroup().location -param apimSku string = 'Basicv2' -param apimManagedIdentityType string = 'SystemAssigned' - -// NOTE: Using 2024-06-01-preview because Basicv2 SKU support currently requires this preview API version. -// Update to the latest stable (GA) API version once Basicv2 is available there. -resource apimService 'Microsoft.ApiManagement/service@2024-06-01-preview' = { - name: 'apim-aigateway-${uniqueString(resourceGroup().id)}' - location: location - sku: { - name: apimSku - capacity: 1 - } - properties: { - publisherEmail: 'admin@contoso.com' - publisherName: 'Contoso' - } - identity: { - type: apimManagedIdentityType - } -} - -output gatewayUrl string = apimService.properties.gatewayUrl -output principalId string = apimService.identity.principalId -``` - -## Pattern 2: Semantic Caching - -Cache similar prompts to reduce costs and latency. - -```xml - - - - - - - - - - - - - -``` - -**Options:** -| Parameter | Range | Description | -|-----------|-------|-------------| -| `score-threshold` | 0.7-0.95 | Higher = stricter matching | -| `duration` | 60-3600 | Cache TTL in seconds | - -## Pattern 3: Token Rate Limiting - -Limit tokens per minute to control costs and prevent abuse. - -```xml - - - - - - - - -``` - -**Options:** -| Parameter | Values | Description | -|-----------|--------|-------------| -| `counter-key` | Subscription.Id, Request.IpAddress, custom | Grouping key for limits | -| `tokens-per-minute` | 100-100000 | Token quota | -| `estimate-prompt-tokens` | true/false | true = faster but less accurate | - -## Pattern 4: Content Safety - -Filter harmful content and detect jailbreak attempts. - -```xml - - - - - - - - - - - - - - custom-blocklist - - - - -``` - -**Options:** -| Parameter | Range | Description | -|-----------|-------|-------------| -| `threshold` | 0-7 | 0=safe, 7=severe | -| `shield-prompt` | true/false | Detect jailbreak attempts | - -## Pattern 5: Rate Limits for MCPs/OpenAPI Tools - -Protect MCP servers and tools with request rate limiting. - -```xml - - - - - - - - - @(context.Variables.GetValueOrDefault("remainingCalls", 0).ToString()) - - - - -``` - -## Pattern 6: Managed Identity Authentication - -Secure backend access with managed identity instead of API keys. - -```xml - - - - - - - @("Bearer " + (string)context.Variables["managed-id-access-token"]) - - - - - - - - - - -``` +> **To deploy APIM**, use the **azure-prepare** skill. See [APIM deployment guide](https://learn.microsoft.com/azure/api-management/get-started-create-service-instance). -## Pattern 7: Load Balancing with Retry - -Distribute load across multiple backends with automatic failover. - -```xml - - - - - - - - - - - - - - - - - - - - -``` - -## Pattern 8: Add AI Foundry Model Behind Gateway - -When user asks to "add my model behind gateway", first discover available models from Azure AI Foundry, then ask which model to add. - -### Step 1: Discover AI Foundry Projects and Available Models - -```bash -# Set environment variables -accountName="" -resourceGroupName="" - -# List AI Foundry resources (AI Services accounts) -az cognitiveservices account list --query "[?kind=='AIServices'].{name:name, resourceGroup:resourceGroup, location:location}" -o table - -# List available models in the AI Foundry resource -az cognitiveservices account list-models \ - -n $accountName \ - -g $resourceGroupName \ - | jq '.[] | { name: .name, format: .format, version: .version, sku: .skus[0].name, capacity: .skus[0].capacity.default }' - -# List already deployed models -az cognitiveservices account deployment list \ - -n $accountName \ - -g $resourceGroupName -``` - -### Step 2: Ask User Which Model to Add - -After listing the available models, **use the ask_user tool** to present the models as choices and let the user select which model to add behind the gateway. - -Example choices to present: -- Model deployments from the discovered list -- Include model name, format (provider), version, and SKU info - -### Step 3: Deploy the Model (if not already deployed) - -```bash -# Deploy the selected model to AI Foundry -az cognitiveservices account deployment create \ - -n $accountName \ - -g $resourceGroupName \ - --deployment-name \ - --model-name \ - --model-version \ - --model-format \ - --sku-capacity 1 \ - --sku-name -``` - -### Step 4: Configure APIM Backend for Selected Model - -```bash -# Get the AI Foundry inference endpoint -ENDPOINT=$(az cognitiveservices account show \ - -n $accountName \ - -g $resourceGroupName \ - | jq -r '.properties.endpoints["Azure AI Model Inference API"]') - -# Create APIM backend for the selected model -az apim backend create \ - --resource-group \ - --service-name \ - --backend-id -backend \ - --protocol http \ - --url "${ENDPOINT}" -``` - -### Step 5: Create API and Apply Policies - -```bash -# Import Azure OpenAI API specification -az apim api import \ - --resource-group \ - --service-name \ - --path \ - --specification-format OpenApiJson \ - --specification-url "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/stable/2024-02-01/inference.json" -``` +## When to Use This Skill -### Step 6: Grant APIM Access to AI Foundry +| 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" | -```bash -# Get APIM managed identity principal ID -APIM_PRINCIPAL_ID=$(az apim show \ - --name \ - --resource-group \ - --query "identity.principalId" -o tsv) - -# Get AI Foundry resource ID -AI_RESOURCE_ID=$(az cognitiveservices account show \ - -n $accountName \ - -g $resourceGroupName \ - --query "id" -o tsv) - -# Assign Cognitive Services User role -az role assignment create \ - --assignee $APIM_PRINCIPAL_ID \ - --role "Cognitive Services User" \ - --scope $AI_RESOURCE_ID -``` - -### Bicep Template for Backend Configuration - -```bicep -param apimServiceName string -param backendId string -param aiFoundryEndpoint string -param modelDeploymentName string - -resource apimService 'Microsoft.ApiManagement/service@2024-06-01-preview' existing = { - name: apimServiceName -} - -resource backend 'Microsoft.ApiManagement/service/backends@2024-06-01-preview' = { - parent: apimService - name: backendId - properties: { - protocol: 'http' - url: '${aiFoundryEndpoint}openai/deployments/${modelDeploymentName}' - credentials: { - header: {} - } - tls: { - validateCertificateChain: true - validateCertificateName: true - } - } -} -``` - -## Pattern 9: Import API from OpenAPI Specification +--- -Add an API to the gateway from an OpenAPI/Swagger specification, either from a local file or web URL. +## Quick Reference -### Step 1: Import API from Web URL +| 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) | -```bash -# Import API from a publicly accessible OpenAPI spec URL -az apim api import \ - --resource-group \ - --service-name \ - --api-id \ - --path \ - --display-name "" \ - --specification-format OpenApiJson \ - --specification-url "https://example.com/openapi.json" -``` +--- -### Step 2: Import API from Local File +## Get Gateway Details ```bash -# Import API from a local OpenAPI spec file (JSON or YAML) -az apim api import \ - --resource-group \ - --service-name \ - --api-id \ - --path \ - --display-name "" \ - --specification-format OpenApi \ - --specification-path "./openapi.yaml" -``` - -### Step 3: Configure Backend for the API +# Get gateway URL +az apim show --name --resource-group --query "gatewayUrl" -o tsv -```bash -# Create backend pointing to your API server -az apim backend create \ - --resource-group \ - --service-name \ - --backend-id \ - --protocol http \ - --url "https://your-api-server.com" - -# Update API to use the backend -az apim api update \ - --resource-group \ - --service-name \ - --api-id \ - --set properties.serviceUrl="https://your-api-server.com" -``` +# List backends (AI models) +az apim backend list --service-name --resource-group \ + --query "[].{id:name, url:url}" -o table -### Step 4: Apply Policies (Optional) - -```xml - - - - - - - - - - - +# Get subscription key +az apim subscription keys list \ + --service-name --resource-group --subscription-id ``` -### Supported Specification Formats - -| Format | Value | File Extension | -|--------|-------|----------------| -| OpenAPI 3.x JSON | `OpenApiJson` | `.json` | -| OpenAPI 3.x YAML | `OpenApi` | `.yaml`, `.yml` | -| Swagger 2.0 JSON | `SwaggerJson` | `.json` | -| Swagger 2.0 (link) | `SwaggerLinkJson` | URL | -| WSDL | `Wsdl` | `.wsdl` | -| WADL | `Wadl` | `.wadl` | - -## Pattern 10: Convert API to MCP Server - -Convert existing APIM API operations into an MCP (Model Context Protocol) server, enabling AI agents to discover and use your APIs as tools. - -### Prerequisites - -- APIM instance with Basicv2 SKU or higher -- Existing API imported into APIM -- MCP feature enabled on APIM +--- -### Step 1: List Existing APIs in APIM +## Test AI Endpoint ```bash -# List all APIs in APIM -az apim api list \ - --resource-group \ - --service-name \ - --query "[].{id:name, displayName:displayName, path:path}" \ - -o table -``` - -### Step 2: Ask User Which API to Convert - -After listing the APIs, **use the ask_user tool** to let the user select which API to convert to an MCP server. +GATEWAY_URL=$(az apim show --name --resource-group --query "gatewayUrl" -o tsv) -### Step 3: List API Operations - -```bash -# List all operations for the selected API -az apim api operation list \ - --resource-group \ - --service-name \ - --api-id \ - --query "[].{operationId:name, displayName:displayName, method:method, urlTemplate:urlTemplate}" \ - -o table +curl -X POST "${GATEWAY_URL}/openai/deployments//chat/completions?api-version=2024-02-01" \ + -H "Content-Type: application/json" \ + -H "Ocp-Apim-Subscription-Key: " \ + -d '{"messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}' ``` -### Step 4: Ask User Which Operations to Expose as MCP Tools +--- -After listing the operations, **use the ask_user tool** to present the operations as choices. Let the user select which operations to expose as MCP tools. Users may want to expose all operations or only a subset. +## Common Tasks -Example choices to present: -- All operations (convert entire API) -- Individual operations from the discovered list -- Include operation name, method, and URL template +### Add AI Backend -### Step 5: Enable MCP Server on APIM +See [references/patterns.md](references/patterns.md#pattern-1-add-ai-model-backend) for full steps. ```bash -# Enable MCP server capability (via ARM/Bicep or Portal) -# Note: MCP configuration is done via APIM policies and product configuration -``` +# Discover AI resources +az cognitiveservices account list --query "[?kind=='OpenAI']" -o table -### Step 6: Configure MCP Endpoint for API - -Create an MCP-compatible endpoint that exposes your API operations as tools: - -```xml - - - - - - - - - - application/json - - @{ - var tools = new JArray(); - // Define your API operations as MCP tools - tools.Add(new JObject( - new JProperty("name", "operation_name"), - new JProperty("description", "Description of what this operation does"), - new JProperty("inputSchema", new JObject( - new JProperty("type", "object"), - new JProperty("properties", new JObject( - new JProperty("param1", new JObject( - new JProperty("type", "string"), - new JProperty("description", "Parameter description") - )) - )) - )) - )); - return new JObject(new JProperty("tools", tools)).ToString(); - } - - - - - -``` - -### Step 7: Bicep Template for MCP-Enabled API - -```bicep -param apimServiceName string -param apiId string -param apiDisplayName string -param apiPath string -param backendUrl string - -resource apimService 'Microsoft.ApiManagement/service@2024-06-01-preview' existing = { - name: apimServiceName -} - -resource api 'Microsoft.ApiManagement/service/apis@2024-06-01-preview' = { - parent: apimService - name: apiId - properties: { - displayName: apiDisplayName - path: apiPath - protocols: ['https'] - serviceUrl: backendUrl - subscriptionRequired: true - // MCP endpoints - apiType: 'http' - } -} - -// MCP tools/list operation -resource mcpToolsListOperation 'Microsoft.ApiManagement/service/apis/operations@2024-06-01-preview' = { - parent: api - name: 'mcp-tools-list' - properties: { - displayName: 'MCP Tools List' - method: 'POST' - urlTemplate: '/mcp/tools/list' - description: 'List available MCP tools' - } -} - -// MCP tools/call operation -resource mcpToolsCallOperation 'Microsoft.ApiManagement/service/apis/operations@2024-06-01-preview' = { - parent: api - name: 'mcp-tools-call' - properties: { - displayName: 'MCP Tools Call' - method: 'POST' - urlTemplate: '/mcp/tools/call' - description: 'Call an MCP tool' - } -} -``` - -### Step 8: Test MCP Endpoint - -```bash -# Get APIM gateway URL -GATEWAY_URL=$(az apim show \ - --name \ - --resource-group \ - --query "gatewayUrl" -o tsv) - -# Test MCP tools/list endpoint -curl -X POST "${GATEWAY_URL}//mcp/tools/list" \ - -H "Content-Type: application/json" \ - -H "Ocp-Apim-Subscription-Key: " \ - -d '{}' -``` +# Create backend +az apim backend create --service-name --resource-group \ + --backend-id openai-backend --protocol http --url "https://.openai.azure.com/openai" -### MCP Tool Definition Schema - -When converting API operations to MCP tools, use this schema: - -```json -{ - "tools": [ - { - "name": "get_weather", - "description": "Get current weather for a location", - "inputSchema": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "City name or coordinates" - } - }, - "required": ["location"] - } - } - ] -} +# Grant access (managed identity) +az role assignment create --assignee \ + --role "Cognitive Services User" --scope ``` -### Reference - -- [MCP Server Overview](https://learn.microsoft.com/en-us/azure/api-management/mcp-server-overview) -- [MCP from API Lab](https://github.com/Azure-Samples/AI-Gateway/tree/main/labs/mcp-from-api) +### Apply AI Governance Policy -## Lab References (AI-Gateway Repo) +Recommended policy order in ``: -**Essential Labs to Get Started:** +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 -| Scenario | Lab | Description | -|----------|-----|-------------| -| Semantic Caching | [semantic-caching](https://github.com/Azure-Samples/AI-Gateway/tree/main/labs/semantic-caching) | Cache similar prompts to reduce costs | -| Token Rate Limiting | [token-rate-limiting](https://github.com/Azure-Samples/AI-Gateway/tree/main/labs/token-rate-limiting) | Limit tokens per minute | -| Content Safety | [content-safety](https://github.com/Azure-Samples/AI-Gateway/tree/main/labs/content-safety) | Filter harmful content | -| Load Balancing | [backend-pool-load-balancing](https://github.com/Azure-Samples/AI-Gateway/tree/main/labs/backend-pool-load-balancing) | Distribute load across backends | -| MCP from API | [mcp-from-api](https://github.com/Azure-Samples/AI-Gateway/tree/main/labs/mcp-from-api) | Convert OpenAPI to MCP server | -| Zero to Production | [zero-to-production](https://github.com/Azure-Samples/AI-Gateway/tree/main/labs/zero-to-production) | Complete production setup guide | +See [references/policies.md](references/policies.md#combining-policies) for complete example. -**Find more labs at:** https://github.com/Azure-Samples/AI-Gateway/tree/main/labs - -## Quick Start Checklist - -### Prerequisites -- [ ] Azure subscription created -- [ ] Azure CLI installed and authenticated (`az login`) -- [ ] Resource group created for AI Gateway resources +--- -### Deployment -- [ ] Deploy APIM with Basicv2 SKU -- [ ] Configure managed identity -- [ ] Add backend for Azure OpenAI or AI Foundry -- [ ] Apply policies (caching, rate limits, content safety) +## Troubleshooting -### Verification -- [ ] Test API endpoint through gateway -- [ ] Verify token metrics in Application Insights -- [ ] Check rate limiting headers in response -- [ ] Validate content safety filtering +| 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 | -## Best Practices +See [references/troubleshooting.md](references/troubleshooting.md) for details. -| Practice | Description | -|----------|-------------| -| **Default to Basicv2** | Use Basicv2 SKU for cost/speed optimization | -| **Use managed identity** | Prefer managed identity over API keys for backend auth | -| **Enable token metrics** | Use `azure-openai-emit-token-metric` for cost tracking | -| **Semantic caching** | Cache similar prompts to reduce costs (60-80% savings possible) | -| **Rate limit by key** | Use subscription ID or IP for granular rate limiting | -| **Content safety** | Enable `shield-prompt` to detect jailbreak attempts | +--- -## Troubleshooting +## References -| Issue | Symptom | Solution | -|-------|---------|----------| -| **Slow APIM creation** | Deployment takes 30+ minutes | Use Basicv2 SKU instead of Premium | -| **Token limit exceeded** | 429 response | Increase `tokens-per-minute` or add load balancing | -| **Cache not working** | No cache hits | Lower `score-threshold` (e.g., 0.7) | -| **Content blocked** | False positives | Increase category thresholds | -| **Backend auth fails** | 401 from Azure OpenAI | Assign Cognitive Services User role to APIM managed identity | -| **Rate limit too strict** | Legitimate requests blocked | Increase `calls` or `renewal-period` | +- [**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) - -## Additional Resources - -- [Azure API Management Documentation](https://learn.microsoft.com/azure/api-management/) -- [AI Gateway Samples Repository](https://github.com/Azure-Samples/AI-Gateway) -- [APIM Policies Reference](https://learn.microsoft.com/azure/api-management/api-management-policies) -- [Azure OpenAI Integration](https://learn.microsoft.com/azure/api-management/azure-openai-api-from-specification) diff --git a/.github/plugins/azure-skills/skills/azure-aigateway/references/auth-best-practices.md b/.github/plugins/azure-skills/skills/azure-aigateway/references/auth-best-practices.md new file mode 100644 index 00000000..6938d5f0 --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-aigateway/references/auth-best-practices.md @@ -0,0 +1,128 @@ +# Azure Authentication Best Practices + +> Source: [Microsoft — Passwordless connections for Azure services](https://learn.microsoft.com/azure/developer/intro/passwordless-overview) and [Azure Identity client libraries](https://learn.microsoft.com/dotnet/azure/sdk/authentication/). + +## Golden Rule + +Use **managed identities** and **Azure RBAC** in production. Reserve `DefaultAzureCredential` for **local development only**. + +## Authentication by Environment + +| Environment | Recommended Credential | Why | +|---|---|---| +| **Production (Azure-hosted)** | `ManagedIdentityCredential` (system- or user-assigned) | No secrets to manage; auto-rotated by Azure | +| **Production (on-premises)** | `ClientCertificateCredential` or `WorkloadIdentityCredential` | Deterministic; no fallback chain overhead | +| **CI/CD pipelines** | `AzurePipelinesCredential` / `WorkloadIdentityCredential` | Scoped to pipeline identity | +| **Local development** | `DefaultAzureCredential` | Chains CLI, PowerShell, and VS Code credentials for convenience | + +## Why Not `DefaultAzureCredential` in Production? + +1. **Unpredictable fallback chain** — walks through multiple credential types, adding latency and making failures harder to diagnose. +2. **Broad surface area** — checks environment variables, CLI tokens, and other sources that should not exist in production. +3. **Non-deterministic** — which credential actually authenticates depends on the environment, making behavior inconsistent across deployments. +4. **Performance** — each failed credential attempt adds network round-trips before falling back to the next. + +## Production Patterns + +### .NET + +```csharp +using Azure.Identity; + +var credential = Environment.GetEnvironmentVariable("AZURE_FUNCTIONS_ENVIRONMENT") == "Development" + ? new DefaultAzureCredential() // local dev — uses CLI/VS credentials + : new ManagedIdentityCredential(); // production — deterministic, no fallback chain +// For user-assigned identity: new ManagedIdentityCredential("") +``` + +### TypeScript / JavaScript + +```typescript +import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity"; + +const credential = process.env.NODE_ENV === "development" + ? new DefaultAzureCredential() // local dev — uses CLI/VS credentials + : new ManagedIdentityCredential(); // production — deterministic, no fallback chain +// For user-assigned identity: new ManagedIdentityCredential("") +``` + +### Python + +```python +import os +from azure.identity import DefaultAzureCredential, ManagedIdentityCredential + +credential = ( + DefaultAzureCredential() # local dev — uses CLI/VS credentials + if os.getenv("AZURE_FUNCTIONS_ENVIRONMENT") == "Development" + else ManagedIdentityCredential() # production — deterministic, no fallback chain +) +# For user-assigned identity: ManagedIdentityCredential(client_id="") +``` + +### Java + +```java +import com.azure.identity.DefaultAzureCredentialBuilder; +import com.azure.identity.ManagedIdentityCredentialBuilder; + +var credential = "Development".equals(System.getenv("AZURE_FUNCTIONS_ENVIRONMENT")) + ? new DefaultAzureCredentialBuilder().build() // local dev — uses CLI/VS credentials + : new ManagedIdentityCredentialBuilder().build(); // production — deterministic, no fallback chain +// For user-assigned identity: new ManagedIdentityCredentialBuilder().clientId("").build() +``` + +## Local Development Setup + +`DefaultAzureCredential` is ideal for local dev because it automatically picks up credentials from developer tools: + +1. **Azure CLI** — `az login` +2. **Azure Developer CLI** — `azd auth login` +3. **Azure PowerShell** — `Connect-AzAccount` +4. **Visual Studio / VS Code** — sign in via Azure extension + +```typescript +import { DefaultAzureCredential } from "@azure/identity"; + +// Local development only — uses CLI/PowerShell/VS Code credentials +const credential = new DefaultAzureCredential(); +``` + +## Environment-Aware Pattern + +Detect the runtime environment and select the appropriate credential. The key principle: use `DefaultAzureCredential` only when running locally, and a specific credential in production. + +> **Tip:** Azure Functions sets `AZURE_FUNCTIONS_ENVIRONMENT` to `"Development"` when running locally. For App Service or containers, use any environment variable you control (e.g. `NODE_ENV`, `ASPNETCORE_ENVIRONMENT`). + +```typescript +import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity"; + +function getCredential() { + if (process.env.NODE_ENV === "development") { + return new DefaultAzureCredential(); // picks up az login / VS Code creds + } + return process.env.AZURE_CLIENT_ID + ? new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID) // user-assigned + : new ManagedIdentityCredential(); // system-assigned +} +``` + +## Security Checklist + +- [ ] Use managed identity for all Azure-hosted apps +- [ ] Never hardcode credentials, connection strings, or keys +- [ ] Apply least-privilege RBAC roles at the narrowest scope +- [ ] Use `ManagedIdentityCredential` (not `DefaultAzureCredential`) in production +- [ ] Store any required secrets in Azure Key Vault +- [ ] Rotate secrets and certificates on a schedule +- [ ] Enable Microsoft Defender for Cloud on production resources + +## Further Reading + +- [Passwordless connections overview](https://learn.microsoft.com/azure/developer/intro/passwordless-overview) +- [Managed identities overview](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview) +- [Azure RBAC overview](https://learn.microsoft.com/azure/role-based-access-control/overview) +- [.NET authentication guide](https://learn.microsoft.com/dotnet/azure/sdk/authentication/) +- [Python identity library](https://learn.microsoft.com/python/api/overview/azure/identity-readme) +- [JavaScript identity library](https://learn.microsoft.com/javascript/api/overview/azure/identity-readme) +- [Java identity library](https://learn.microsoft.com/java/api/overview/azure/identity-readme) diff --git a/.github/plugins/azure-skills/skills/azure-aigateway/references/patterns.md b/.github/plugins/azure-skills/skills/azure-aigateway/references/patterns.md new file mode 100644 index 00000000..53397c46 --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-aigateway/references/patterns.md @@ -0,0 +1,226 @@ +# AI Gateway Configuration Patterns + +Step-by-step patterns for configuring Azure API Management as an AI Gateway. + +--- + +## Pattern 1: Add AI Model Backend + +Connect Azure OpenAI or AI Foundry models to your APIM instance. + +### Prerequisites + +- APIM instance deployed (use **azure-prepare** skill to deploy APIM — see [APIM deployment guide](https://learn.microsoft.com/azure/api-management/get-started-create-service-instance)) +- Azure OpenAI or AI Foundry resource provisioned +- System-assigned or user-assigned managed identity enabled on APIM + +### Steps + +#### 1. Discover AI Resources + +```bash +# Find Azure OpenAI resources +az cognitiveservices account list --query "[?kind=='OpenAI'].{name:name, rg:resourceGroup, endpoint:properties.endpoint}" -o table + +# Find AI Foundry resources (if using) +az cognitiveservices account list --query "[?kind=='AIServices'].{name:name, rg:resourceGroup}" -o table +``` + +#### 2. Enable Managed Identity on APIM + +```bash +# Enable system-assigned identity +az apim update --name --resource-group --set identity.type=SystemAssigned + +# Get principal ID +PRINCIPAL_ID=$(az apim show --name --resource-group --query "identity.principalId" -o tsv) +``` + +#### 3. Grant RBAC Access + +```bash +AOAI_ID=$(az cognitiveservices account show --name --resource-group --query id -o tsv) + +az role assignment create \ + --assignee "$PRINCIPAL_ID" \ + --role "Cognitive Services User" \ + --scope "$AOAI_ID" +``` + +#### 4. Create Backend + +```bash +az apim backend create \ + --service-name \ + --resource-group \ + --backend-id openai-backend \ + --protocol http \ + --url "https://.openai.azure.com/openai" +``` + +#### 5. Import API (OpenAPI Spec) + +```bash +# Import the Azure OpenAI API specification +az apim api import \ + --service-name \ + --resource-group \ + --api-id azure-openai-api \ + --path "openai" \ + --specification-format OpenApi \ + --specification-url "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/stable/2024-02-01/inference.json" \ + --service-url "https://.openai.azure.com/openai" +``` + +#### 6. Set Backend Policy + +Add managed identity authentication in ``: + +```xml + + + + + +``` + +--- + +## Pattern 2: Load Balance Across Multiple AI Backends + +Distribute requests across multiple Azure OpenAI instances for higher throughput. + +### Steps + +#### 1. Create Multiple Backends + +```bash +# Primary region +az apim backend create --service-name --resource-group \ + --backend-id openai-eastus --protocol http \ + --url "https://.openai.azure.com/openai" + +# Secondary region +az apim backend create --service-name --resource-group \ + --backend-id openai-westus --protocol http \ + --url "https://.openai.azure.com/openai" +``` + +#### 2. Create Backend Pool + +Using APIM backend pool (preview) or policy-based load balancing: + +```xml + + + + + + +``` + +#### 3. Add Circuit Breaker (Retry on 429) + +```xml + + + + + +``` + +--- + +## Pattern 3: Convert API to MCP Tool + +Expose an existing API through APIM as an MCP-compatible tool for AI agents. + +### Steps + +1. **Import API** into APIM using OpenAPI spec +2. **Add rate limiting** to protect the tool endpoint +3. **Add content safety** to filter harmful inputs +4. **Generate MCP manifest** pointing to the APIM endpoint + +```xml + + + + + +``` + +--- + +## Pattern 4: Add Streaming Support + +Configure APIM to properly handle Server-Sent Events (SSE) for streaming AI responses. + +```xml + + + + + + + + + @(context.Request.Body.As()["stream"]?.Value() == true + ? "text/event-stream" : "application/json") + + +``` + +> **Note**: Semantic caching and token metrics policies are NOT compatible with streaming responses. Use non-streaming for cost control scenarios. + +--- + +## Pattern 5: Multi-Tenant AI Gateway + +Isolate tenants with per-client rate limiting and tracking. + +```xml + + + + + + + + + + + + + + + + + +``` + +--- + +## Next Steps + +- Apply [governance policies](policies.md) to your configured backends +- Review [troubleshooting](troubleshooting.md) for common configuration issues diff --git a/.github/plugins/azure-skills/skills/azure-aigateway/references/policies.md b/.github/plugins/azure-skills/skills/azure-aigateway/references/policies.md new file mode 100644 index 00000000..127cabf3 --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-aigateway/references/policies.md @@ -0,0 +1,311 @@ +# AI Gateway Policies + +Complete reference for Azure API Management AI governance policies. + +--- + +## Policy Placement Order + +Recommended order in `` section: + +``` +1. Authentication (managed identity) +2. Semantic Cache Lookup +3. Token Rate Limiting +4. Content Safety +5. Backend Selection / Load Balancing +6. Token Metrics +``` + +--- + +## Model Policies + +### Token Rate Limiting + +Control costs by limiting token consumption per minute. + +```xml + +``` + +| Attribute | Purpose | Default | +|-----------|---------|---------| +| `tokens-per-minute` | Max tokens per counter window | Required | +| `counter-key` | Grouping key (subscription, IP, custom) | Required | +| `estimate-prompt-tokens` | Count prompt tokens toward limit | `true` | +| `tokens-consumed-header-name` | Response header with consumed count | — | +| `remaining-tokens-header-name` | Response header with remaining count | — | + +**Usage tiers example:** + +```xml + + + + + +``` + +--- + +### Semantic Caching + +Cache AI responses for semantically similar prompts. Saves 60-80% on repeated queries. + +**Lookup** (in ``): + +```xml + +``` + +**Store** (in ``): + +```xml + +``` + +| Attribute | Purpose | Recommended | +|-----------|---------|-------------| +| `score-threshold` | Similarity threshold (0-1) | 0.8 (lower = more cache hits) | +| `embeddings-backend-id` | Backend for embedding generation | Required | +| `embeddings-backend-auth` | Auth to embeddings backend | `system-assigned` | +| `duration` | Cache TTL in seconds | 3600 (1 hour) | + +**Prerequisites:** +- An embeddings model deployed (e.g., `text-embedding-ada-002`) +- A separate backend pointing to the embeddings endpoint +- Azure Cache for Redis Enterprise with RediSearch module (for vector storage) + +```bash +# Create embeddings backend +az apim backend create --service-name --resource-group \ + --backend-id embeddings-backend --protocol http \ + --url "https://.openai.azure.com/openai" +``` + +> **Note**: Semantic caching is NOT compatible with streaming responses (`"stream": true`). + +--- + +### Token Metrics + +Emit token usage metrics for monitoring and chargeback. + +```xml + + + + + + +``` + +Emits to Azure Monitor with these metrics: +- `Total Tokens` — prompt + completion combined +- `Prompt Tokens` — input tokens +- `Completion Tokens` — output tokens + +**Query token usage (KQL):** + +```kql +customMetrics +| where name == "Total Tokens" +| extend Subscription = tostring(customDimensions["Subscription"]) +| summarize TotalTokens = sum(value) by Subscription, bin(timestamp, 1h) +| order by TotalTokens desc +``` + +--- + +## Agent Policies + +### Content Safety + +Filter harmful, violent, or inappropriate content from AI inputs and outputs. + +```xml + + + + + + + +``` + +| Category | Description | Threshold Range | +|----------|-------------|-----------------| +| Hate | Discrimination, slurs | 0 (block all) - 6 (allow most) | +| Sexual | Explicit content | 0-6 | +| SelfHarm | Self-injury content | 0-6 | +| Violence | Violent content | 0-6 | + +**Prerequisites:** +- Azure AI Content Safety resource deployed +- Backend configured for the Content Safety endpoint: + +```bash +az apim backend create --service-name --resource-group \ + --backend-id contentsafety-backend --protocol http \ + --url "https://.cognitiveservices.azure.com" +``` + +--- + +### Jailbreak Detection + +Block prompt injection attacks that attempt to bypass AI safety guardrails. + +```xml + + + + + + + +``` + +Custom response for blocked content: + +```xml + + + + + + + {"error": "Request blocked by content safety policy"} + + + + +``` + +--- + +## Tool Policies + +### Request Rate Limiting + +Protect MCP tools and API endpoints from excessive requests. + +```xml + + +``` + +```xml + + +``` + +--- + +## Combining Policies + +Complete inbound policy example with all governance layers: + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 60 + + {"error": "Token rate limit exceeded. Try again later."} + + + + + +``` + +--- + +## Policy Quick-Decision Table + +| Need | Policy | Section | +|------|--------|---------| +| Control token spend | `azure-openai-token-limit` | `` | +| Cache similar prompts | `azure-openai-semantic-cache-lookup/store` | `` / `` | +| Track token usage | `azure-openai-emit-token-metric` | `` | +| Block harmful content | `llm-content-safety` | `` | +| Rate limit API calls | `rate-limit-by-key` | `` | +| Authenticate to backend | `authentication-managed-identity` | `` | +| Load balance backends | `set-backend-service` + retry | `` | + +--- + +## References + +- [GenAI Gateway Capabilities](https://learn.microsoft.com/azure/api-management/genai-gateway-capabilities) +- [APIM Policy Reference](https://learn.microsoft.com/azure/api-management/api-management-policies) +- [AI-Gateway Samples](https://github.com/Azure-Samples/AI-Gateway) diff --git a/.github/plugins/azure-skills/skills/azure-aigateway/references/sdk/azure-mgmt-apimanagement-dotnet.md b/.github/plugins/azure-skills/skills/azure-aigateway/references/sdk/azure-mgmt-apimanagement-dotnet.md index 40551fde..8f44361e 100644 --- a/.github/plugins/azure-skills/skills/azure-aigateway/references/sdk/azure-mgmt-apimanagement-dotnet.md +++ b/.github/plugins/azure-skills/skills/azure-aigateway/references/sdk/azure-mgmt-apimanagement-dotnet.md @@ -9,6 +9,8 @@ dotnet add package Azure.ResourceManager.ApiManagement dotnet add package Azure.Identity ## Quick Start +> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. + ```csharp using Azure.ResourceManager; using Azure.Identity; @@ -18,7 +20,7 @@ var armClient = new ArmClient(new DefaultAzureCredential()); ## Best Practices - Use `WaitUntil.Completed` for operations that must finish before proceeding - Use `WaitUntil.Started` for long operations like service creation (30+ min) -- Always use DefaultAzureCredential — never hardcode keys +- Use DefaultAzureCredential for **local development only**. In production, use ManagedIdentityCredential — see [auth-best-practices.md](../auth-best-practices.md) - Handle `RequestFailedException` for ARM API errors - Use `CreateOrUpdateAsync` for idempotent operations - Navigate hierarchy via `Get*` methods (e.g., `service.GetApis()`) diff --git a/.github/plugins/azure-skills/skills/azure-aigateway/references/sdk/azure-mgmt-apimanagement-py.md b/.github/plugins/azure-skills/skills/azure-aigateway/references/sdk/azure-mgmt-apimanagement-py.md index 25b968ba..b4c4cc75 100644 --- a/.github/plugins/azure-skills/skills/azure-aigateway/references/sdk/azure-mgmt-apimanagement-py.md +++ b/.github/plugins/azure-skills/skills/azure-aigateway/references/sdk/azure-mgmt-apimanagement-py.md @@ -8,6 +8,8 @@ pip install azure-mgmt-apimanagement azure-identity ## Quick Start +> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. + ```python import os from azure.mgmt.apimanagement import ApiManagementClient diff --git a/.github/plugins/azure-skills/skills/azure-aigateway/references/troubleshooting.md b/.github/plugins/azure-skills/skills/azure-aigateway/references/troubleshooting.md new file mode 100644 index 00000000..a46f3b49 --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-aigateway/references/troubleshooting.md @@ -0,0 +1,270 @@ +# AI Gateway Troubleshooting + +Common issues when using Azure API Management as an AI Gateway. + +--- + +## Authentication Issues + +### 401 Unauthorized from Backend + +**Symptom**: APIM returns `401` when calling Azure OpenAI. + +**Causes & Solutions**: + +| Cause | Fix | +|-------|-----| +| Managed identity not enabled on APIM | `az apim update --name --resource-group --set identity.type=SystemAssigned` | +| Missing RBAC role | `az role assignment create --assignee --role "Cognitive Services User" --scope ` | +| Wrong auth resource | Ensure `resource="https://cognitiveservices.azure.com"` (not the endpoint URL) | +| RBAC propagation delay | Wait 5-10 minutes after role assignment | + +**Diagnostic**: + +```bash +# Verify identity is enabled +az apim show --name --resource-group --query "identity" -o json + +# Check role assignments +AOAI_ID=$(az cognitiveservices account show --name --resource-group --query id -o tsv) +az role assignment list --scope "$AOAI_ID" --query "[?principalType=='ServicePrincipal'].{role:roleDefinitionName, principal:principalId}" -o table +``` + +--- + +## Rate Limiting Issues + +### 429 Token Limit Exceeded + +**Symptom**: Requests blocked with `429 Too Many Requests` from `azure-openai-token-limit` policy. + +**Solutions**: + +1. **Increase limit**: Raise `tokens-per-minute` value +2. **Add more backends**: Load balance across regions for higher aggregate TPM +3. **Enable semantic caching**: Reduce actual token consumption by serving cached responses +4. **Switch counter-key**: Use per-user instead of global to prevent one user from exhausting the pool + +```xml + + +``` + +### 429 from Azure OpenAI (Not APIM) + +**Symptom**: Backend returns `429` even though APIM token limits are not exceeded. + +**Cause**: Azure OpenAI's own TPM quota is exhausted. + +**Solutions**: + +1. Increase Azure OpenAI deployment TPM quota in the portal +2. Add load balancing across multiple Azure OpenAI instances +3. Use retry with backoff: + +```xml + + + +``` + +--- + +## Semantic Caching Issues + +### No Cache Hits + +**Symptom**: Semantic cache is configured but cache hit rate is 0%. + +**Causes & Solutions**: + +| Cause | Fix | +|-------|-----| +| `score-threshold` too high | Lower from 0.9 to 0.7 (more matches) | +| Embeddings backend misconfigured | Verify backend URL and auth | +| Redis not configured | Deploy Azure Cache for Redis Enterprise with RediSearch | +| Streaming requests | Semantic caching doesn't work with `"stream": true` | + +**Verify caching is working**: + +```bash +# Check cache-related headers in response +curl -v -X POST "${GATEWAY_URL}/openai/deployments//chat/completions?api-version=2024-02-01" \ + -H "Content-Type: application/json" \ + -H "Ocp-Apim-Subscription-Key: " \ + -d '{"messages": [{"role": "user", "content": "What is Azure?"}], "max_tokens": 100}' + +# Look for: x-cache-status header in response +``` + +### Cache Returns Stale Data + +**Solution**: Reduce `duration` in `azure-openai-semantic-cache-store`: + +```xml + + +``` + +--- + +## Content Safety Issues + +### False Positives (Legitimate Content Blocked) + +**Symptom**: Normal business content is being blocked by content safety policy. + +**Solutions**: + +1. **Increase thresholds** (less strict): + +```xml + + + + + + +``` + +2. **Log blocked content** for review: + +```xml + + + + + @{ + return new JObject( + new JProperty("blocked", true), + new JProperty("subscription", context.Subscription.Id), + new JProperty("timestamp", DateTime.UtcNow) + ).ToString(); + } + + + + {"error": "Content filtered by safety policy"} + + + + +``` + +### Content Safety Backend Error + +**Symptom**: `500` error from `llm-content-safety` policy. + +**Causes**: + +| Cause | Fix | +|-------|-----| +| Content Safety resource not deployed | Deploy Azure AI Content Safety resource | +| Backend URL wrong | Check `contentsafety-backend` URL matches resource endpoint | +| Missing RBAC | Grant APIM "Cognitive Services User" on the Content Safety resource | +| Region mismatch | Content Safety must be in a supported region | + +--- + +## Backend Configuration Issues + +### Backend Not Found + +**Symptom**: `500` error with "Backend not found" message. + +```bash +# Verify backend exists +az apim backend list --service-name --resource-group \ + --query "[].{id:name, url:url}" -o table + +# Check backend ID matches policy reference +``` + +### Timeout on AI Requests + +**Symptom**: Requests timeout, especially for large context windows or complex prompts. + +**Solution**: Increase timeout in ``: + +```xml + + + + +``` + +--- + +## Diagnostic Tools + +### APIM Tracing + +Enable request tracing for debugging policy flow: + +```bash +# Get tracing subscription key +az apim subscription list --service-name --resource-group \ + --query "[?displayName=='Built-in all-access subscription'].primaryKey" -o tsv + +# Send request with tracing +curl -X POST "${GATEWAY_URL}/..." \ + -H "Ocp-Apim-Trace: true" \ + -H "Ocp-Apim-Subscription-Key: " +``` + +### Application Insights + +If APIM is connected to Application Insights: + +```kql +// Failed AI gateway requests +requests +| where success == false +| where url contains "openai" +| project timestamp, resultCode, duration, url +| order by timestamp desc +| take 20 + +// Token metrics over time +customMetrics +| where name == "Total Tokens" +| summarize TotalTokens = sum(value) by bin(timestamp, 1h) +| render timechart + +// Content safety blocks +traces +| where message contains "content-safety" +| project timestamp, message, customDimensions +| order by timestamp desc +``` + +### Health Check + +Quick validation that the AI Gateway is functioning: + +```bash +# 1. Check APIM is running +az apim show --name --resource-group --query "provisioningState" -o tsv +# Expected: Succeeded + +# 2. Check backends +az apim backend list --service-name --resource-group -o table + +# 3. Test endpoint +curl -s -o /dev/null -w "%{http_code}" "${GATEWAY_URL}/openai/deployments//chat/completions?api-version=2024-02-01" \ + -H "Ocp-Apim-Subscription-Key: " \ + -H "Content-Type: application/json" \ + -d '{"messages": [{"role": "user", "content": "ping"}], "max_tokens": 5}' +# Expected: 200 +``` + +--- + +## References + +- [APIM Diagnostics](https://learn.microsoft.com/azure/api-management/diagnose-solve-problems) +- [AI Gateway Monitoring](https://learn.microsoft.com/azure/api-management/genai-gateway-capabilities#monitoring-and-analytics) +- [APIM Error Handling](https://learn.microsoft.com/azure/api-management/api-management-error-handling-policies) diff --git a/.github/plugins/azure-skills/skills/azure-cloud-migrate/SKILL.md b/.github/plugins/azure-skills/skills/azure-cloud-migrate/SKILL.md new file mode 100644 index 00000000..868d9ce7 --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-cloud-migrate/SKILL.md @@ -0,0 +1,43 @@ +--- +name: azure-cloud-migrate +description: "Assess and migrate cross-cloud workloads to Azure. Generates assessment reports and converts code from AWS, GCP, or other providers to Azure services. WHEN: migrate Lambda to Azure Functions, migrate AWS to Azure, Lambda migration assessment, convert AWS serverless to Azure, migration readiness report, migrate from AWS, migrate from GCP, cross-cloud migration." +license: MIT +metadata: + author: Microsoft + version: "1.0.0" +--- + +# 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_bestpractices` and `mcp_azure_mcp_documentation` MCP tools +5. Use the latest supported runtime for the target service +6. Destructive actions require `ask_user` — [global-rules](references/services/functions/global-rules.md) + +## Migration Scenarios + +| Source | Target | Reference | +|--------|--------|-----------| +| AWS Lambda | Azure Functions | [lambda-to-functions.md](references/services/functions/lambda-to-functions.md) | + +> No matching scenario? Use `mcp_azure_mcp_documentation` and `mcp_azure_mcp_get_bestpractices` tools. + +## Output Directory + +All output goes to `-azure/` at workspace root. Never modify the source directory. + +## Steps + +1. **Create** `-azure/` at workspace root +2. **Assess** — Analyze source, map services, generate report → [assessment.md](references/services/functions/assessment.md) +3. **Migrate** — Convert code using target programming model → [code-migration.md](references/services/functions/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). diff --git a/.github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/assessment.md b/.github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/assessment.md new file mode 100644 index 00000000..8b1e5dbf --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/assessment.md @@ -0,0 +1,154 @@ +# Assessment Phase + +Generate a migration assessment report before any code changes. + +## Prerequisites + +- Workspace contains AWS Lambda functions, SAM templates, or CloudFormation templates +- Prompt user to upload relevant files if not present + +## Assessment Steps + +1. **Identify Functions** — List all Lambda functions with runtimes, triggers, and dependencies +2. **Map AWS Services** — Map AWS services to Azure equivalents (see [lambda-to-functions.md](lambda-to-functions.md)) +3. **Map Properties** — Map Lambda properties to Azure Functions properties +4. **Check Dependencies** — List 3rd-party libraries and verify Azure compatibility +5. **Analyze Code** — Check language support and runtime differences +6. **Map Triggers** — Identify equivalent Azure Functions triggers +7. **Map Deployment** — Identify equivalent Azure deployment strategies (CLI, Bicep, azd) +8. **Review CI/CD** — Check pipeline compatibility with Azure DevOps or GitHub Actions +9. **Map Monitoring** — Map CloudWatch → Application Insights / Azure Monitor + +## Code Preview + +During assessment, show a **sneak peek** of what the migrated Azure Functions code will look like for each function. Use bindings and triggers (not SDKs) in all previews, following Azure Functions best practices. **Always use the newest generally available (GA) language runtime listed in the Azure Functions supported languages documentation** in previews (for example, the latest Node.js LTS or newest Python GA version). This helps the user understand the migration scope before committing to code migration. + +> ⚠️ **Binding-first rule**: Code previews MUST use `input.storageBlob()`, `output.storageBlob()`, `app.storageQueue()`, etc. instead of `BlobServiceClient`, `QueueClient`, or other SDK clients. Only use SDK for services that have no binding equivalent. + +## Architecture Diagrams + +Generate two diagrams: +1. **Current State** — AWS Lambda architecture with triggers and integrations +2. **Target State** — Azure Functions architecture showing equivalent structure + +## Assessment Report Format + +> ⚠️ **MANDATORY**: Use these exact section headings in every assessment report. Do NOT rename, reorder, or omit sections. + +The report MUST be saved as `migration-assessment-report.md` inside the output directory (`-azure/`). + +```markdown +# Migration Assessment Report + +## 1. Executive Summary + +| Property | Value | +|----------|-------| +| **Total Functions** | | +| **Source Platform** | AWS Lambda | +| **Source Runtime** | | +| **Target Platform** | Azure Functions | +| **Target Runtime** | | +| **Migration Readiness** | | +| **Estimated Effort** | | +| **Assessment Date** | | + +## 2. Functions Inventory + +| # | Function Name | Runtime | Trigger Type | Memory (MB) | Timeout (s) | Description | +|---|--------------|---------|-------------- |-------------|-------------|-------------| +| 1 | | | | | | | + +## 3. Service Mapping + +| AWS Service | Azure Equivalent | Migration Complexity | Notes | +|-------------|------------------|----------------------|-------| +| Lambda | Azure Functions | | | +| API Gateway | Azure Functions HTTP Trigger / APIM | | | +| S3 | Azure Blob Storage | | | +| DynamoDB | Cosmos DB | | | +| SQS | Service Bus / Storage Queue | | | +| SNS | Event Grid | | | +| CloudWatch | Application Insights / Azure Monitor | | | +| IAM Roles | Managed Identity + RBAC | | | +| CloudFormation / SAM | Bicep / ARM Templates | | | + +## 4. Trigger & Binding Mapping + +| # | Function Name | AWS Trigger | Azure Trigger | AWS Inputs/Outputs | Azure Bindings | Notes | +|---|--------------|-------------|---------------|--------------------| ---------------|-------| +| 1 | | | | | | | + +## 5. Dependencies Analysis + +| # | Package/Library | Version | AWS-Specific? | Azure Equivalent | Compatible? | Notes | +|---|----------------|---------|---------------|------------------|-------------|-------| +| 1 | | | | | | | + +## 6. Environment Variables & Configuration + +| # | AWS Variable | Purpose | Azure Equivalent | Auth Method | Notes | +|---|-------------|---------|------------------|-------------|-------| +| 1 | | | | Managed Identity / App Setting | | + +## 7. Architecture Diagrams + +### 7a. Current State (AWS) + + + +### 7b. Target State (Azure) + + + +## 8. IAM & Security Mapping + +| AWS IAM Role/Policy | Azure RBAC Role | Scope | Notes | +|---------------------|-----------------|-------|-------| +| | | | | + +## 9. Monitoring & Observability Mapping + +| AWS Service | Azure Equivalent | Migration Notes | +|-------------|------------------|-----------------| +| CloudWatch Logs | Application Insights | | +| CloudWatch Metrics | Azure Monitor Metrics | | +| CloudWatch Alarms | Azure Monitor Alerts | | +| X-Ray | Application Insights (distributed tracing) | | + +## 10. CI/CD & Deployment Mapping + +| AWS Tool | Azure Equivalent | Notes | +|----------|------------------|-------| +| SAM CLI | Azure Functions Core Tools / azd | | +| CloudFormation | Bicep / ARM Templates | | +| CodePipeline | Azure DevOps Pipelines / GitHub Actions | | +| CodeBuild | Azure DevOps Build / GitHub Actions | | + +## 11. Project Structure Comparison + +| AWS Lambda Structure | Azure Functions Structure | +|---------------------|--------------------------| +| `template.yaml` (SAM) | `host.json` | +| `handler.js / handler.py` | `src/app.js` / `src/function_app.py` | +| `requirements.txt` / `package.json` | `requirements.txt` / `package.json` | +| Per-function directories (optional) | Single entry point (v4 JS / v2 Python) | +| `event` object | Trigger-specific parameter | +| `context` object | `InvocationContext` | + +## 12. Recommendations + +1. **Runtime**: +2. **Hosting Plan**: +3. **IaC Strategy**: +4. **Auth Strategy**: +5. **Monitoring**: + +## 13. Next Steps + +- [ ] Review and approve this assessment report +- [ ] Proceed to code migration (azure-cloud-migrate Phase 2) +- [ ] Hand off to azure-prepare for IaC generation +``` + +> 💡 **Tip:** Use `mcp_azure_mcp_get_bestpractices` tool to learn Azure Functions project structure best practices for the comparison. diff --git a/.github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/code-migration.md b/.github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/code-migration.md new file mode 100644 index 00000000..8cab61f9 --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-cloud-migrate/references/services/functions/code-migration.md @@ -0,0 +1,138 @@ +# Code Migration Phase + +Migrate AWS Lambda function code to Azure Functions. + +## Prerequisites + +- Assessment report completed +- Azure Functions extension installed in VS Code +- Best practices loaded via `mcp_azure_mcp_get_bestpractices` tool + +## Rules + +- If runtime is Python or Node.js: **do NOT create function.json files** +- If runtime is .NET (in-process or isolated) or Java: **do NOT hand-author function.json** — bindings metadata is generated from attributes/annotations at build time +- Use extension bundle version `[4.*, 5.0.0)` in host.json +- Use latest programming model (v4 for JavaScript, v2 for Python) +- **Always use bindings and triggers instead of SDKs** — For blob read/write, use `input.storageBlob()` / `output.storageBlob()` with `extraInputs`/`extraOutputs`. For queues, use `app.storageQueue()` or `app.serviceBusQueue()`. Only use SDK when there is no equivalent binding (e.g., Azure AI, custom HTTP calls) +- **Always use the latest supported language runtime** — Consult [supported languages](https://learn.microsoft.com/en-us/azure/azure-functions/supported-languages) and select the newest GA version. Do NOT default to an older LTS version when a newer version is available on Azure Functions. + +## Steps + +1. **Install Azure Functions Extension** — Ensure VS Code extension is installed +2. **Load Best Practices** — Use `mcp_azure_mcp_get_bestpractices` tool for code generation guidance +3. **Create Project Structure** — Set up the Azure Functions project inside the output directory (`-azure/`). Do NOT create files inside the original AWS directory +4. **Migrate Functions** — Convert each Lambda function to Azure Functions equivalent +5. **Update Dependencies** — Replace AWS SDKs with Azure SDKs in package.json / requirements.txt +6. **Configure Bindings** — Set up triggers and bindings inline (v4 JS / v2 Python) +7. **Configure Environment** — Map Lambda env vars to Azure Functions app settings +8. **Add Error Handling** — Ensure proper error handling in all functions + +## Key Configuration Files + +### host.json + +```json +{ + "version": "2.0", + "extensionBundle": { + "id": "Microsoft.Azure.Functions.ExtensionBundle", + "version": "[4.*, 5.0.0)" + }, + "extensions": { + "queues": { + "maxPollingInterval": "00:00:02", + "visibilityTimeout": "00:00:30", + "batchSize": 1, + "maxDequeueCount": 5 + } + }, + "logging": { + "applicationInsights": { + "samplingSettings": { + "isEnabled": true, + "excludedTypes": "Request" + } + } + } +} +``` + +## Critical Infrastructure Dependencies + +### Blob Trigger with EventGrid Source — Additional Requirements + +When migrating S3 event triggers to Azure blob triggers with `source: 'EventGrid'`, the following infrastructure must be configured **at the IaC level** (not code level). Failure to set these up results in silent trigger failures. + +| Requirement | Why | Consequence of Missing | +|------------|-----|----------------------| +| **Queue endpoint** (`AzureWebJobsStorage__queueServiceUri`) | Blob extension uses queues internally for poison-message tracking with EventGrid source | Function fails to index: "Unable to find matching constructor...QueueServiceClient" | +| **Always-ready instances** (Flex Consumption only) | Blob trigger group must be running to register the Event Grid webhook | Trigger group never starts → webhook never registered → events never delivered | +| **Event Grid subscription via Bicep/ARM** | CLI-based webhook validation handshake times out on Flex Consumption | Use `listKeys()` in Bicep to obtain the `blobs_extension` system key at deployment time | +| **Storage Queue Data Contributor** RBAC | Identity-based queue access for poison messages | 403 errors during blob trigger indexing | + +See [lambda-to-functions.md](lambda-to-functions.md#flex-consumption--blob-trigger-with-eventgrid-source) for Bicep patterns. + +### UAMI Credential Pattern + +When using User Assigned Managed Identity (UAMI), `DefaultAzureCredential()` without arguments tries System Assigned first and fails. Always pass the client ID: + +```javascript +const credential = new DefaultAzureCredential({ + managedIdentityClientId: process.env.AZURE_CLIENT_ID +}); +``` + +Add `AZURE_CLIENT_ID` as an app setting in Bicep pointing to the UAMI client ID. + +### azd init Workaround for Non-Empty Directories + +`azd init --template