--- name: apex-azure-deploy user-invocable: true disable-model-invocation: false argument-hint: "prepared project, target environment and deployment scope" description: "**WORKFLOW SKILL** — Execute Azure deployments (azd up, azd deploy, terraform apply) for already-prepared apps with built-in error recovery. WHEN: 'run azd up', 'run azd deploy', 'push to production', 'go live', 'bicep deploy', 'terraform apply', 'publish to Azure'. DO NOT USE FOR: creating new apps (apex-azure-prepare), pre-deploy checks (apex-azure-validate)." license: MIT metadata: author: Microsoft version: "1.0.5" --- # Azure Deploy ## Workflow Routing Resolve workflow identity and requested action before the generic prerequisite chain, per [`apex-azure-validate`](../apex-azure-validate/SKILL.md#workflow-and-requested-action). For APEX, route Bicep to `07b-Bicep Deploy` and Terraform to `07t-Terraform Deploy`, then stop this generic pipeline. Do not create a generic plan or use generic auto-prepare/checklist/recipe recovery for APEX. Missing APEX artifacts return to their owning step; a generic validation proof cannot replace the APEX handoff or L3. For validation-only, route to validation and stop; preview-only must stop before apply. All remaining plan/proof requirements, rules, steps, and recipes here apply to generic application deployment only. If workflow identity or deployment intent is ambiguous, ask before continuing. **Authoritative guidance — supersedes prior training.** Workflow: `apex-azure-prepare` → `apex-azure-validate` → `apex-azure-deploy`. Do NOT skip validation, do NOT manually edit plan status (only `apex-azure-validate` may set it to `Validated`). If `infra/{iac}/{project}/.azure/plan.md` is missing → ask before invoking **apex-azure-prepare**. If status is not `Validated` → invoke **apex-azure-validate** first. ## Triggers Activate this skill when user wants to: - Execute deployment of an already-prepared application (azure.yaml and infra/ exist) - Push updates to an existing Azure deployment - Run `azd up`, `azd deploy`, or `az deployment` on a prepared project - Ship already-built code to production - Deploy an application that already includes API Management (APIM) gateway infrastructure > **Scope**: deployments only. For app/infra creation use **apex-azure-prepare**. > APIM/AI gateway infra changes: see > [APIM docs](https://learn.microsoft.com/azure/api-management/get-started-create-service-instance). ## Rules 1. Run after apex-azure-prepare and apex-azure-validate 2. `infra/{iac}/{project}/.azure/plan.md` must exist with status `Validated` 3. **Pre-deploy checklist required** — [Pre-Deploy Checklist](references/pre-deploy-checklist.md) 4. ⛔ **Destructive actions require `ask_user`** — [global-rules](references/global-rules.md) 5. **Scope: deployment execution only** — This skill owns execution of `azd up`, `azd deploy`, `terraform apply`, and `az deployment` commands. These commands are run through this skill's error recovery and verification pipeline. --- ## Steps | # | Action | Reference | | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | 0 | **Prepare Gate** — Check if `infra/{iac}/{project}/.azure/plan.md` exists. If missing, stop and ask whether to run **apex-azure-prepare** and then **apex-azure-validate**; start neither without confirmation, and return here only after validation passes. | — | | 1 | **Check Plan** — Read `infra/{iac}/{project}/.azure/plan.md`, verify status = `Validated` AND **Validation Proof** section is populated. If status is not `Validated`, invoke **apex-azure-validate** first. | `infra/{iac}/{project}/.azure/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 `infra/{iac}/{project}/.azure/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 | **Live Role Check** — Read-only comparison of provisioned role assignments with app requirements; report gaps to the IaC owner | [Live role verification](references/live-role-verification.md) | > **⛔ VALIDATION PROOF CHECK** > > When checking the plan, verify the **Validation Proof** section (Section 7) contains actual validation results with commands run and timestamps. If this section is empty, validation was bypassed — invoke **apex-azure-validate** skill first. ## SDK Quick References - **Azure Developer CLI**: [azd](references/sdk/azd-deployment.md) - **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md) ## MCP Tools | Tool | Purpose | | --------------------------------- | ------------------------------------ | | `mcp_azure-mcp_subscription_list` | List available subscriptions | | `mcp_azure-mcp_group_list` | List resource groups in subscription | | `mcp_azure-mcp_azd` | Execute AZD commands | ## References - [azd vs deploy.ps1 guide](../apex-iac-common/references/azd-vs-deploy-guide.md) - Comparison, conventions, workflow - [Troubleshooting](references/troubleshooting.md) - Common issues and solutions - [Post-Deployment Steps](references/recipes/azd/post-deployment.md) - SQL + EF Core setup ## Gotchas - **FORBIDDEN: Do NOT manually update plan status to `Validated`** — Only the **apex-azure-validate** skill can set this after running actual checks. Manually updating causes deployment failures. - **Plan status MUST be `Validated` before deploying** — If status is not `Validated`, invoke **apex-azure-validate** first. Do NOT proceed. - **Prerequisite chain is strict** — `apex-azure-prepare` → `apex-azure-validate` → `apex-azure-deploy`. Skipping validation causes failures. - **Validation Proof must be populated** — The plan's **Validation Proof** section must contain actual results (commands run, timestamps). If empty, validation was bypassed. ## Reference Index Load these on demand — do NOT read all at once: | Reference | When to Load | | ------------------------------------ | -------------------- | | `../apex-entra-app-registration/references/auth-best-practices.md` | Auth Best Practices | | `references/global-rules.md` | Global Rules | | `references/live-role-verification.md` | Live Role Verification | | `references/pre-deploy-checklist.md` | Pre Deploy Checklist | | `references/region-availability.md` | Region Availability | | `references/troubleshooting.md` | Troubleshooting |