From 0447a624f8437a79b0339d6d43520fa3d11826b0 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 1 Apr 2026 11:20:00 +0000 Subject: [PATCH] Sync plugin files from GitHub-Copilot-for-Azure --- .../azure-skills/.claude-plugin/plugin.json | 2 +- .../plugins/azure-skills/.plugin/plugin.json | 2 +- .../azure-skills/skills/azure-deploy/SKILL.md | 16 +- .../references/live-role-verification.md | 102 +++++++++++++ .../references/recipes/azcli/README.md | 2 +- .../references/recipes/azd/README.md | 2 +- .../recipes/azd/functions-deploy.md | 2 +- .../references/recipes/bicep/README.md | 2 +- .../references/recipes/cicd/README.md | 2 +- .../references/recipes/terraform/README.md | 2 +- .../azure-enterprise-infra-planner/SKILL.md | 10 +- .../references/bicep-generation.md | 24 +-- .../references/deployment.md | 22 +-- .../references/pairing-checks.md | 2 +- .../references/research.md | 44 +++--- .../references/terraform-generation.md | 16 +- .../references/verification.md | 4 +- .../references/waf-checklist.md | 28 ++-- .../references/workflow.md | 46 +++--- .../skills/azure-prepare/SKILL.md | 29 ++-- .../azure-prepare/references/architecture.md | 2 +- .../azure-prepare/references/azure-context.md | 2 +- .../references/functional-verification.md | 76 ++++++++++ .../azure-prepare/references/generate.md | 6 +- .../azure-prepare/references/plan-template.md | 6 +- .../references/recipe-selection.md | 2 +- .../references/recipes/azcli/README.md | 2 +- .../references/recipes/azd/README.md | 2 +- .../references/recipes/bicep/README.md | 2 +- .../references/recipes/terraform/README.md | 2 +- .../azure-prepare/references/requirements.md | 26 +++- .../azure-prepare/references/research.md | 4 +- .../references/resources-limits-quotas.md | 2 +- .../skills/azure-validate/SKILL.md | 20 +-- .../references/recipes/azcli/README.md | 13 ++ .../references/recipes/azcli/errors.md | 1 + .../references/recipes/azd/README.md | 28 +++- .../references/recipes/azd/errors.md | 1 + .../references/role-verification.md | 75 ++++++++++ .../skills/entra-app-registration/SKILL.md | 15 +- .../references/auth-best-practices.md | 137 ++++++++---------- .../references/sdk/azure-identity-dotnet.md | 19 +-- .../references/sdk/azure-identity-go.md | 37 ----- .../references/sdk/azure-identity-java.md | 18 +-- .../references/sdk/azure-identity-py.md | 16 +- .../references/sdk/azure-identity-rust.md | 16 +- .../references/sdk/azure-identity-ts.md | 16 +- .../references/sdk/azure-keyvault-py.md | 19 +-- .../sdk/azure-keyvault-secrets-ts.md | 14 +- ...extensions-authentication-events-dotnet.md | 9 +- 50 files changed, 570 insertions(+), 377 deletions(-) create mode 100644 .github/plugins/azure-skills/skills/azure-deploy/references/live-role-verification.md create mode 100644 .github/plugins/azure-skills/skills/azure-prepare/references/functional-verification.md create mode 100644 .github/plugins/azure-skills/skills/azure-validate/references/role-verification.md delete mode 100644 .github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-go.md diff --git a/.github/plugins/azure-skills/.claude-plugin/plugin.json b/.github/plugins/azure-skills/.claude-plugin/plugin.json index 2079bd73..60fc0f4b 100644 --- a/.github/plugins/azure-skills/.claude-plugin/plugin.json +++ b/.github/plugins/azure-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "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.5", + "version": "1.0.6", "author": { "name": "Microsoft", "url": "https://www.microsoft.com" diff --git a/.github/plugins/azure-skills/.plugin/plugin.json b/.github/plugins/azure-skills/.plugin/plugin.json index 2ca10844..2e487a8d 100644 --- a/.github/plugins/azure-skills/.plugin/plugin.json +++ b/.github/plugins/azure-skills/.plugin/plugin.json @@ -1,7 +1,7 @@ { "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.5", + "version": "1.0.6", "author": { "name": "Microsoft", "url": "https://www.microsoft.com" diff --git a/.github/plugins/azure-skills/skills/azure-deploy/SKILL.md b/.github/plugins/azure-skills/skills/azure-deploy/SKILL.md index 9acf3d42..25aee0e6 100644 --- a/.github/plugins/azure-skills/skills/azure-deploy/SKILL.md +++ b/.github/plugins/azure-skills/skills/azure-deploy/SKILL.md @@ -1,10 +1,10 @@ --- name: azure-deploy -description: "Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/plan.md from azure-prepare and validated status from azure-validate. WHEN: \"run azd up\", \"run azd deploy\", \"execute deployment\", \"push to production\", \"push to cloud\", \"go live\", \"ship it\", \"bicep deploy\", \"terraform apply\", \"publish to Azure\", \"launch on Azure\". DO NOT USE WHEN: \"create and deploy\", \"build and deploy\", \"create a new app\", \"set up infrastructure\", \"create and deploy to Azure using Terraform\" — use azure-prepare for these." +description: "Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: \"run azd up\", \"run azd deploy\", \"execute deployment\", \"push to production\", \"push to cloud\", \"go live\", \"ship it\", \"bicep deploy\", \"terraform apply\", \"publish to Azure\", \"launch on Azure\". DO NOT USE WHEN: \"create and deploy\", \"build and deploy\", \"create a new app\", \"set up infrastructure\", \"create and deploy to Azure using Terraform\" — use azure-prepare for these." license: MIT metadata: author: Microsoft - version: "1.0.8" + version: "1.0.10" --- # Azure Deploy @@ -16,7 +16,7 @@ metadata: > **⛔ STOP — PREREQUISITE CHECK REQUIRED** > Before proceeding, verify BOTH prerequisites are met: > -> 1. **azure-prepare** was invoked and completed → `.azure/plan.md` exists +> 1. **azure-prepare** was invoked and completed → `.azure/deployment-plan.md` exists > 2. **azure-validate** was invoked and passed → plan status = `Validated` > > If EITHER is missing, **STOP IMMEDIATELY**: @@ -47,7 +47,7 @@ Activate this skill when user wants to: ## Rules 1. Run after azure-prepare and azure-validate -2. `.azure/plan.md` must exist with status `Validated` +2. `.azure/deployment-plan.md` must exist with status `Validated` 3. **Pre-deploy checklist required** — [Pre-Deploy Checklist](references/pre-deploy-checklist.md) 4. ⛔ **Destructive actions require `ask_user`** — [global-rules](references/global-rules.md) 5. **Scope: deployment execution only** — This skill owns execution of `azd up`, `azd deploy`, `terraform apply`, and `az deployment` commands. These commands are run through this skill's error recovery and verification pipeline. @@ -58,14 +58,15 @@ Activate this skill when user wants to: | # | Action | Reference | |---|--------|-----------| -| 1 | **Check Plan** — Read `.azure/plan.md`, verify status = `Validated` AND **Validation Proof** section is populated | `.azure/plan.md` | +| 1 | **Check Plan** — Read `.azure/deployment-plan.md`, verify status = `Validated` AND **Validation Proof** section is populated | `.azure/deployment-plan.md` | | 2 | **Pre-Deploy Checklist** — MUST complete ALL steps | [Pre-Deploy Checklist](references/pre-deploy-checklist.md) | -| 3 | **Load Recipe** — Based on `recipe.type` in `.azure/plan.md` | [recipes/README.md](references/recipes/README.md) | +| 3 | **Load Recipe** — Based on `recipe.type` in `.azure/deployment-plan.md` | [recipes/README.md](references/recipes/README.md) | | 4 | **Execute Deploy** — Follow recipe steps | Recipe README | | 5 | **Post-Deploy** — Configure SQL managed identity and apply EF migrations if applicable | [Post-Deployment](references/recipes/azd/post-deployment.md) | | 6 | **Handle Errors** — See recipe's `errors.md` | — | | 7 | **Verify Success** — Confirm deployment completed and endpoints are accessible | [Verification](references/recipes/azd/verify.md) | -| 8 | **Report Results** — Present deployed endpoint URLs to the user as fully-qualified `https://` links | [Verification](references/recipes/azd/verify.md) | +| 8 | **Live Role Verification** — Query Azure to confirm provisioned RBAC roles are correct and sufficient | [live-role-verification.md](references/live-role-verification.md) | +| 9 | **Report Results** — Present deployed endpoint URLs to the user as fully-qualified `https://` links | [Verification](references/recipes/azd/verify.md) | > **⛔ URL FORMAT RULE** > @@ -87,6 +88,7 @@ Activate this skill when user wants to: | `mcp_azure_mcp_subscription_list` | List available subscriptions | | `mcp_azure_mcp_group_list` | List resource groups in subscription | | `mcp_azure_mcp_azd` | Execute AZD commands | +| `azure__role` | List role assignments for live RBAC verification (step 8) | ## References diff --git a/.github/plugins/azure-skills/skills/azure-deploy/references/live-role-verification.md b/.github/plugins/azure-skills/skills/azure-deploy/references/live-role-verification.md new file mode 100644 index 00000000..7a8c23f2 --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-deploy/references/live-role-verification.md @@ -0,0 +1,102 @@ +# Live Role Verification + +Query Azure to confirm that provisioned RBAC role assignments are correct and sufficient for the application to function. This complements the static role check in azure-validate by validating **live Azure state**. + +## How It Differs from azure-validate's Role Check + +| Check | Skill | What It Verifies | +|-------|-------|-----------------| +| **Static** | azure-validate | Generated Bicep/Terraform has correct role assignments in code | +| **Live** | azure-deploy (this) | Provisioned Azure resources actually have the right roles assigned | + +Both checks are needed because: +- Bicep may be correct but provisioning could fail silently for roles +- Manual changes or policy enforcement may alter role assignments +- Previous deployments may have stale or conflicting roles + +## When to Run + +After deployment verification (step 7). Resources are now provisioned, so live role assignments can be queried. + +## Verification Steps + +### 1. Identify App Identities + +Read `.azure/deployment-plan.md` to find all services with managed identities. Then query Azure for their principal IDs: + +```bash +# App Service +az webapp identity show --name -g --query principalId -o tsv + +# Container App +az containerapp identity show --name -g --query principalId -o tsv + +# Function App +az functionapp identity show --name -g --query principalId -o tsv +``` + +### 2. Query Live Role Assignments + +Use MCP tools to list role assignments for each resource **and identity** (using the `principalId` from step 1): + +``` +azure__role( + command: "role_assignment_list", + scope: "", + assignee_object_id: "" +) +``` + +Or via CLI: + +```bash +az role assignment list --scope --assignee-object-id --output table +``` + +### 3. Cross-Check Against Requirements + +For each identity, verify the assigned roles match what the app needs: + +| App Operation | Expected Role | Scope | +|---------------|---------------|-------| +| Read/write blobs | Storage Blob Data Contributor | Storage account | +| Generate user delegation SAS | Storage Blob Delegator | Storage account | +| Read secrets | Key Vault Secrets User | Key Vault | +| Send messages | Azure Service Bus Data Sender | Service Bus namespace | +| Read/write documents | Cosmos DB Built-in Data Contributor | Cosmos DB account | + +### 4. Check for Common Issues + +| Issue | How to Detect | Fix | +|-------|---------------|-----| +| Role assigned at wrong scope | Role on resource group but needed on specific resource | Reassign at resource scope | +| Generic role instead of data role | `Contributor` assigned but no data-plane access | Replace with data-plane role (e.g., `Storage Blob Data Contributor`) | +| Missing role entirely | No assignment found for identity on target resource | Add role assignment to Bicep and redeploy | +| Stale role from previous deployment | Old principal ID with roles, new identity without | Clean up old assignments, add new ones | + +## Decision Tree + +``` +Resources provisioned? +├── No → Skip live check (nothing to query yet) +└── Yes → For each app identity: + ├── Query role assignments on target resources + ├── Compare against expected roles from plan + │ ├── All roles present and correct → ✅ Pass + │ ├── Missing roles → ❌ Fail — add to Bicep, redeploy + │ └── Wrong scope or generic roles → ⚠️ Warning — fix and redeploy + └── Record results in deployment verification +``` + +## Record in Deployment Verification + +Add live role verification results to the deployment log in `.azure/plan.md`: + +```markdown +### Live Role Verification +- Command: `az role assignment list --scope --assignee-object-id ` +- Results: + - → on ✅ + - → missing on ❌ +- Status: Pass / Fail +``` diff --git a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azcli/README.md b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azcli/README.md index 1f65fbca..05cc4614 100644 --- a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azcli/README.md +++ b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azcli/README.md @@ -5,7 +5,7 @@ Deploy to Azure using Azure CLI. ## Prerequisites - `az` CLI installed → Run `mcp_azure_mcp_extension_cli_install` with `cli-type: az` if needed -- `.azure/plan.md` exists with status `Validated` +- `.azure/deployment-plan.md` exists with status `Validated` - Bicep/ARM templates exist in `infra/` - **Subscription and location confirmed** → See [Pre-Deploy Checklist](../../pre-deploy-checklist.md) diff --git a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/README.md b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/README.md index e813b7b7..07ccff0f 100644 --- a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/README.md +++ b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/README.md @@ -7,7 +7,7 @@ Deploy to Azure using Azure Developer CLI (azd). ## Prerequisites - `azd` CLI installed → Run `mcp_azure_mcp_extension_cli_install` with `cli-type: azd` if needed -- `.azure/plan.md` exists with status `Validated` +- `.azure/deployment-plan.md` exists with status `Validated` - `azure.yaml` exists and validated - Infrastructure files exist (Bicep: `infra/main.bicep`, Terraform: `infra/*.tf`) - **AZD environment configured** → Done in azure-validate diff --git a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/functions-deploy.md b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/functions-deploy.md index 59af8e30..8e3e41b7 100644 --- a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/functions-deploy.md +++ b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/azd/functions-deploy.md @@ -6,7 +6,7 @@ Deployment workflows for Azure Functions using AZD. - Azure Functions project prepared with azd template - `azure.yaml` exists and validated -- `.azure/plan.md` status = `Validated` +- `.azure/deployment-plan.md` status = `Validated` - Azure Functions Core Tools (optional, for local debugging or when using `func` commands outside azd workflows) ## AZD Deployment diff --git a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/bicep/README.md b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/bicep/README.md index 65bba983..535581fd 100644 --- a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/bicep/README.md +++ b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/bicep/README.md @@ -5,7 +5,7 @@ Deploy to Azure using Bicep templates directly. ## Prerequisites - `az` CLI installed with Bicep extension -- `.azure/plan.md` exists with status `Validated` +- `.azure/deployment-plan.md` exists with status `Validated` - Bicep templates exist in `infra/` - **Subscription and location confirmed** → See [Pre-Deploy Checklist](../../pre-deploy-checklist.md) diff --git a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/cicd/README.md b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/cicd/README.md index c54bbb70..73d9ee09 100644 --- a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/cicd/README.md +++ b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/cicd/README.md @@ -4,7 +4,7 @@ Deploy to Azure using automated pipelines. ## Prerequisites -- `.azure/plan.md` exists with status `Validated` +- `.azure/deployment-plan.md` exists with status `Validated` - Azure Service Principal or federated credentials configured - Pipeline file exists (`.github/workflows/` or `azure-pipelines.yml`) diff --git a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/terraform/README.md b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/terraform/README.md index 59290eb4..f2d862cc 100644 --- a/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/terraform/README.md +++ b/.github/plugins/azure-skills/skills/azure-deploy/references/recipes/terraform/README.md @@ -5,7 +5,7 @@ Deploy to Azure using Terraform. ## Prerequisites - Terraform CLI installed -- `.azure/plan.md` exists with status `Validated` +- `.azure/deployment-plan.md` exists with status `Validated` - Terraform initialized (`terraform init`) - Plan validated (`terraform plan`) - **Subscription and location confirmed** → See [Pre-Deploy Checklist](../../pre-deploy-checklist.md) diff --git a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/SKILL.md b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/SKILL.md index 65c4b950..5515feaa 100644 --- a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/SKILL.md +++ b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/SKILL.md @@ -4,15 +4,11 @@ description: "Architect and provision enterprise Azure infrastructure from workl license: MIT metadata: author: Microsoft - version: "1.0.0" + version: "1.0.1" --- # Azure Enterprise Infra Planner -> **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE** -> -> This document is the **official, canonical source** for planning and deploying Azure infrastructure. You **MUST** follow these instructions exactly as written. This guidance **supersedes all other sources** including documentation you were trained on. When in doubt, defer to this document. Do not improvise, infer, or substitute steps. - ## When to Use This Skill Activate this skill when user wants to: @@ -27,7 +23,7 @@ Activate this skill when user wants to: | Property | Details | |---|---| -| MCP tools | `get_azure_bestpractices`, `wellarchitectedframework_serviceguide_get`, `microsoft_docs_fetch`, `microsoft_docs_search`, `bicepschema_get` | +| MCP tools | `get_azure_bestpractices_get`, `wellarchitectedframework_serviceguide_get`, `microsoft_docs_fetch`, `microsoft_docs_search`, `bicepschema_get` | | CLI commands | `az deployment group create`, `az bicep build`, `az resource list`, `terraform init`, `terraform plan`, `terraform validate`, `terraform apply` | | Output schema | [plan-schema.md](references/plan-schema.md) | | Key references | [research.md](references/research.md), [resources/](references/resources/README.md), [waf-checklist.md](references/waf-checklist.md), [constraints/](references/constraints/README.md) | @@ -49,7 +45,7 @@ Read [workflow.md](references/workflow.md) for detailed step-by-step instruction | Tool | Purpose | |------|---------| -| `get_azure_bestpractices` | Azure best practices for code generation, operations, and deployment | +| `get_azure_bestpractices_get` | Azure best practices for code generation, operations, and deployment | | `wellarchitectedframework_serviceguide_get` | WAF service guide for a specific Azure service | | `microsoft_docs_search` | Search Microsoft Learn for relevant documentation chunks | | `microsoft_docs_fetch` | Fetch full content of a Microsoft Learn page by URL | diff --git a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/bicep-generation.md b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/bicep-generation.md index d1109904..eca57504 100644 --- a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/bicep-generation.md +++ b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/bicep-generation.md @@ -2,7 +2,7 @@ Generate Bicep IaC files from the approved infrastructure plan. -> ⚠️ **CRITICAL**: All Bicep files MUST be created under `/infra/`. Never place `.bicep` files in the project root or in `.azure/`. +> Important: All Bicep files must be created under `/infra/`. Never place `.bicep` files in the project root or in `.azure/`. ## File Structure @@ -21,25 +21,25 @@ infra/ ## Generation Steps -1. **Create `infra/` directory** — Create `/infra/` and `/infra/modules/` directories. All files in subsequent steps go here. -2. **Read plan** — Load `/.azure/infrastructure-plan.json`, verify `meta.status === "approved"` -3. **Fetch Bicep schemas** — For each resource in the plan, use a sub-agent to call `bicepschema_get` with `resource-type` set to the ARM type from the relevant [resources/](resources/README.md) category file (e.g., `Microsoft.ContainerService/managedClusters`). Instruct the sub-agent: "Return the full property structure for {ARM type}: required properties, allowed values, child resources. ≤500 tokens." Use this output — not training data — to generate correct resource definitions. +1. Create `infra/` directory — create `/infra/` and `/infra/modules/` directories. All files in subsequent steps go here. +2. Read plan — load `/.azure/infrastructure-plan.json`, verify `meta.status === "approved"` +3. Fetch Bicep schemas — for each resource in the plan, use a sub-agent to call `bicepschema_get` with `resource-type` set to the ARM type from the relevant [resources/](resources/README.md) category file (e.g., `Microsoft.ContainerService/managedClusters`). Instruct the sub-agent: "Return the full property structure for {ARM type}: required properties, allowed values, child resources. ≤500 tokens." Use this output — not training data — to generate correct resource definitions. - > ⚠️ **Sub-resource vs parent schemas**: The schema tool returns only the schema for the exact type requested. Sub-resource types (e.g., `Microsoft.Network/virtualNetworks/subnets`) return a smaller, focused schema but **miss parent-level properties** (e.g., VNet `encryption` lives on the parent, not the subnet sub-resource). Strategy: - > - **Start with sub-resource types** when validating child resources — smaller responses (~25KB vs ~95KB), easier to summarize - > - **Fetch the parent type separately** when you need parent-level properties (encryption, tags, SKU) — delegate to a sub-agent with specific property extraction instructions to manage the large response +> The schema tool returns only the schema for the exact type requested. Sub-resource types (e.g., `Microsoft.Network/virtualNetworks/subnets`) return a smaller, focused schema but miss parent-level properties (e.g., VNet `encryption` lives on the parent, not the subnet sub-resource). Strategy: +> - Start with sub-resource types when validating child resources — smaller responses (~25KB vs ~95KB), easier to summarize +> - Fetch the parent type separately when you need parent-level properties (encryption, tags, SKU) — delegate to a sub-agent with specific property extraction instructions to manage the large response -4. **Generate modules** — Group resources by category; one `.bicep` file per group under `infra/modules/`. Use the schema from step 3 for property names, allowed values, and required fields. -5. **Generate main.bicep** — Write `infra/main.bicep` that imports all modules and passes parameters -6. **Generate parameters** — Create `infra/main.bicepparam` with environment-specific values +4. Generate modules — group resources by category; one `.bicep` file per group under `infra/modules/`. Use the schema from step 3 for property names, allowed values, and required fields. +5. Generate main.bicep — write `infra/main.bicep` that imports all modules and passes parameters +6. Generate parameters — create `infra/main.bicepparam` with environment-specific values ## Bicep Conventions - Use `@description()` decorators on all parameters - Use `@secure()` for secrets and connection strings - Choose `targetScope` in `main.bicep` based on the deployment plan: - - For **single resource group** deployments, set `targetScope = 'resourceGroup'` and deploy with `az deployment group create`. - - For **subscription-scope** deployments (for example, resources across multiple resource groups or subscription-level resources), set `targetScope = 'subscription'` and deploy with `az deployment sub create`. + - For single resource group deployments, set `targetScope = 'resourceGroup'` and deploy with `az deployment group create`. + - For subscription-scope deployments (for example, resources across multiple resource groups or subscription-level resources), set `targetScope = 'subscription'` and deploy with `az deployment sub create`. - Use `existing` keyword for referencing pre-existing resources - Output resource IDs and endpoints needed by other resources - Use `dependsOn` only when implicit dependencies are insufficient diff --git a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/deployment.md b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/deployment.md index 911ef014..49c70054 100644 --- a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/deployment.md +++ b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/deployment.md @@ -4,25 +4,25 @@ Execute infrastructure deployment after plan approval and IaC generation. ## Status Gate -**Before executing any deployment command, verify:** +Before executing any deployment command, verify: ```txt meta.status === "approved" ``` -If status is not `approved`, **STOP** and inform the user. Do NOT manually change the status. +If status is not `approved`, stop and inform the user. Do not manually change the status. ## Pre-Deployment Checklist -1. **Plan approved** — `meta.status` is `approved` -2. **IaC generated** — Bicep or Terraform files exist in `/infra/` -3. **Azure context confirmed** — Subscription and resource group selected -4. **User confirmation** — Explicit "yes, deploy" from the user -5. **Syntax validated** — `az bicep build` or `terraform validate` passed +1. Plan approved — `meta.status` is `approved` +2. IaC generated — Bicep or Terraform files exist in `/infra/` +3. Azure context confirmed — subscription and resource group selected +4. User confirmation — explicit "yes, deploy" from the user +5. Syntax validated — `az bicep build` or `terraform validate` passed ## Bicep Deployment -**Scope selection:** Use **resource-group scope** when your template deploys into an existing resource group. Use **subscription scope** when your template creates resource groups or other subscription-level resources (policies, role assignments, etc.). +Scope selection: use resource-group scope when your template deploys into an existing resource group. Use subscription scope when your template creates resource groups or other subscription-level resources (policies, role assignments, etc.). ```bash # Validate first (applies to both scopes) @@ -117,9 +117,9 @@ terraform apply tfplan After successful deployment: -1. **Update status** — Set `meta.status` to `deployed` in `/.azure/infrastructure-plan.json` -2. **Verify resources** — List resources in the target resource group using Azure CLI: `az resource list -g -o table` -3. **Report to user** — List deployed resources, endpoints, and any follow-up actions +1. Update status — set `meta.status` to `deployed` in `/.azure/infrastructure-plan.json` +2. Verify resources — list resources in the target resource group using Azure CLI: `az resource list -g -o table` +3. Report to user — list deployed resources, endpoints, and any follow-up actions ## Error Handling diff --git a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/pairing-checks.md b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/pairing-checks.md index 06373bb7..d47c5ae6 100644 --- a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/pairing-checks.md +++ b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/pairing-checks.md @@ -1,6 +1,6 @@ # Property & Pairing Checks -Cross-check each new resource's properties against **every already-written resource** it connects to. Only run the checks relevant to this resource's type. Consult the resource file's **Pairing Constraints** section for type-specific rules. +Cross-check each new resource's properties against every already-written resource it connects to. Only run the checks relevant to this resource's type. Consult the resource file's Pairing Constraints section for type-specific rules. ## SKU Compatibility diff --git a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/research.md b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/research.md index 73daeea9..4a6bd4fe 100644 --- a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/research.md +++ b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/research.md @@ -6,51 +6,51 @@ Research is sequential: identify resources → call WAF tools → refine → loa | Scenario | Action | |----------|--------| -| **Repository** | Scan `package.json`, `requirements.txt`, `Dockerfile`, `*.csproj` for runtime/dependencies. | -| **User requirements** | Clarify workload purpose, traffic, data storage, security, budget. | -| **Multi-environment** | Ask about dev/staging/prod sizing differences. | +| Repository | Scan `package.json`, `requirements.txt`, `Dockerfile`, `*.csproj` for runtime/dependencies. | +| User requirements | Clarify workload purpose, traffic, data storage, security, budget. | +| Multi-environment | Ask about dev/staging/prod sizing differences. | ## Step 1 — Identify Core Resources and Sub-Goals -From the user's description, list the **core Azure services** (compute, data, networking, messaging). Also derive **sub-goals** — implicit constraints to include in `inputs.subGoals`: +From the user's description, list the core Azure services (compute, data, networking, messaging). Also derive sub-goals — implicit constraints to include in `inputs.subGoals`: - "assume all defaults" → `"Cost-optimized: consumption/serverless tiers, minimal complexity"` - production system → `"Production-grade: zone redundancy, private networking, managed identity"` -## Step 2 — WAF Tool Calls (MANDATORY FIRST) +## Step 2 — WAF Tool Calls -> ⚠️**HARD GATE**: Call WAF MCP tools BEFORE reading local resource files. Do NOT skip this. +> Mandatory: Call WAF MCP tools before reading local resource files. Complete this step before proceeding. 1. Call `get_azure_bestpractices` with `resource: "general"`, `action: "all"` for baseline guidance. -2. Call `wellarchitectedframework_serviceguide_get` with `service: ""` for **each** core service (in parallel). Examples: `"Container Apps"`, `"Cosmos DB"`, `"App Service"`, `"Event Grid"`, `"Key Vault"`. +2. Call `wellarchitectedframework_serviceguide_get` with `service: ""` for each core service (in parallel). Examples: `"Container Apps"`, `"Cosmos DB"`, `"App Service"`, `"Event Grid"`, `"Key Vault"`. 3. The tool returns a markdown URL. Use a sub-agent to fetch and summarize in ≤500 tokens, focusing on: additional resources needed, required properties for security/reliability, key design decisions. 4. Collect all WAF findings: missing resources, property hardening, architecture patterns. -## Step 3 — Resource Refinement (MANDATORY) +## Step 3 — Resource Refinement -> ⚠️ **HARD GATE**: Do NOT skip. You MUST walk through the WAF checklist and document what was added or intentionally omitted. +> Mandatory: Walk through the WAF checklist and document what was added or intentionally omitted. Walk through every concern in the [WAF cross-cutting checklist](waf-checklist.md) and add missing resources or harden properties. For each checklist item, either add the resource/property or document the intentional omission in `overallReasoning.tradeoffs` and `inputs.subGoals`. Present the refinement summary to the user before proceeding to Step 4. -## Step 4 — Resource Lookup via Tools (MANDATORY) +## Step 4 — Resource Lookup via Tools -> ⚠️ **HARD GATE**: You MUST complete this step for every resource before generating the plan. WAF tools (Step 2) provide architecture guidance but do NOT provide ARM types, naming rules, or pairing constraints. This step fills those gaps. Read [resources/README.md](resources/README.md) to identify which category files contain the resources you need, then load only those category files. +> Mandatory: Complete this step for every resource before generating the plan. WAF tools (Step 2) provide architecture guidance but do not provide ARM types, naming rules, or pairing constraints. This step fills those gaps. Read [resources/README.md](resources/README.md) to identify which category files contain the resources you need, then load only those category files. For each resource identified in Steps 1-3: -1. **Look up the resource** in the relevant [resources/](resources/README.md) category file (e.g., `resources/compute-infra.md` for AKS, `resources/data-analytics.md` for Cosmos DB) to get its ARM type, API version, and CAF prefix. Read the index in `resources/README.md` to find the right category file. -2. **Use a sub-agent** to call `microsoft_docs_fetch` with the naming rules URL from the resource category file. Instruct the sub-agent: "Extract naming rules for {service}: min/max length, allowed characters, uniqueness scope. ≤200 tokens." Fall back to `microsoft_docs_search` with `" naming rules"` only if the URL is missing or returns an error. -3. **Read pairing constraints** for the resource from the matching [constraints/](constraints/README.md) category file (e.g., `constraints/networking-core.md` for VNet, `constraints/security.md` for Key Vault). Each category file is <2K tokens — read the whole file for all resources in that category. +1. Look up the resource in the relevant [resources/](resources/README.md) category file (e.g., `resources/compute-infra.md` for AKS, `resources/data-analytics.md` for Cosmos DB) to get its ARM type, API version, and CAF prefix. Read the index in `resources/README.md` to find the right category file. +2. Use a sub-agent to call `microsoft_docs_fetch` with the naming rules URL from the resource category file. Instruct the sub-agent: "Extract naming rules for {service}: min/max length, allowed characters, uniqueness scope. ≤200 tokens." Fall back to `microsoft_docs_search` with `" naming rules"` only if the URL is missing or returns an error. +3. Read pairing constraints for the resource from the matching [constraints/](constraints/README.md) category file (e.g., `constraints/networking-core.md` for VNet, `constraints/security.md` for Key Vault). Each category file is <2K tokens — read the whole file for all resources in that category. Use the [constraints/README.md](constraints/README.md) index to find the right category file for each resource name. -> ⚠️ **Selective loading**: Only load the category files you need. For a plan with AKS + Cosmos DB + VNet + Key Vault, you'd load 4 constraint files and 4 resource files (~5,500 tokens total) instead of the full catalog (~21,600 tokens). +> Important: Only load the category files you need. For a plan with AKS + Cosmos DB + VNet + Key Vault, you'd load 4 constraint files and 4 resource files (~5,500 tokens total) instead of the full catalog (~21,600 tokens). From the tool results, verify: -1. **Type** — Correct `Microsoft.*` resource type and API version -2. **SKU** — Available in target region, appropriate for workload -3. **Region** — Service available, data residency met -4. **Name** — CAF-compliant naming constraints -5. **Dependencies** — All prerequisites identified and ordered -6. **Properties** — Required properties per resource schema -7. **Alternatives** — At least one alternative with tradeoff documented +1. Type — Correct `Microsoft.*` resource type and API version +2. SKU — Available in target region, appropriate for workload +3. Region — Service available, data residency met +4. Name — CAF-compliant naming constraints +5. Dependencies — All prerequisites identified and ordered +6. Properties — Required properties per resource schema +7. Alternatives — At least one alternative with tradeoff documented diff --git a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/terraform-generation.md b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/terraform-generation.md index 28ab6494..7b880604 100644 --- a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/terraform-generation.md +++ b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/terraform-generation.md @@ -31,14 +31,14 @@ infra/ ## Generation Steps -1. **Create `infra/` directory** — Create `/infra/` and `/infra/modules/` directories. All files in subsequent steps go here. -2. **Read plan** — Load `/.azure/infrastructure-plan.json`, verify `meta.status === "approved"` -3. **Generate providers.tf** — Write `infra/providers.tf` to configure `azurerm` provider with required features -4. **Generate modules** — Group resources by category; one module per group under `infra/modules/` -5. **Generate root main.tf** — Write `infra/main.tf` that calls all modules, wire outputs to inputs -6. **Generate variables.tf** — Write `infra/variables.tf` with all configurable parameters -7. **Generate terraform.tfvars** — Write `infra/terraform.tfvars` with default values from the plan -8. **Generate backend.tf** — Write `infra/backend.tf` for Azure Storage backend remote state +1. Create `infra/` directory — create `/infra/` and `/infra/modules/` directories. All files in subsequent steps go here. +2. Read plan — load `/.azure/infrastructure-plan.json`, verify `meta.status === "approved"` +3. Generate providers.tf — write `infra/providers.tf` to configure `azurerm` provider with required features +4. Generate modules — group resources by category; one module per group under `infra/modules/` +5. Generate root main.tf — write `infra/main.tf` that calls all modules, wire outputs to inputs +6. Generate variables.tf — write `infra/variables.tf` with all configurable parameters +7. Generate terraform.tfvars — write `infra/terraform.tfvars` with default values from the plan +8. Generate backend.tf — write `infra/backend.tf` for Azure Storage backend remote state ## Terraform Conventions diff --git a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/verification.md b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/verification.md index 86bbe6c4..bc33ed96 100644 --- a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/verification.md +++ b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/verification.md @@ -1,6 +1,6 @@ # Resource Verification -Run these checks **immediately after writing each resource** to `plan.resources[]`. Fix issues in-place before moving to the next resource. Load the relevant category file from [resources/](resources/README.md) for naming constraints, valid SKUs, and pairing rules. +Run these checks immediately after writing each resource to `plan.resources[]`. Fix issues in-place before moving to the next resource. Load the relevant category file from [resources/](resources/README.md) for naming constraints, valid SKUs, and pairing rules. ## 1. Name Checks @@ -24,4 +24,4 @@ Run these checks **immediately after writing each resource** to `plan.resources[ ## 3. Property & Pairing Checks -Cross-check against every already-written connected resource. Consult the resource file's **Pairing Constraints** section and [pairing-checks.md](pairing-checks.md) for full rules covering: SKU compatibility, subnet/network conflicts, storage pairing, Cosmos DB, Key Vault/CMK, SQL Database, and AKS networking. +Cross-check against every already-written connected resource. Consult the resource file's Pairing Constraints section and [pairing-checks.md](pairing-checks.md) for full rules covering: SKU compatibility, subnet/network conflicts, storage pairing, Cosmos DB, Key Vault/CMK, SQL Database, and AKS networking. diff --git a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/waf-checklist.md b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/waf-checklist.md index a805ba89..ce68102f 100644 --- a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/waf-checklist.md +++ b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/waf-checklist.md @@ -1,26 +1,26 @@ # WAF Cross-Cutting Checklist -Walk through **every row** and decide if resources or properties are needed. +Walk through every row and decide if resources or properties are needed. | Concern | Question | Resources / Properties to Add | |---------|----------|-------------------------------| -| **Identity** | How do services authenticate to each other? | Managed identity (`Microsoft.ManagedIdentity/userAssignedIdentities`), RBAC role assignments | -| **Secrets** | Are there connection strings, API keys, credentials? | Key Vault (`Microsoft.KeyVault/vaults`) with `enableRbacAuthorization: true`, `enableSoftDelete: true`, `enablePurgeProtection: true` | -| **Monitoring** | How will operators observe the system? | Application Insights for compute resources, Log Analytics workspace, diagnostic settings per data resource | -| **Network** | Should resources have public endpoints? | Production → VNet + private endpoints, `publicNetworkAccess: "Disabled"`. Cost-optimized → document omission as tradeoff. | -| **Encryption** | Is data encrypted at rest and in transit? | `httpsOnly: true`, `minTlsVersion: "1.2"`, Key Vault for CMK | -| **Resilience** | Single points of failure? | `zoneRedundant: true` on supported SKUs. Cost-optimized → document as tradeoff. | -| **Auth hardening** | Can local/key-based auth be disabled? | `disableLocalAuth: true` on Event Grid, Service Bus, Storage | -| **Tagging** | Resources tagged for cost tracking? | Tags on every resource | +| Identity | How do services authenticate to each other? | Managed identity (`Microsoft.ManagedIdentity/userAssignedIdentities`), RBAC role assignments | +| Secrets | Are there connection strings, API keys, credentials? | Key Vault (`Microsoft.KeyVault/vaults`) with `enableRbacAuthorization: true`, `enableSoftDelete: true`, `enablePurgeProtection: true` | +| Monitoring | How will operators observe the system? | Application Insights for compute resources, Log Analytics workspace, diagnostic settings per data resource | +| Network | Should resources have public endpoints? | Production → VNet + private endpoints, `publicNetworkAccess: "Disabled"`. Cost-optimized → document omission as tradeoff. | +| Encryption | Is data encrypted at rest and in transit? | `httpsOnly: true`, `minTlsVersion: "1.2"`, Key Vault for CMK | +| Resilience | Single points of failure? | `zoneRedundant: true` on supported SKUs. Cost-optimized → document as tradeoff. | +| Auth hardening | Can local/key-based auth be disabled? | `disableLocalAuth: true` on Event Grid, Service Bus, Storage | +| Tagging | Resources tagged for cost tracking? | Tags on every resource | ## Common Additions Most workloads should include these unless sub-goals justify omission: -- **Key Vault** — secrets, certificates, CMK -- **Managed Identity** — prefer over keys for service-to-service auth -- **Application Insights** — for App Service, Functions, Container Apps, AKS -- **Log Analytics** — centralized log aggregation -- **Diagnostic Settings** — wire Cosmos DB, SQL, Storage to Log Analytics +- Key Vault — secrets, certificates, CMK +- Managed Identity — prefer over keys for service-to-service auth +- Application Insights — for App Service, Functions, Container Apps, AKS +- Log Analytics — centralized log aggregation +- Diagnostic Settings — wire Cosmos DB, SQL, Storage to Log Analytics If you intentionally skip a concern (e.g., no VNet for cost reasons), document it in `overallReasoning.tradeoffs` and `inputs.subGoals`. diff --git a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/workflow.md b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/workflow.md index d0db811d..65525d80 100644 --- a/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/workflow.md +++ b/.github/plugins/azure-skills/skills/azure-enterprise-infra-planner/references/workflow.md @@ -2,40 +2,38 @@ ## Rules -1. **Research before planning** — You **MUST** call `mcp_azure_mcp_get_azure_bestpractices` and `mcp_azure_mcp_wellarchitectedframework` MCP tools BEFORE reading local resource files or generating a plan. See [research.md](research.md) Step 2. -2. **Plan before IaC** — Generate `/.azure/infrastructure-plan.json` before any IaC so we can map the plan to generated code and ensure alignment. -3. **Get approval** — Plan status must be `approved` before deployment. -4. **User chooses IaC format** — Bicep or Terraform; ask if not specified. -5. ⚠️ **Destructive actions require explicit confirmation.** +1. Research before planning — call `mcp_azure_mcp_get_azure_bestpractices` and `mcp_azure_mcp_wellarchitectedframework` MCP tools before reading local resource files or generating a plan. See [research.md](research.md) Step 2. +2. Plan before IaC — generate `/.azure/infrastructure-plan.json` before any IaC so we can map the plan to generated code and ensure alignment. +3. Get approval — plan status must be `approved` before deployment. +4. User chooses IaC format — Bicep or Terraform; ask if not specified. +5. Destructive actions require explicit confirmation. ---- - -> **Complete each phase fully before starting the next. Phases are sequential, not parallel.** +> Complete each phase fully before starting the next. Phases are sequential, not parallel. ## Phase 1: Research — WAF Tools Call MCP tools to gather best practices and WAF guidance. See [research.md](research.md) Steps 1-2. - Call `get_azure_bestpractices` once (direct call — small response) - Call `wellarchitectedframework_serviceguide_get` for each core service (direct parallel calls — small responses, returns URLs only) -- Use **sub-agents** to fetch and summarize each WAF guide URL (large responses — 20-60KB each) +- Use sub-agents to fetch and summarize each WAF guide URL (large responses — 20-60KB each) -**Gate**: All WAF tool calls complete and summarized before proceeding. +Gate: All WAF tool calls complete and summarized before proceeding. ## Phase 2: Research — Refine & Lookup -> ⚠️ **You MUST look up resources before generating the plan.** The [resources/](resources/README.md) directory contains ARM types, API versions, CAF prefixes, naming rule URLs, and region categories that MCP tools do not provide. +Look up resources before generating the plan. The [resources/](resources/README.md) directory contains ARM types, API versions, CAF prefixes, naming rule URLs, and region categories that MCP tools do not provide. Apply WAF findings, then look up every resource in local reference files. See [research.md](research.md) Steps 3-4. - Walk through [waf-checklist.md](waf-checklist.md) — add missing resources, document omissions - Read [resources/README.md](resources/README.md) to identify which category files to load, then read only the relevant category files (e.g., `resources/compute-infra.md` for AKS, `resources/security.md` for Key Vault) -- For each resource: use **sub-agents** to fetch naming rules via `microsoft_docs_fetch` using URLs from the resource category files +- For each resource: use sub-agents to fetch naming rules via `microsoft_docs_fetch` using URLs from the resource category files - For each resource: read pairing constraints from the matching [constraints/](constraints/README.md) category file (e.g., `constraints/networking-core.md` for VNet) -**Gate**: Every resource has an ARM type, naming rules, and pairing constraints checked. Present the preliminary resource list to the user with brief justifications and **STOP — wait for approval**. +Gate: Every resource has an ARM type, naming rules, and pairing constraints checked. Present the preliminary resource list to the user with brief justifications and wait for approval before proceeding. ## Phase 3: Plan Generation Build `/.azure/infrastructure-plan.json` using the schema in [plan-schema.md](plan-schema.md). Set `meta.status` to `draft`. -**Gate**: Plan JSON written to disk before proceeding. +Gate: Plan JSON written to disk before proceeding. ## Phase 4: Verification Run a full verification pass on the generated plan. See [verification.md](verification.md) and [pairing-checks.md](pairing-checks.md). @@ -44,12 +42,12 @@ Run a full verification pass on the generated plan. See [verification.md](verifi - Check pairing constraints — SKU compatibility, subnet conflicts, storage pairing - Fix issues in-place in the plan JSON -**Gate**: All verification checks pass. Present plan to user and **STOP — wait for approval**. +Gate: All verification checks pass. Present plan to user and wait for approval before proceeding. ## Phase 5: IaC Generation -Generate Bicep or Terraform from the approved plan. You must refer to instructions in [bicep-generation.md](bicep-generation.md) for Bicep or [terraform-generation.md](terraform-generation.md) for Terraform. +Generate Bicep or Terraform from the approved plan. Refer to [bicep-generation.md](bicep-generation.md) for Bicep or [terraform-generation.md](terraform-generation.md) for Terraform. -**Gate**: `meta.status` must be `approved` before generating any IaC files. +Gate: `meta.status` must be `approved` before generating any IaC files. ## Phase 6: Deployment Execute deployment commands. See [deployment.md](deployment.md). @@ -57,24 +55,22 @@ Execute deployment commands. See [deployment.md](deployment.md). - Select the correct deployment scope based on `targetScope` in `main.bicep` (resource group, subscription, management group, or tenant) - Run `az bicep build` to validate, then execute the matching scope command (`az deployment group create`, `az deployment sub create`, etc.) or `terraform apply` -**Gate**: `meta.status` must be `approved`. Destructive actions require explicit user confirmation. +Gate: `meta.status` must be `approved`. Destructive actions require explicit user confirmation. ## Status Lifecycle `draft` → `approved` → `deployed` ---- - ## Outputs | Artifact | Location | |----------|----------| -| **Infrastructure Plan** | `/.azure/infrastructure-plan.json` | +| Infrastructure Plan | `/.azure/infrastructure-plan.json` | | Bicep files | `/infra/main.bicep`, `/infra/modules/*.bicep` | | Terraform files | `/infra/main.tf`, `/infra/modules/**/*.tf` | -> ⚠️ **IaC file placement is mandatory.** Before writing any `.bicep` or `.tf` files: -> 1. Create the `infra/` directory at `/infra/` -> 2. Create `infra/modules/` for child modules -> 3. Write `main.bicep` (or `main.tf`) inside `infra/`, NOT in the project root or `.azure/` +Before writing any `.bicep` or `.tf` files: +1. Create the `infra/` directory at `/infra/` +2. Create `infra/modules/` for child modules +3. Write `main.bicep` (or `main.tf`) inside `infra/`, not in the project root or `.azure/` diff --git a/.github/plugins/azure-skills/skills/azure-prepare/SKILL.md b/.github/plugins/azure-skills/skills/azure-prepare/SKILL.md index a485b8e3..d66a3a2c 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/SKILL.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/SKILL.md @@ -4,7 +4,7 @@ description: "Prepare Azure apps for deployment (infra Bicep/Terraform, azure.ya license: MIT metadata: author: Microsoft - version: "1.0.13" + version: "1.1.1" --- # Azure Prepare @@ -28,7 +28,7 @@ Activate this skill when user wants to: ## Rules -1. **Plan first** — Create `.azure/plan.md` **in the workspace root directory** (not the session-state folder) before any code generation +1. **Plan first** — Create `.azure/deployment-plan.md` **in the workspace root directory** (not the session-state folder) before any code generation 2. **Get approval** — Present plan to user before execution 3. **Research before generating** — Load references and invoke related skills 4. **Update plan progressively** — Mark steps complete as you go @@ -45,15 +45,13 @@ Activate this skill when user wants to: > **YOU MUST CREATE A PLAN BEFORE DOING ANY WORK** > > 1. **STOP** — Do not generate any code, infrastructure, or configuration yet -> 2. **PLAN** — Follow the Planning Phase below to create `.azure/plan.md` +> 2. **PLAN** — Follow the Planning Phase below to create `.azure/deployment-plan.md` > 3. **CONFIRM** — Present the plan to the user and get approval > 4. **EXECUTE** — Only after approval, execute the plan step by step > -> The `.azure/plan.md` file is the **source of truth** for this workflow and for azure-validate and azure-deploy skills. Without it, those skills will fail. +> The `.azure/deployment-plan.md` file is the **source of truth** for this workflow and for azure-validate and azure-deploy skills. Without it, those skills will fail. > -> ⚠️ **CRITICAL: `.azure/plan.md` must be created inside the workspace root** (e.g., `/tmp/my-project/.azure/plan.md`). This is **NOT** the session-state `plan.md` used for internal workflow tracking. These are two different files: -> - **`/.azure/plan.md`** — The deployment plan artifact read by azure-validate and azure-deploy. **You must create this.** -> - **`~/.copilot/session-state//plan.md`** — Internal session notes. This file is NOT visible to other skills. +> ⚠️ **CRITICAL: `.azure/deployment-plan.md` must be created inside the workspace root** (e.g., `/tmp/my-project/.azure/deployment-plan.md`), not in the session-state folder. This is the deployment plan artifact read by azure-validate and azure-deploy. **You must create this.** --- @@ -78,7 +76,7 @@ After the specialized skill completes, **resume azure-prepare** at Phase 1 Step ## Phase 1: Planning (BLOCKING — Complete Before Any Execution) -Create `.azure/plan.md` by completing these steps. Do NOT generate any artifacts until the plan is approved. +Create `.azure/deployment-plan.md` by completing these steps. Do NOT generate any artifacts until the plan is approved. | # | Action | Reference | |---|--------|-----------| @@ -88,8 +86,8 @@ Create `.azure/plan.md` by completing these steps. Do NOT generate any artifacts | 3 | **Scan Codebase** — Identify components, technologies, dependencies | [scan.md](references/scan.md) | | 4 | **Select Recipe** — Choose AZD (default), AZCLI, Bicep, or Terraform | [recipe-selection.md](references/recipe-selection.md) | | 5 | **Plan Architecture** — Select stack + map components to Azure services | [architecture.md](references/architecture.md) | -| 6 | **Write Plan** — Generate `.azure/plan.md` with all decisions | [plan-template.md](references/plan-template.md) | -| 7 | **Present Plan** — Show plan to user and ask for approval | `.azure/plan.md` | +| 6 | **Write Plan** — Generate `.azure/deployment-plan.md` with all decisions | [plan-template.md](references/plan-template.md) | +| 7 | **Present Plan** — Show plan to user and ask for approval | `.azure/deployment-plan.md` | | 8 | **Destructive actions require `ask_user`** | [Global Rules](references/global-rules.md) | --- @@ -100,7 +98,7 @@ Create `.azure/plan.md` by completing these steps. Do NOT generate any artifacts ## Phase 2: Execution (Only After Plan Approval) -Execute the approved plan. Update `.azure/plan.md` status after each step. +Execute the approved plan. Update `.azure/deployment-plan.md` status after each step. | # | Action | Reference | |---|--------|-----------| @@ -108,8 +106,9 @@ Execute the approved plan. Update `.azure/plan.md` status after each step. | 2 | **Confirm Azure Context** — Detect and confirm subscription + location and check the resource provisioning limit | [Azure Context](references/azure-context.md) | | 3 | **Generate Artifacts** — Create infrastructure and configuration files | [generate.md](references/generate.md) | | 4 | **Harden Security** — Apply security best practices | [security.md](references/security.md) | -| 5 | **⛔ Update Plan (MANDATORY before hand-off)** — Use the `edit` tool to change the Status in `.azure/plan.md` to `Ready for Validation`. You **MUST** complete this edit **BEFORE** invoking azure-validate. Do NOT skip this step. | `.azure/plan.md` | -| 6 | **⚠️ Hand Off** — Invoke **azure-validate** skill. Your preparation work is done. Deployment execution is handled by azure-deploy. **PREREQUISITE:** Step 5 must be completed first — `.azure/plan.md` status must say `Ready for Validation`. | — | +| 5 | **Functional Verification** — Verify the app works (UI + backend), locally if possible | [functional-verification.md](references/functional-verification.md) | +| 6 | **⛔ Update Plan (MANDATORY before hand-off)** — Use the `edit` tool to change the Status in `.azure/deployment-plan.md` to `Ready for Validation`. You **MUST** complete this edit **BEFORE** invoking azure-validate. Do NOT skip this step. | `.azure/deployment-plan.md` | +| 7 | **⚠️ Hand Off** — Invoke **azure-validate** skill. Your preparation work is done. Deployment execution is handled by azure-deploy. **PREREQUISITE:** Step 6 must be completed first — `.azure/deployment-plan.md` status must say `Ready for Validation`. | — | --- @@ -117,7 +116,7 @@ Execute the approved plan. Update `.azure/plan.md` status after each step. | Artifact | Location | |----------|----------| -| **Plan** | `.azure/plan.md` | +| **Plan** | `.azure/deployment-plan.md` | | Infrastructure | `./infra/` | | AZD Config | `azure.yaml` (AZD only) | | Dockerfiles | `src//Dockerfile` | @@ -140,7 +139,7 @@ Execute the approved plan. Update `.azure/plan.md` status after each step. > > `azure-prepare` → `azure-validate` → `azure-deploy` > -> **⛔ BEFORE invoking azure-validate**, you MUST use the `edit` tool to update `.azure/plan.md` status to `Ready for Validation`. If the plan status has not been updated, the validation will fail. +> **⛔ BEFORE invoking azure-validate**, you MUST use the `edit` tool to update `.azure/deployment-plan.md` status to `Ready for Validation`. If the plan status has not been updated, the validation will fail. > > Skipping validation leads to deployment failures. Be patient and follow the complete workflow for the highest success outcome. diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/architecture.md b/.github/plugins/azure-skills/skills/azure-prepare/references/architecture.md index 831cd8c8..859e70c3 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/architecture.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/architecture.md @@ -104,4 +104,4 @@ Select hosting stack and map components to Azure services. ## Document Architecture -Record selections in `.azure/plan.md` with rationale for each choice. +Record selections in `.azure/deployment-plan.md` with rationale for each choice. diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/azure-context.md b/.github/plugins/azure-skills/skills/azure-prepare/references/azure-context.md index e9a2e347..57292841 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/azure-context.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/azure-context.md @@ -130,7 +130,7 @@ Choices: [ ## Record in Plan -After confirmation, record in `.azure/plan.md`: +After confirmation, record in `.azure/deployment-plan.md`: ```markdown ## Azure Context diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/functional-verification.md b/.github/plugins/azure-skills/skills/azure-prepare/references/functional-verification.md new file mode 100644 index 00000000..28f348d2 --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/functional-verification.md @@ -0,0 +1,76 @@ +# Functional Verification + +Verify that the application works correctly — both UI and backend — before proceeding to validation and deployment. This step prevents deploying broken or incomplete functionality to Azure. + +## When to Verify + +After generating all artifacts (code, infrastructure, configuration) and applying security hardening — but **before** marking the plan as `Ready for Validation`. + +## Verification Checklist + +Use `ask_user` to confirm functional testing with the user: + +``` +"Before we proceed to deploy, would you like to verify the app works as expected? +We can test both the UI and backend to catch issues before they reach Azure." +``` + +### Backend Verification + +| Check | How | +|-------|-----| +| **App starts without errors** | Run the app and confirm no startup crashes or missing dependencies | +| **API endpoints respond** | Test core routes (e.g., `curl` health, list, create endpoints) | +| **Data operations work** | Verify CRUD operations against storage, database, or other services | +| **Authentication flows** | Confirm auth works (tokens, managed identity fallback, login/logout) | +| **Error handling** | Verify error responses are meaningful (not unhandled exceptions) | + +### UI Verification + +| Check | How | +|-------|-----| +| **Page loads** | Open the app in a browser and confirm the UI renders | +| **Interactive elements work** | Test buttons, forms, file inputs, navigation links | +| **Data displays correctly** | Verify lists, images, and dynamic content render from the backend | +| **User workflows complete** | Walk through the core user journey end-to-end (e.g., upload → view → delete) | + +## Decision Tree + +``` +App artifacts generated? +├── Yes → Ask user: "Would you like to verify functionality?" +│ ├── User says yes +│ │ ├── App can run locally? → Run locally, verify backend + UI +│ │ ├── API-only / no UI? → Test endpoints with curl or similar +│ │ └── Static site? → Open in browser, verify rendering +│ │ Then: +│ │ ├── Works → Proceed to Update Plan (step 6) +│ │ └── Issues found → Fix issues, re-test +│ └── User says no / skip → Proceed to Update Plan (step 6) +└── No → Go back to Generate Artifacts (step 3) +``` + +## Running Locally + +For apps that can run locally, help the user start the app based on the detected runtime: + +| Runtime | Command | Notes | +|---------|---------|-------| +| Node.js | `npm install && npm start` | Set `PORT=3000` if not configured | +| Python | `pip install -r requirements.txt && python app.py` | Use virtual environment | +| .NET | `dotnet run` | Check `launchSettings.json` for port | +| Java | `mvn spring-boot:run` or `gradle bootRun` | Check `application.properties` | + +> ⚠️ **Warning:** For apps using Azure services (e.g., Blob Storage, Cosmos DB), local testing requires the user to be authenticated via `az login` with sufficient RBAC roles, or to have local emulators configured (e.g., Azurite for Storage). + +## Record in Plan + +After functional verification, add a note to `.azure/plan.md`: + +```markdown +## Functional Verification +- Status: Verified / Skipped +- Backend: Tested / Not applicable +- UI: Tested / Not applicable +- Notes: +``` diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/generate.md b/.github/plugins/azure-skills/skills/azure-prepare/references/generate.md index 4b895764..d68b0005 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/generate.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/generate.md @@ -49,7 +49,7 @@ The research step loads service-specific references and invokes related skills t 1. ✅ Completed [Research Components](research.md) step 2. ✅ Loaded all relevant `services/*.md` references 3. ✅ Invoked related skills for specialized guidance -4. ✅ Documented findings in `.azure/plan.md` +4. ✅ Documented findings in `.azure/deployment-plan.md` ## Generation Order @@ -79,7 +79,7 @@ Load the appropriate recipe for detailed generation steps: ``` project-root/ ├── .azure/ -│ └── plan.md +│ └── deployment-plan.md ├── infra/ │ ├── main.bicep (or main.tf) │ └── modules/ @@ -106,6 +106,6 @@ Apply language-specific production settings for containerized apps: ## After Generation -1. Update `.azure/plan.md` with generated file list +1. Update `.azure/deployment-plan.md` with generated file list 2. Run validation checks 3. Proceed to **azure-validate** skill diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/plan-template.md b/.github/plugins/azure-skills/skills/azure-prepare/references/plan-template.md index a04eb174..99a7f568 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/plan-template.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/plan-template.md @@ -1,6 +1,6 @@ # Plan Template -Create `.azure/plan.md` using this template. This file is **mandatory** and serves as the source of truth for the entire workflow. +Create `.azure/deployment-plan.md` using this template. This file is **mandatory** and serves as the source of truth for the entire workflow. ## ⛔ BLOCKING REQUIREMENTS @@ -165,7 +165,7 @@ For each resource type: - [ ] Apply recipes for integrations (if needed) - [ ] Generate application configuration - [ ] Generate Dockerfiles (if containerized) -- [ ] **⛔ Update plan status to "Ready for Validation"** — Use the `edit` tool to change the Status line in `.azure/plan.md`. This step is MANDATORY before invoking azure-validate. +- [ ] **⛔ Update plan status to "Ready for Validation"** — Use the `edit` tool to change the Status line in `.azure/deployment-plan.md`. This step is MANDATORY before invoking azure-validate. ### Phase 3: Validation - [ ] **PREREQUISITE:** Plan status MUST be "Ready for Validation" (Phase 2 last step) @@ -200,7 +200,7 @@ For each resource type: | File | Purpose | Status | |------|---------|--------| -| `.azure/plan.md` | This plan | ✅ | +| `.azure/deployment-plan.md` | This plan | ✅ | | `azure.yaml` | AZD configuration | ⏳ | | `infra/main.bicep` | Infrastructure | ⏳ | | `src/{component}/Dockerfile` | Container build | ⏳ | diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/recipe-selection.md b/.github/plugins/azure-skills/skills/azure-prepare/references/recipe-selection.md index 3e74c4b0..2168591a 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/recipe-selection.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/recipe-selection.md @@ -54,7 +54,7 @@ Choose the deployment recipe based on project needs and existing tooling. ## Record Selection -Document in `.azure/plan.md`: +Document in `.azure/deployment-plan.md`: ```markdown ## Recipe: AZD (Terraform) diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/azcli/README.md b/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/azcli/README.md index 2e57c32d..9ef3345a 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/azcli/README.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/azcli/README.md @@ -75,4 +75,4 @@ Resources: `{prefix}{token}{instance}` ## Next -→ Update `.azure/plan.md` → **azure-validate** +→ Update `.azure/deployment-plan.md` → **azure-validate** diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/azd/README.md b/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/azd/README.md index d5b9b536..98a7a5ad 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/azd/README.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/azd/README.md @@ -101,4 +101,4 @@ Azure Developer CLI workflow for preparing Azure deployments. ## Next -→ Update `.azure/plan.md` → **azure-validate** +→ Update `.azure/deployment-plan.md` → **azure-validate** diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/bicep/README.md b/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/bicep/README.md index b06d6bc8..4ce274b3 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/bicep/README.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/bicep/README.md @@ -58,4 +58,4 @@ Manual Dockerfile creation required. ## Next -→ Update `.azure/plan.md` → **azure-validate** +→ Update `.azure/deployment-plan.md` → **azure-validate** diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/terraform/README.md b/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/terraform/README.md index d7b0100e..7f33d6c6 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/terraform/README.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/recipes/terraform/README.md @@ -89,4 +89,4 @@ Manual Dockerfile creation required. ## Next -→ Update `.azure/plan.md` → **azure-validate** +→ Update `.azure/deployment-plan.md` → **azure-validate** diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/requirements.md b/.github/plugins/azure-skills/skills/azure-prepare/references/requirements.md index 1d280b14..2ed4e60e 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/requirements.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/requirements.md @@ -36,6 +36,27 @@ Collect project requirements through conversation before making architecture dec | Industry regulations | Security controls | | Internal policies | Approval workflows | +### 5. Subscription Policies + +After the user confirms a subscription, query Azure Policy assignments to discover enforcement constraints before making architecture decisions. + +``` +mcp_azure_mcp_policy(command: "policy_assignment_list", subscription: "") +``` + +| Policy Constraint | Impact | +|-------------------|--------| +| Blocked resource types or SKUs | Exclude from architecture | +| Required tags | Add to all Bicep/Terraform resources | +| Allowed regions | Restrict location choices | +| Network restrictions (e.g., no public endpoints) | Adjust networking and access patterns | +| Storage policies (e.g., deny shared key access) | Use policy-compliant auth | +| Naming conventions | Apply to resource naming | + +> ⚠️ **Warning:** Skipping this step can cause deployment failures when Azure Policy denies resource creation. Checking policies here prevents wasted work in architecture and generation phases. + +Record discovered policy constraints in `.azure/plan.md` under a **Policy Constraints** section so they feed into architecture decisions. + ## Gather via Conversation Use `ask_user` tool to confirm each of these with the user: @@ -44,8 +65,9 @@ Use `ask_user` tool to confirm each of these with the user: 2. Expected scale 3. Budget constraints 4. Compliance requirements (including data residency preferences) -5. Architecture preferences (if any) +5. Subscription and policy constraints (confirm subscription, then check policies automatically) +6. Architecture preferences (if any) ## Document in Plan -Record all requirements in `.azure/plan.md` immediately after gathering. +Record all requirements in `.azure/deployment-plan.md` immediately after gathering. diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/research.md b/.github/plugins/azure-skills/skills/azure-prepare/references/research.md index 471bc7cc..24a2284f 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/research.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/research.md @@ -12,7 +12,7 @@ After architecture planning, research each selected component to gather best pra 6. **Check Provisioning Limits** — Invoke **azure-quotas** skill to validate that the selected subscription and region have sufficient quota/capacity for all planned resources. Complete [Step 6 of the plan template](plan-template.md#6-provisioning-limit-checklist) in two phases: (1) prepare resource inventory with deployment quantities, (2) fetch quotas and validate capacity using azure-quotas skill 7. **Load Runtime References** — For containerized apps, load language-specific production settings (e.g., [Node.js](runtimes/nodejs.md)) 8. **Invoke Related Skills** — For deeper guidance, invoke mapped skills from the table below -9. **Document Findings** — Record key insights in `.azure/plan.md` +9. **Document Findings** — Record key insights in `.azure/deployment-plan.md` ## Service-to-Reference Mapping @@ -97,7 +97,7 @@ For **PostgreSQL**: ### Step 3: Document in Plan -Add research findings to `.azure/plan.md` under a `## Research Summary` section with source references and key insights per component. +Add research findings to `.azure/deployment-plan.md` under a `## Research Summary` section with source references and key insights per component. ## Common Research Patterns diff --git a/.github/plugins/azure-skills/skills/azure-prepare/references/resources-limits-quotas.md b/.github/plugins/azure-skills/skills/azure-prepare/references/resources-limits-quotas.md index e3f7504d..ac54f954 100644 --- a/.github/plugins/azure-skills/skills/azure-prepare/references/resources-limits-quotas.md +++ b/.github/plugins/azure-skills/skills/azure-prepare/references/resources-limits-quotas.md @@ -175,7 +175,7 @@ az quota update --resource-name {quota-name} --scope /subscriptions/{id}/provide 6. **Handle unsupported providers gracefully**: If you get `BadRequest` error, fall back to official documentation (Azure Resource Graph + docs) 7. **Request quota increases proactively**: If selected region lacks capacity, submit request before deployment 8. **Have alternative regions ready**: If quota increase denied, suggest backup regions -9. **Document capacity assumptions**: Note quota availability and source in `.azure/plan.md` +9. **Document capacity assumptions**: Note quota availability and source in `.azure/deployment-plan.md` 10. **Design for limits**: Architecture should account for both hard limits and quotas 11. **Monitor usage trends**: Regular quota checks help predict future needs 12. **Use lower environments wisely**: Dev/test environments count against quotas diff --git a/.github/plugins/azure-skills/skills/azure-validate/SKILL.md b/.github/plugins/azure-skills/skills/azure-validate/SKILL.md index 98a4f6f1..d075e686 100644 --- a/.github/plugins/azure-skills/skills/azure-validate/SKILL.md +++ b/.github/plugins/azure-skills/skills/azure-validate/SKILL.md @@ -1,10 +1,10 @@ --- name: azure-validate -description: "Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment." +description: "Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis." license: MIT metadata: author: Microsoft - version: "1.0.2" + version: "1.0.3" --- # Azure Validate @@ -15,7 +15,7 @@ metadata: > > Before proceeding, verify this prerequisite is met: > -> **azure-prepare** was invoked and completed → `.azure/plan.md` exists with status `Approved` or later +> **azure-prepare** was invoked and completed → `.azure/deployment-plan.md` exists with status `Approved` or later > > If the plan is missing, **STOP IMMEDIATELY** and invoke **azure-prepare** first. > @@ -40,15 +40,15 @@ metadata: | # | Action | Reference | |---|--------|-----------| -| 1 | **Load Plan** — Read `.azure/plan.md` for recipe and configuration. If missing → run azure-prepare first | `.azure/plan.md` | -| 2 | **Add Validation Steps** — Copy recipe "Validation Steps" to `.azure/plan.md` as children of "All validation checks pass" | [recipes/README.md](references/recipes/README.md), `.azure/plan.md` | +| 1 | **Load Plan** — Read `.azure/deployment-plan.md` for recipe and configuration. If missing → run azure-prepare first | `.azure/deployment-plan.md` | +| 2 | **Add Validation Steps** — Copy recipe "Validation Steps" to `.azure/deployment-plan.md` as children of "All validation checks pass" | [recipes/README.md](references/recipes/README.md), `.azure/deployment-plan.md` | | 3 | **Run Validation** — Execute recipe-specific validation commands | [recipes/README.md](references/recipes/README.md) | | 4 | **Build Verification** — Build the project and fix any errors before proceeding | See recipe | -| 5 | **Record Proof** — Populate **Section 7: Validation Proof** with commands run and results | `.azure/plan.md` | -| 6 | **Resolve Errors** — Fix failures before proceeding | See recipe's `errors.md` | -| 7 | **Update Status** — Only after ALL checks pass, set status to `Validated` | `.azure/plan.md` | -| 8 | **Deploy** — Invoke **azure-deploy** skill | — | - +| 5 | **Static Role Verification** — Review Bicep/Terraform for correct RBAC role assignments in code | [role-verification.md](references/role-verification.md) | +| 6 | **Record Proof** — Populate **Section 7: Validation Proof** with commands run and results | `.azure/deployment-plan.md` | +| 7 | **Resolve Errors** — Fix failures before proceeding | See recipe's `errors.md` | +| 8 | **Update Status** — Only after ALL checks pass, set status to `Validated` | `.azure/deployment-plan.md` | +| 9 | **Deploy** — Invoke **azure-deploy** skill | — | > **⛔ VALIDATION AUTHORITY** > > This skill is the **ONLY** authorized way to set plan status to `Validated`. You MUST: diff --git a/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azcli/README.md b/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azcli/README.md index 5fc45c39..b2553f38 100644 --- a/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azcli/README.md +++ b/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azcli/README.md @@ -88,6 +88,19 @@ az deployment group what-if \ ### 6. Docker Build (if containerized) +**Before building**, validate the Docker build context: + +1. Read the `Dockerfile` in `./src/` +2. If the Dockerfile contains `npm ci`, verify `package-lock.json` exists in the same directory +3. If `package-lock.json` is missing, generate it: + +```bash +cd ./src/ +npm install --package-lock-only +``` + +**Then build:** + ```bash docker build -t :test ./src/ ``` diff --git a/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azcli/errors.md b/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azcli/errors.md index edce66ac..bd85db7c 100644 --- a/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azcli/errors.md +++ b/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azcli/errors.md @@ -6,6 +6,7 @@ | `Please run 'az login'` | `az login` | | `AADSTS50076: MFA required` | `az login --use-device-code` | | `AuthorizationFailed` | Request Contributor role | +| `npm ci` fails with `missing: package-lock.json` | Run `npm install --package-lock-only` in the service directory before building | | `Template validation failed` | Check Bicep syntax | ## Debug diff --git a/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azd/README.md b/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azd/README.md index 7b8aa984..c40fbeaf 100644 --- a/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azd/README.md +++ b/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azd/README.md @@ -19,9 +19,10 @@ Validation steps for Azure Developer CLI projects. - [ ] 6. Aspire Pre-Provisioning Checks - [ ] 7. Provision Preview - [ ] 8. Build Verification -- [ ] 9. Package Validation -- [ ] 10. Azure Policy Validation -- [ ] 11. Aspire Post-Provisioning Checks +- [ ] 9. Docker Build Context Validation +- [ ] 10. Package Validation +- [ ] 11. Azure Policy Validation +- [ ] 12. Aspire Post-Provisioning Checks ## Validation Details @@ -109,7 +110,22 @@ azd provision --preview --no-prompt Build the project and verify there are no errors. If the build fails, fix the issues and re-build until it succeeds. Do NOT proceed to packaging or deployment with build errors. -### 9. Package Validation +### 9. Docker Build Context Validation + +**If any service in `azure.yaml` uses a Dockerfile** (check the service's `project` path from `azure.yaml` for a `Dockerfile`), validate the build context before packaging: + +1. Read each service's `Dockerfile` +2. If the Dockerfile contains `npm ci`, verify `package-lock.json` exists in the same directory +3. If `package-lock.json` is missing, generate it in the service's `project` path directory before proceeding: + +```bash +cd +npm install --package-lock-only +``` + +> ⚠️ **Warning:** `npm ci` will fail during Docker build if `package-lock.json` is missing. This check prevents Docker build failures during `azd package` and `azd up`. + +### 10. Package Validation Confirm all services package successfully: @@ -117,11 +133,11 @@ Confirm all services package successfully: azd package --no-prompt ``` -### 10. Azure Policy Validation +### 11. Azure Policy Validation See [Policy Validation Guide](../../policy-validation.md) for instructions on retrieving and validating Azure policies for your subscription. -### 11. Aspire Post-Provisioning Checks +### 12. Aspire Post-Provisioning Checks **If this is a .NET Aspire project**, run the **Post-Provisioning** checks in [Aspire Validation](aspire.md) before proceeding to deployment. **If not Aspire, skip this step.** diff --git a/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azd/errors.md b/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azd/errors.md index c5d655d5..8fb1cde8 100644 --- a/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azd/errors.md +++ b/.github/plugins/azure-skills/skills/azure-validate/references/recipes/azd/errors.md @@ -14,6 +14,7 @@ These errors can be caught **before** running `azd up`: | `Invalid azure.yaml` | YAML syntax error | Fix YAML syntax | | `Project path does not exist` | Wrong service project path | Fix service project path in azure.yaml | | `Cannot connect to Docker daemon` | Docker not running | Start Docker Desktop | +| `npm ci` fails with `missing: package-lock.json` | Dockerfile uses `npm ci` but `package-lock.json` not in build context | Run `npm install --package-lock-only` in the service directory before building | | `Could not find a part of the path 'infra\main.bicep'` | Missing infrastructure files | Generate infra/ folder before `azd up` | | `Invalid resource group location ''. The Resource group already exists in location ''` | RG exists in different region | Check RG location first with `az group show`, use that region or new env name | | `expecting only '1' resource tagged with 'azd-service-name: web', but found '2'` | Multiple resources with same tag **in the same RG** | Delete duplicate or rename service | diff --git a/.github/plugins/azure-skills/skills/azure-validate/references/role-verification.md b/.github/plugins/azure-skills/skills/azure-validate/references/role-verification.md new file mode 100644 index 00000000..9038cc04 --- /dev/null +++ b/.github/plugins/azure-skills/skills/azure-validate/references/role-verification.md @@ -0,0 +1,75 @@ +# Role Assignment Verification + +Verify that all RBAC role assignments in the generated infrastructure are correct and sufficient before deployment. Incorrect or missing roles are a common cause of runtime failures. + +## When to Verify + +After build verification (step 4) and **before** recording proof (step 6). Role issues surface as cryptic auth errors during deployment — catching them here saves debugging time. + +## Verification Checklist + +Review every resource-to-identity relationship in the generated Bicep/Terraform: + +| Check | How | +|-------|-----| +| **Every service identity has roles** | Each app with a managed identity must have at least one role assignment | +| **Roles match data operations** | Use service-specific **data-plane** roles for data access (see mapping table below); use generic Reader/Contributor/Owner only for management-plane operations | +| **Scope is least privilege** | Roles scoped to specific resources, not resource groups or subscriptions | +| **No missing roles** | Cross-check app code operations against assigned roles (see table below) | +| **Local dev identity has roles** | If testing locally, the user's identity needs equivalent roles via `az login` | + +## Common Service-to-Role Mapping + +| Service Operation | Required Role | Common Mistake | +|-------------------|---------------|----------------| +| Read blobs | Storage Blob Data Reader | Using generic Reader (no data access) | +| Read + write blobs | Storage Blob Data Contributor | Missing write permission | +| Generate SAS via user delegation | Storage Blob Delegator + Data Reader/Contributor | Forgetting Delegator role | +| Read Key Vault secrets | Key Vault Secrets User | Using Key Vault Reader (no secret access) | +| Read + write Cosmos DB | Cosmos DB Built-in Data Contributor | Using generic Contributor | +| Send Service Bus messages | Azure Service Bus Data Sender | Using generic Contributor | +| Read queues | Storage Queue Data Reader | Using Blob role for queues | + +## How to Verify (Static Code Review) + +Review the generated Bicep/Terraform files directly — do **not** query live Azure state here. For each role assignment resource in your infrastructure code: + +1. Identify the **principal** (which managed identity) +2. Identify the **role** (which role definition) +3. Identify the **scope** (which target resource) +4. Cross-check against the app code to confirm the role grants the required data-plane access + +> 💡 **Tip:** Search your Bicep for `Microsoft.Authorization/roleAssignments` or your Terraform for `azurerm_role_assignment` to find all role assignments. + +> ⚠️ **Live role verification** (querying Azure for actually provisioned roles) is handled by **azure-deploy** step 8 as a post-deployment check. This step is a static code review only. + +## Decision Tree + +``` +For each app identity in the generated infrastructure: +├── Has role assignments? +│ ├── No → Add required role assignments to Bicep/Terraform +│ └── Yes → Check each role: +│ ├── Role matches code operations? → ✅ OK +│ ├── Role too broad? → Narrow to least privilege +│ └── Role insufficient? → Upgrade or add missing role +│ +For local testing: +├── User identity has equivalent roles? +│ ├── No → Grant roles via CLI or inform user +│ └── Yes → ✅ Ready for functional verification +``` + +> ⚠️ **Warning:** Generic roles like `Contributor` or `Reader` do **not** include data-plane access. For example, `Contributor` on a Storage Account cannot read blobs — you need `Storage Blob Data Contributor`. This is the most common RBAC mistake. + +## Record in Plan + +After role verification, update `.azure/plan.md`: + +```markdown +## Role Assignment Verification +- Status: Verified / Issues Found +- Identities checked: +- Roles confirmed: +- Issues: +``` diff --git a/.github/plugins/azure-skills/skills/entra-app-registration/SKILL.md b/.github/plugins/azure-skills/skills/entra-app-registration/SKILL.md index f26678ef..c30c2e79 100644 --- a/.github/plugins/azure-skills/skills/entra-app-registration/SKILL.md +++ b/.github/plugins/azure-skills/skills/entra-app-registration/SKILL.md @@ -1,6 +1,6 @@ --- name: entra-app-registration -description: "Guides Microsoft Entra app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Microsoft Entra app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Microsoft Entra authentication. DO NOT USE FOR: Azure RBAC or role assignments (use azure-rbac), Key Vault secrets (use azure-keyvault-expiration-audit), Azure resource security (use azure-security)." +description: "Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Azure RBAC or role assignments (use azure-rbac), Key Vault secrets (use azure-keyvault-expiration-audit), Azure resource security (use azure-security)." license: MIT metadata: author: Microsoft @@ -9,7 +9,7 @@ metadata: ## Overview -Microsoft Entra ID is Microsoft's cloud-based identity and access management service. App registrations allow applications to authenticate users and access Azure resources securely. +Microsoft Entra ID (formerly Azure Active Directory) is Microsoft's cloud-based identity and access management service. App registrations allow applications to authenticate users and access Azure resources securely. ### Key Concepts @@ -17,7 +17,7 @@ Microsoft Entra ID is Microsoft's cloud-based identity and access management ser |---------|-------------| | **App Registration** | Configuration that allows an app to use Microsoft identity platform | | **Application (Client) ID** | Unique identifier for your application | -| **Tenant ID** | Unique identifier for your Microsoft Entra tenant/directory | +| **Tenant ID** | Unique identifier for your Azure AD tenant/directory | | **Client Secret** | Password for the application (confidential clients only) | | **Redirect URI** | URL where authentication responses are sent | | **API Permissions** | Access scopes your app requests | @@ -148,10 +148,7 @@ Set up daemon/service authentication without user interaction. MSAL is the recommended library for integrating Microsoft identity platform. **Supported Languages:** - -- .NET - `Microsoft.Identity.Client` -- Go - `github.com/AzureAD/microsoft-authentication-library-for-go` -- Java - `msal4j` +- .NET/C# - `Microsoft.Identity.Client` - JavaScript/TypeScript - `@azure/msal-browser`, `@azure/msal-node` - Python - `msal` @@ -173,8 +170,8 @@ MSAL is the recommended library for integrating Microsoft identity platform. ## SDK Quick References -- **Azure Identity**: [.NET](references/sdk/azure-identity-dotnet.md) | [Go](references/sdk/azure-identity-go.md) | [Java](references/sdk/azure-identity-java.md) | [JavaScript / TypeScript](references/sdk/azure-identity-ts.md) | [Python](references/sdk/azure-identity-py.md) | [Rust](references/sdk/azure-identity-rust.md) -- **Key Vault (secrets)**: [Python](references/sdk/azure-keyvault-py.md) | [JavaScript / TypeScript](references/sdk/azure-keyvault-secrets-ts.md) +- **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md) | [Rust](references/sdk/azure-identity-rust.md) +- **Key Vault (secrets)**: [Python](references/sdk/azure-keyvault-py.md) | [TypeScript](references/sdk/azure-keyvault-secrets-ts.md) - **Auth Events**: [.NET](references/sdk/microsoft-azure-webjobs-extensions-authentication-events-dotnet.md) ## References diff --git a/.github/plugins/azure-skills/skills/entra-app-registration/references/auth-best-practices.md b/.github/plugins/azure-skills/skills/entra-app-registration/references/auth-best-practices.md index c55c6e55..6938d5f0 100644 --- a/.github/plugins/azure-skills/skills/entra-app-registration/references/auth-best-practices.md +++ b/.github/plugins/azure-skills/skills/entra-app-registration/references/auth-best-practices.md @@ -8,33 +8,21 @@ Use **managed identities** and **Azure RBAC** in production. Reserve `DefaultAzu ## 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` (`CertificateCredential` in Python) or `WorkloadIdentityCredential` | Deterministic; no fallback chain overhead | -| **CI/CD pipelines** | `AzurePipelinesCredential` | Scoped to pipeline identity | -| **Local development** | `DefaultAzureCredential` | Chains dev tool credentials for convenience | +| 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? +## 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. -## Environment-Aware Pattern - -Detect the runtime environment and select the appropriate credential. The key principle is to use `DefaultAzureCredential` only when running locally, and a specific credential in production. Set the `AZURE_TOKEN_CREDENTIALS` environment variable to `"dev"` or a specific developer tool credential (e.g., `"AzureCli"`, `"AzurePowerShell"`, `"VisualStudioCode"`) to skip unnecessary credential checks and speed up authentication in your local environment. - -See the language-specific overviews for the full `DefaultAzureCredential` credential chain and its configuration options: - -- [.NET](https://aka.ms/azsdk/net/identity/credential-chains#defaultazurecredential-overview) -- [Go](https://aka.ms/azsdk/go/identity/credential-chains#defaultazurecredential-overview) -- [Java](https://aka.ms/azsdk/java/identity/credential-chains#defaultazurecredential-overview) -- [JavaScript](https://aka.ms/azsdk/js/identity/credential-chains#use-defaultazurecredential-for-flexibility) -- [Python](https://aka.ms/azsdk/python/identity/credential-chains#defaultazurecredential-overview) - -> **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`). +## Production Patterns ### .NET @@ -42,33 +30,34 @@ See the language-specific overviews for the full `DefaultAzureCredential` creden using Azure.Identity; var credential = Environment.GetEnvironmentVariable("AZURE_FUNCTIONS_ENVIRONMENT") == "Development" - ? new DefaultAzureCredential(DefaultAzureCredential.DefaultEnvironmentVariableName) // local dev — uses dev tool credentials - : new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned); // production — deterministic, no fallback chain -// For user-assigned managed identity: -// new ManagedIdentityCredential(ManagedIdentityId.FromUserAssignedClientId("")) + ? new DefaultAzureCredential() // local dev — uses CLI/VS credentials + : new ManagedIdentityCredential(); // production — deterministic, no fallback chain +// For user-assigned identity: new ManagedIdentityCredential("") ``` -### Go +### TypeScript / JavaScript -```go -import ( - "os" +```typescript +import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity"; - "github.com/Azure/azure-sdk-for-go/sdk/azcore" - "github.com/Azure/azure-sdk-for-go/sdk/azidentity" -) +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("") +``` -func getCredential() (azcore.TokenCredential, error) { - if os.Getenv("AZURE_FUNCTIONS_ENVIRONMENT") == "Development" { - opts := azidentity.DefaultAzureCredentialOptions{RequireAzureTokenCredentials: true} - return azidentity.NewDefaultAzureCredential(&opts) // local dev — uses dev tool credentials - } - return azidentity.NewManagedIdentityCredential(nil) // production — deterministic, no fallback chain - // For user-assigned managed identity: - // azidentity.NewManagedIdentityCredential(&azidentity.ManagedIdentityCredentialOptions{ - // ID: azidentity.ClientID(""), - // }) -} +### 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 @@ -78,41 +67,44 @@ import com.azure.identity.DefaultAzureCredentialBuilder; import com.azure.identity.ManagedIdentityCredentialBuilder; var credential = "Development".equals(System.getenv("AZURE_FUNCTIONS_ENVIRONMENT")) - ? new DefaultAzureCredentialBuilder() - .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS) - .build() // local dev — uses dev tool credentials - : new ManagedIdentityCredentialBuilder().build(); // production — deterministic, no fallback chain -// For user-assigned managed identity: -// new ManagedIdentityCredentialBuilder().clientId("").build() + ? 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() ``` -### Python +## Local Development Setup -```python -import os -from azure.identity import DefaultAzureCredential, ManagedIdentityCredential +`DefaultAzureCredential` is ideal for local dev because it automatically picks up credentials from developer tools: -credential = ( - DefaultAzureCredential(require_envvar=True) # local dev — uses dev tool credentials - if os.getenv("AZURE_FUNCTIONS_ENVIRONMENT") == "Development" - else ManagedIdentityCredential() # production — deterministic, no fallback chain -) -# For user-assigned managed identity: -# ManagedIdentityCredential(client_id="") +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(); ``` -### TypeScript / JavaScript +## 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"; -const credential = process.env.NODE_ENV === "development" - ? new DefaultAzureCredential({ - requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ] - }) // local dev — uses dev tool credentials - : new ManagedIdentityCredential(); // production — deterministic, no fallback chain -// For user-assigned managed identity: -// new ManagedIdentityCredential({ clientId: ""}) +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 @@ -123,8 +115,6 @@ const credential = process.env.NODE_ENV === "development" - [ ] Use `ManagedIdentityCredential` (not `DefaultAzureCredential`) in production - [ ] Store any required secrets in Azure Key Vault - [ ] Rotate secrets and certificates on a schedule -- [ ] Set `AZURE_TOKEN_CREDENTIALS` in local dev environments to restrict the `DefaultAzureCredential` credential chain -- [ ] Enable Azure SDK diagnostic logging to troubleshoot authentication failures - [ ] Enable Microsoft Defender for Cloud on production resources ## Further Reading @@ -132,8 +122,7 @@ const credential = process.env.NODE_ENV === "development" - [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) -- [Azure Identity library for .NET](https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme) -- [Azure Identity library for Go](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#section-readme) -- [Azure Identity library for Java](https://learn.microsoft.com/java/api/overview/azure/identity-readme) -- [Azure Identity library for JavaScript](https://learn.microsoft.com/javascript/api/overview/azure/identity-readme) -- [Azure Identity library for Python](https://learn.microsoft.com/python/api/overview/azure/identity-readme) +- [.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/entra-app-registration/references/sdk/azure-identity-dotnet.md b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-dotnet.md index 705bcdc6..5bec6aae 100644 --- a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-dotnet.md +++ b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-dotnet.md @@ -1,31 +1,22 @@ -# Authentication — .NET Library Quick Reference +# Authentication — .NET SDK Quick Reference -> Condensed from **azure-identity-dotnet**. Full patterns (ASP.NET Core DI, +> Condensed from **azure-identity-dotnet**. Full patterns (ASP.NET DI, > sovereign clouds, brokered auth, certificate credentials) > in the **azure-identity-dotnet** plugin skill if installed. ## Install - -```bash dotnet add package Azure.Identity -``` - -## Quickstart +## Quick Start > **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. ```csharp using Azure.Identity; - var credential = new DefaultAzureCredential(); ``` ## Best Practices - -- Use `DefaultAzureCredential` for **local development only**. In production, use deterministic credentials (`ManagedIdentityCredential`) — see [auth-best-practices.md](../auth-best-practices.md) +- Use DefaultAzureCredential for **local development only**. In production, use deterministic credentials (ManagedIdentityCredential) — see [auth-best-practices.md](../auth-best-practices.md) - Reuse credential instances — single instance shared across clients -- Azure CLI for local dev — run `az login` before running your app -- Least privilege — grant only required permissions to service principals - Configure retry policies for credential operations -- Enable logging with `AzureEventSourceListener` for debugging auth issues -- Environment variables — use for CI/CD, not hardcoded secrets +- Enable logging with AzureEventSourceListener for debugging auth issues diff --git a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-go.md b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-go.md deleted file mode 100644 index b12bfbd1..00000000 --- a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-go.md +++ /dev/null @@ -1,37 +0,0 @@ -# Authentication — Go Library Quick Reference - -> Condensed from **azure-identity-go**. Full patterns (workload identity, -> certificate auth, device code, sovereign clouds) -> in the **azure-identity-go** plugin skill if installed. - -## Install - -```bash -go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity -``` - -## Quickstart - -> **Auth:** `DefaultAzureCredential` is best for prototyping or local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. - -```go -import ( - "log" - - "github.com/Azure/azure-sdk-for-go/sdk/azidentity" -) - -cred, err := azidentity.NewDefaultAzureCredential(nil) -if err != nil { - log.Fatal(err) -} -``` - -## Best Practices - -- Use `DefaultAzureCredential` for **local development only** (CLI, PowerShell, VS Code). In production, use `ManagedIdentityCredential` — see [auth-best-practices.md](../auth-best-practices.md) -- Managed identity in production — no secrets to manage, automatic rotation -- Azure CLI for local dev — run `az login` before running your app -- Least privilege — grant only required permissions to service principals -- Token caching — enabled by default, reduces auth round-trips -- Environment variables — use for CI/CD, not hardcoded secrets diff --git a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-java.md b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-java.md index bfae736f..0681b73a 100644 --- a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-java.md +++ b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-java.md @@ -1,34 +1,28 @@ -# Authentication — Java Library Quick Reference +# Authentication — Java SDK Quick Reference > Condensed from **azure-identity-java**. Full patterns (workload identity, > certificate auth, device code, sovereign clouds) > in the **azure-identity-java** plugin skill if installed. ## Install - ```xml com.azure azure-identity - + 1.15.0 ``` -## Quickstart - -> **Auth:** `DefaultAzureCredential` is best for prototyping or local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. +## Quick Start +> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. ```java -import com.azure.identity.DefaultAzureCredential; import com.azure.identity.DefaultAzureCredentialBuilder; - -DefaultAzureCredential credential = new DefaultAzureCredentialBuilder() - .build(); +var credential = new DefaultAzureCredentialBuilder().build(); ``` ## Best Practices - -- Use `DefaultAzureCredential` for **local development only** (CLI, PowerShell, VS Code). In production, use `ManagedIdentityCredential` — see [auth-best-practices.md](../auth-best-practices.md) +- Use DefaultAzureCredential for **local development only** (CLI, PowerShell, VS Code). In production, use ManagedIdentityCredential — see [auth-best-practices.md](../auth-best-practices.md) - Managed identity in production — no secrets to manage, automatic rotation - Azure CLI for local dev — run `az login` before running your app - Least privilege — grant only required permissions to service principals diff --git a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-py.md b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-py.md index ffb6e07b..f73e44db 100644 --- a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-py.md +++ b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-py.md @@ -1,31 +1,27 @@ -# Authentication — Python Library Quick Reference +# Authentication — Python SDK Quick Reference > Condensed from **azure-identity-py**. Full patterns (async, > ChainedTokenCredential, token caching, all credential types) > in the **azure-identity-py** plugin skill if installed. ## Install - ```bash pip install azure-identity ``` -## Quickstart - -> **Auth:** `DefaultAzureCredential` is best for prototyping or local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. +## Quick Start +> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. ```python from azure.identity import DefaultAzureCredential - credential = DefaultAzureCredential() ``` ## Best Practices - -- Use `DefaultAzureCredential` for **local development only** (CLI, PowerShell, VS Code). In production, use `ManagedIdentityCredential` — see [auth-best-practices.md](../auth-best-practices.md) +- Use DefaultAzureCredential for **local development only** (CLI, PowerShell, VS Code). In production, use ManagedIdentityCredential — see [auth-best-practices.md](../auth-best-practices.md) - Never hardcode credentials — use environment variables or managed identity - Prefer managed identity in production Azure deployments -- Use `ChainedTokenCredential` when you need a custom credential order +- Use ChainedTokenCredential when you need a custom credential order - Close async credentials explicitly or use context managers -- Set `AZURE_CLIENT_ID` env var for user-assigned managed identities +- Set AZURE_CLIENT_ID env var for user-assigned managed identities - Exclude unused credentials to speed up authentication diff --git a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-rust.md b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-rust.md index c9c2c1b1..30057e22 100644 --- a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-rust.md +++ b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-rust.md @@ -1,29 +1,21 @@ -# Authentication — Rust Library Quick Reference +# Authentication — Rust SDK Quick Reference > Condensed from **azure-identity-rust**. Full patterns (ClientSecret, > ClientCertificate, WorkloadIdentity, AzurePipelines credentials) > in the **azure-identity-rust** plugin skill if installed. ## Install - -```bash cargo add azure_identity -``` - -## Quickstart - -> **Auth:** `DeveloperToolsCredential` is best for prototyping or local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. +## Quick Start ```rust use azure_identity::DeveloperToolsCredential; - let credential = DeveloperToolsCredential::new(None)?; ``` ## Best Practices - -- Use `DeveloperToolsCredential` for local dev — automatically picks up Azure CLI -- Use `ManagedIdentityCredential` in production — no secrets to manage +- Use DeveloperToolsCredential for local dev — automatically picks up Azure CLI +- Use ManagedIdentityCredential in production — no secrets to manage - Clone credentials — credentials are Arc-wrapped and cheap to clone - Reuse credential instances — same credential can be used with multiple clients - Use tokio feature — `cargo add azure_identity --features tokio` diff --git a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-ts.md b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-ts.md index 49d43fee..e1a64790 100644 --- a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-ts.md +++ b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-identity-ts.md @@ -1,30 +1,24 @@ -# Authentication — TypeScript Library Quick Reference +# Authentication — TypeScript SDK Quick Reference > Condensed from **azure-identity-ts**. Full patterns (sovereign clouds, > device code flow, custom credentials, bearer token provider) > in the **azure-identity-ts** plugin skill if installed. ## Install - -```bash npm install @azure/identity -``` - -## Quickstart -> **Auth:** `DefaultAzureCredential` is best for prototyping or local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. +## Quick Start +> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. ```typescript import { DefaultAzureCredential } from "@azure/identity"; - const credential = new DefaultAzureCredential(); ``` ## Best Practices - -- Use `DefaultAzureCredential` for **local development only** (CLI, PowerShell, VS Code). In production, use `ManagedIdentityCredential` — see [auth-best-practices.md](../auth-best-practices.md) +- Use DefaultAzureCredential for **local development only** (CLI, PowerShell, VS Code). In production, use ManagedIdentityCredential — see [auth-best-practices.md](../auth-best-practices.md) - Never hardcode credentials — use environment variables or managed identity - Prefer managed identity — no secrets to manage in production - Scope credentials appropriately — use user-assigned identity for multi-tenant scenarios - Handle token refresh — Azure SDK handles this automatically -- Use `ChainedTokenCredential` for custom fallback scenarios +- Use ChainedTokenCredential for custom fallback scenarios diff --git a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-keyvault-py.md b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-keyvault-py.md index 6637144d..043c80cb 100644 --- a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-keyvault-py.md +++ b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-keyvault-py.md @@ -1,32 +1,21 @@ -# Key Vault — Python Library Quick Reference +# Key Vault — Python SDK Quick Reference > Condensed from **azure-keyvault-py**. Full patterns (async clients, > cryptographic operations, certificate management, error handling) > in the **azure-keyvault-py** plugin skill if installed. ## Install - -```bash pip install azure-keyvault-secrets azure-keyvault-keys azure-keyvault-certificates azure-identity -``` - -## Quickstart - -> **Auth:** `DefaultAzureCredential` is best for prototyping or local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns. +## Quick Start ```python from azure.identity import DefaultAzureCredential from azure.keyvault.secrets import SecretClient - -client = SecretClient( - vault_url="https://.vault.azure.net/", - credential=DefaultAzureCredential() -) +client = SecretClient(vault_url="https://.vault.azure.net/", credential=DefaultAzureCredential()) ``` ## Best Practices - -- Use `DefaultAzureCredential` for **local development only**. In production, use `ManagedIdentityCredential` — see [auth-best-practices.md](../auth-best-practices.md) +- Use DefaultAzureCredential for **local development only**. In production, use ManagedIdentityCredential — see [auth-best-practices.md](../auth-best-practices.md) - Use managed identity in Azure-hosted applications - Enable soft-delete for recovery (enabled by default) - Use RBAC over access policies for fine-grained control diff --git a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-keyvault-secrets-ts.md b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-keyvault-secrets-ts.md index 319f1ae9..3a7dce4d 100644 --- a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-keyvault-secrets-ts.md +++ b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/azure-keyvault-secrets-ts.md @@ -1,29 +1,23 @@ -# Key Vault Secrets — TypeScript Library Quick Reference +# Key Vault Secrets — TypeScript SDK Quick Reference > Condensed from **azure-keyvault-secrets-ts**. Full patterns (key rotation, > cryptographic operations, backup/restore, wrap/unwrap) > in the **azure-keyvault-secrets-ts** plugin skill if installed. ## Install - -```bash npm install @azure/keyvault-secrets @azure/identity -``` - -## Quickstart +## Quick Start ```typescript import { DefaultAzureCredential } from "@azure/identity"; import { SecretClient } from "@azure/keyvault-secrets"; - const client = new SecretClient("https://.vault.azure.net", new DefaultAzureCredential()); ``` ## Best Practices - -- Use `DefaultAzureCredential` for prototyping or **local development only**. In production, use `ManagedIdentityCredential` — see [auth-best-practices.md](../auth-best-practices.md) +- Use DefaultAzureCredential for **local development only**. In production, use ManagedIdentityCredential — see [auth-best-practices.md](../auth-best-practices.md) - Enable soft-delete — required for production vaults - Set expiration dates on both keys and secrets - Use key rotation policies — automate key rotation - Limit key operations — only grant needed operations (encrypt, sign, etc.) -- Browser not supported — these libraries are Node.js only +- Browser not supported — these SDKs are Node.js only diff --git a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/microsoft-azure-webjobs-extensions-authentication-events-dotnet.md b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/microsoft-azure-webjobs-extensions-authentication-events-dotnet.md index e9071da0..9b2aef9a 100644 --- a/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/microsoft-azure-webjobs-extensions-authentication-events-dotnet.md +++ b/.github/plugins/azure-skills/skills/entra-app-registration/references/sdk/microsoft-azure-webjobs-extensions-authentication-events-dotnet.md @@ -1,17 +1,13 @@ -# Authentication Events — .NET Library Quick Reference +# Authentication Events — .NET SDK Quick Reference > Condensed from **microsoft-azure-webjobs-extensions-authentication-events-dotnet**. > Full patterns (attribute collection, OTP customization, external data enrichment) > in the source plugin skill if installed. ## Install - -```bash dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents -``` - -## Quickstart +## Quick Start ```csharp using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents; using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart; @@ -31,7 +27,6 @@ public static WebJobsAuthenticationEventResponse Run( ``` ## Best Practices - - Validate all inputs — never trust request data; validate before processing - Handle errors gracefully — return appropriate error responses, don't throw - Log correlation IDs — use CorrelationId for troubleshooting