mirror of
https://github.com/github/awesome-copilot.git
synced 2026-04-14 04:05:58 +00:00
Add azure-architecture-autopilot skill 🤖🤖🤖 (#1158)
* Add azure-architecture-autopilot skill E2E Azure infrastructure automation skill: - Natural language → Architecture diagram → Bicep → Deploy - 70+ service types with 605+ official Azure icons - Interactive HTML diagrams (drag, zoom, click, PNG export) - Scans existing resources or designs new architecture - Modular Bicep with RBAC, Private Endpoints, DNS - Multi-language support (auto-detects user language) - Zero dependencies (diagram engine embedded) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix generator.py import for flat scripts/ structure + sync README Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: whoniiii <whoniiii@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jeonghoon Lee
GitHub
@@ -0,0 +1,318 @@
|
||||
# Phase 4: Deployment Agent
|
||||
|
||||
This file contains detailed instructions for Phase 4. Read and follow this file when the user approves deployment after Phase 3 (code review) is complete.
|
||||
|
||||
---
|
||||
|
||||
**🚨🚨🚨 Phase 4 Mandatory Execution Order — Never Skip Any Step 🚨🚨🚨**
|
||||
|
||||
The following 5 steps must be executed **strictly in order**. No step may be omitted or skipped.
|
||||
Even if the user requests deployment with "deploy it", "go ahead", "do it", etc., always proceed from Step 1 in order.
|
||||
|
||||
```
|
||||
Step 1: Verify prerequisites (az login, subscription, resource group)
|
||||
↓
|
||||
Step 2: What-if validation (az deployment group what-if) ← Must execute
|
||||
↓
|
||||
Step 3: Generate preview diagram (02_arch_diagram_preview.html) ← Must generate
|
||||
↓
|
||||
Step 4: Actual deployment after user final confirmation (az deployment group create)
|
||||
↓
|
||||
Step 5: Generate deployment result diagram (03_arch_diagram_result.html)
|
||||
```
|
||||
|
||||
**Never do the following:**
|
||||
- Execute `az deployment group create` directly without What-if
|
||||
- Skip generating the preview diagram (`02_arch_diagram_preview.html`)
|
||||
- Proceed with deployment without showing What-if results to the user
|
||||
- Only provide `az` commands for the user to run manually
|
||||
|
||||
---
|
||||
|
||||
### Step 1: Verify Prerequisites
|
||||
|
||||
```powershell
|
||||
# Verify az CLI installation and login
|
||||
az account show 2>&1
|
||||
```
|
||||
|
||||
If not logged in, ask the user to run `az login`.
|
||||
The agent must never enter or store credentials directly.
|
||||
|
||||
Create resource group:
|
||||
```powershell
|
||||
az group create --name "<RG_NAME>" --location "<LOCATION>" # Location confirmed in Phase 1
|
||||
```
|
||||
→ Proceed to next step after confirming success
|
||||
|
||||
### Step 2: Validate → What-if Validation — 🚨 Mandatory
|
||||
|
||||
**Do not skip this step. Always execute it no matter how urgently the user requests deployment.**
|
||||
|
||||
**Step 2-A: Run Validate First (Quick Pre-validation)**
|
||||
|
||||
`what-if` can **hang indefinitely without error messages** when there are Azure policy violations, resource reference errors, etc.
|
||||
To prevent this, **always run `validate` first**. Validate returns errors quickly.
|
||||
|
||||
```powershell
|
||||
# validate — Quickly catches policy violations, schema errors, parameter issues
|
||||
az deployment group validate `
|
||||
--resource-group "<RG_NAME>" `
|
||||
--parameters main.bicepparam
|
||||
```
|
||||
|
||||
- **Validate succeeds** → Proceed to Step 2-B (what-if)
|
||||
- **Validate fails** → Analyze error messages, fix Bicep, recompile, re-validate
|
||||
- Azure Policy violation (`RequestDisallowedByPolicy`) → Reflect policy requirements in Bicep (e.g., `azureADOnlyAuthentication: true`)
|
||||
- Schema error → Fix API version/properties
|
||||
- Parameter error → Fix parameter file
|
||||
|
||||
**Step 2-B: Run What-if**
|
||||
|
||||
Run what-if after validate passes.
|
||||
|
||||
**Choose parameter passing method:**
|
||||
- If all `@secure()` parameters have default values → Use `.bicepparam`
|
||||
- If `@secure()` parameters require user input → Use `--template-file` + JSON parameter file
|
||||
|
||||
```powershell
|
||||
# Method 1: Use .bicepparam (when all @secure() parameters have defaults)
|
||||
az deployment group what-if `
|
||||
--resource-group "<RG_NAME>" `
|
||||
--parameters main.bicepparam
|
||||
|
||||
# Method 2: Use JSON parameter file (when @secure() parameters require user input)
|
||||
az deployment group what-if `
|
||||
--resource-group "<RG_NAME>" `
|
||||
--template-file main.bicep `
|
||||
--parameters main.parameters.json `
|
||||
--parameters secureParam='value'
|
||||
```
|
||||
→ Summarize the What-if results and present them to the user.
|
||||
|
||||
**⏱️ What-if Execution Method and Timeout Handling:**
|
||||
|
||||
What-if performs resource validation on the Azure server side, so it may take time depending on the service/region.
|
||||
**Always execute with `initial_wait: 300` (5 minutes).** If not completed within 5 minutes, it automatically times out.
|
||||
|
||||
```powershell
|
||||
# Always set initial_wait: 300 when calling the powershell tool
|
||||
# mode: "sync", initial_wait: 300
|
||||
az deployment group what-if `
|
||||
--resource-group "<RG_NAME>" `
|
||||
--parameters main.bicepparam
|
||||
```
|
||||
|
||||
**Completed within 5 minutes** → Proceed normally (summarize results → preview diagram → deployment confirmation)
|
||||
|
||||
**Not completed within 5 minutes (timeout)** → Immediately stop with `stop_powershell` and offer choices to the user:
|
||||
|
||||
```
|
||||
ask_user({
|
||||
question: "What-if validation did not complete within 5 minutes. The Azure server response is delayed. How would you like to proceed?",
|
||||
choices: [
|
||||
"Retry (Recommended)",
|
||||
"Skip What-if and deploy directly"
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**If "Retry" is selected:** Re-execute the same command with `initial_wait: 300`. Retry up to 2 times maximum.
|
||||
**If "Skip What-if and deploy directly" is selected:**
|
||||
- Generate the preview diagram based on the Phase 1 draft
|
||||
- Inform the user of the risks:
|
||||
> **⚠️ Deploying without What-if validation.** Unexpected resource changes may occur. Please verify in the Azure Portal after deployment.
|
||||
|
||||
**Never do the following:**
|
||||
- Execute without setting `initial_wait`, causing indefinite waiting
|
||||
- Let the agent arbitrarily decide "what-if is optional" and skip it
|
||||
- Automatically switch to deployment without asking the user on timeout
|
||||
- Skip what-if for reasons like "deployment is faster"
|
||||
|
||||
### Step 3: Preview Diagram Based on What-if Results — 🚨 Mandatory
|
||||
|
||||
**Do not skip this step. Always generate the preview diagram when What-if succeeds.**
|
||||
|
||||
Regenerate the diagram using the actual resources to be deployed (resource names, types, locations, counts) from the What-if results.
|
||||
Keep the draft from Phase 1 (`01_arch_diagram_draft.html`) as-is, and generate the preview as `02_arch_diagram_preview.html`.
|
||||
The draft can be reopened at any time.
|
||||
|
||||
```
|
||||
## Architecture to Be Deployed (Based on What-if)
|
||||
|
||||
[Interactive diagram link — 02_arch_diagram_preview.html]
|
||||
(Design draft: 01_arch_diagram_draft.html)
|
||||
|
||||
Resources to be created (N items):
|
||||
[What-if results summary table]
|
||||
|
||||
Deploy these resources? (Yes/No)
|
||||
```
|
||||
|
||||
Proceed to Step 4 when the user confirms. **Do not proceed to deployment without the preview diagram.**
|
||||
|
||||
### Step 4: Actual Deployment
|
||||
|
||||
Execute only when the user has reviewed the preview diagram and What-if results and approved the deployment.
|
||||
**Use the same parameter passing method used in What-if.**
|
||||
|
||||
```powershell
|
||||
$deployName = "deploy-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
|
||||
|
||||
# Method 1: Use .bicepparam
|
||||
az deployment group create `
|
||||
--resource-group "<RG_NAME>" `
|
||||
--parameters main.bicepparam `
|
||||
--name $deployName `
|
||||
2>&1 | Tee-Object -FilePath deployment.log
|
||||
|
||||
# Method 2: Use JSON parameter file
|
||||
az deployment group create `
|
||||
--resource-group "<RG_NAME>" `
|
||||
--template-file main.bicep `
|
||||
--parameters main.parameters.json `
|
||||
--name $deployName `
|
||||
2>&1 | Tee-Object -FilePath deployment.log
|
||||
```
|
||||
|
||||
Periodically monitor progress during deployment:
|
||||
```powershell
|
||||
az deployment group show `
|
||||
--resource-group "<RG_NAME>" `
|
||||
--name "<DEPLOYMENT_NAME>" `
|
||||
--query "{status:properties.provisioningState, duration:properties.duration}" `
|
||||
-o table
|
||||
```
|
||||
|
||||
### Handling Deployment Failures
|
||||
|
||||
When deployment fails, some resources may remain in a 'Failed' state. Redeploying in this state causes errors like `AccountIsNotSucceeded`.
|
||||
|
||||
**⚠️ Resource deletion is a destructive command. Always explain the situation to the user and obtain approval before executing.**
|
||||
|
||||
```
|
||||
[Resource name] failed during deployment.
|
||||
To redeploy, the failed resources must be deleted first.
|
||||
|
||||
Delete and redeploy? (Yes/No)
|
||||
```
|
||||
|
||||
Delete failed resources and redeploy once the user approves.
|
||||
|
||||
**🔹 Handling Soft-deleted Resources (Prevent Redeployment Blocking):**
|
||||
|
||||
When a resource group is deleted after a failed deployment, Cognitive Services (Foundry), Key Vault, etc. remain in a **soft-delete state**.
|
||||
Redeploying with the same name causes `FlagMustBeSetForRestore`, `Conflict` errors.
|
||||
|
||||
**Always check before redeployment:**
|
||||
```powershell
|
||||
# Check soft-deleted Cognitive Services
|
||||
az cognitiveservices account list-deleted -o table
|
||||
|
||||
# Check soft-deleted Key Vault
|
||||
az keyvault list-deleted -o table
|
||||
```
|
||||
|
||||
**Resolution options (provide choices to the user):**
|
||||
```
|
||||
ask_user({
|
||||
question: "Soft-deleted resources from a previous deployment were found. How would you like to handle this?",
|
||||
choices: [
|
||||
"Purge and redeploy (Recommended) - Clean delete then create new",
|
||||
"Redeploy in restore mode - Recover existing resources"
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**Caution — Key Vault with `enablePurgeProtection: true`:**
|
||||
- Cannot be purged (must wait until retention period expires)
|
||||
- Cannot recreate with the same name
|
||||
- **Solution: Change the Key Vault name** and redeploy (e.g., add timestamp to `uniqueString()` seed)
|
||||
- Explain the situation to the user and guide them on the name change
|
||||
|
||||
### Step 5: Deployment Complete — Generate Diagram from Actual Resources and Report
|
||||
|
||||
Once deployment is complete, query the actually deployed resources and generate the final architecture diagram.
|
||||
|
||||
**Step 1: Query Deployed Resources**
|
||||
```powershell
|
||||
az resource list --resource-group "<RG_NAME>" --output json
|
||||
```
|
||||
|
||||
**Step 2: Generate Diagram from Actual Resources**
|
||||
|
||||
Extract resource names, types, SKUs, and endpoints from the query results and generate the final diagram using the built-in diagram engine.
|
||||
Be careful with file names to avoid overwriting previous diagrams:
|
||||
- `01_arch_diagram_draft.html` — Design draft (keep)
|
||||
- `02_arch_diagram_preview.html` — What-if preview (keep)
|
||||
- `03_arch_diagram_result.html` — Deployment result final version
|
||||
|
||||
Populate the diagram's services JSON with actual deployed resource information:
|
||||
- `name`: Actual resource name (e.g., `foundry-duru57kxgqzxs`)
|
||||
- `sku`: Actual SKU
|
||||
- `details`: Actual values such as endpoints, location, etc.
|
||||
|
||||
**Step 3: Report**
|
||||
```
|
||||
## Deployment Complete!
|
||||
|
||||
[Interactive architecture diagram — 03_arch_diagram_result.html]
|
||||
(Design draft: 01_arch_diagram_draft.html | What-if preview: 02_arch_diagram_preview.html)
|
||||
|
||||
Created resources (N items):
|
||||
[Dynamically extracted resource names, types, and endpoints from actual deployment results]
|
||||
|
||||
## Next Steps
|
||||
1. Verify resources in Azure Portal
|
||||
2. Check Private Endpoint connection status
|
||||
3. Additional configuration guidance if needed
|
||||
|
||||
## Cleanup Command (If Needed)
|
||||
az group delete --name <RG_NAME> --yes --no-wait
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Handling Architecture Change Requests After Deployment
|
||||
|
||||
**When the user requests resource additions/changes/deletions after deployment is complete, do NOT go directly to Bicep/deployment.**
|
||||
Always return to Phase 1 and update the architecture first.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. **Confirm user intent** — Ask first whether they want to add to the existing deployed architecture:
|
||||
```
|
||||
Would you like to add a VM to the currently deployed architecture?
|
||||
Current configuration: [Deployed services summary]
|
||||
```
|
||||
|
||||
2. **Return to Phase 1 — Apply Delta Confirmation Rule**
|
||||
- Use the existing deployment result (`03_arch_diagram_result.html`) as the current state baseline
|
||||
- Verify required fields for new services (SKU, networking, region availability, etc.)
|
||||
- Confirm undecided items via ask_user
|
||||
- Fact-check (MS Docs fetch + cross-validation)
|
||||
|
||||
3. **Generate Updated Architecture Diagram**
|
||||
- Combine existing deployed resources + new resources into `04_arch_diagram_update_draft.html`
|
||||
- Show to the user and get confirmation:
|
||||
```
|
||||
## Updated Architecture
|
||||
|
||||
[Interactive diagram — 04_arch_diagram_update_draft.html]
|
||||
(Previous deployment result: 03_arch_diagram_result.html)
|
||||
|
||||
**Changes:**
|
||||
- Added: [New services list]
|
||||
- Removed: [Removed services list] (if any)
|
||||
|
||||
Proceed with this configuration?
|
||||
```
|
||||
|
||||
4. **After confirmation, proceed through Phase 2 → 3 → 4 in order**
|
||||
- Incrementally add new resource modules to existing Bicep
|
||||
- Review → What-if → Deploy (incremental deployment)
|
||||
|
||||
**Never do the following:**
|
||||
- Jump directly to Bicep generation without updating the architecture diagram when a change is requested after deployment
|
||||
- Ignore the existing deployment state and create new resources in isolation
|
||||
- Proceed without confirming with the user whether to add to the existing architecture
|
||||
Reference in New Issue
Block a user