1# Azure Context (Subscription & Location)
2 
3Detect and confirm Azure subscription and location before generating artifacts. Run region capacity check for customer selected location
4 
5---
6 
7## Step 1: Check for Existing AZD Environment
8 
9If the project already uses AZD, check for an existing environment with values already set:
10 
11```bash
12azd env list
13```
14 
15**If an environment is selected** (marked with `*`), check its values:
16 
17```bash
18azd env get-values
19```
20 
21If `AZURE_SUBSCRIPTION_ID` and `AZURE_LOCATION` are already set, use `ask_user` to confirm reuse:
22 
23```
24Question: "I found an existing AZD environment with these settings. Would you like to continue with them?"
25 
26  Environment: {env-name}
27  Subscription: {subscription-name} ({subscription-id})
28  Location: {location}
29 
30Choices: [
31  "Yes, use these settings (Recommended)",
32  "No, let me choose different settings"
33]
34```
35 
36If user confirms → skip to **Record in Plan**. Otherwise → continue to Step 2.
37 
38---
39 
40## Step 2: Detect Defaults
41 
42Check for user-configured defaults:
43 
44```bash
45azd config get defaults
46```
47 
48Returns JSON with any configured defaults:
49```json
50{
51  "subscription": "25fd0362-aa79-488b-b37b-d6e892009fdf",
52  "location": "eastus2"
53}
54```
55 
56Use these as **recommended** values if present.
57 
58If no defaults, fall back to az CLI:
59```bash
60az account show --query "{name:name, id:id}" -o json
61```
62 
63## Step 3: Confirm Subscription with User
64 
65Use `ask_user` with the **actual subscription name and ID**:
66 
67✅ **Correct:**
68```
69Question: "Which Azure subscription would you like to deploy to?"
70Choices: [
71  "Use current: jongdevdiv (25fd0362-aa79-488b-b37b-d6e892009fdf) (Recommended)",
72  "Let me specify a different subscription"
73]
74```
75 
76❌ **Wrong** (never do this):
77```
78Choices: [
79  "Use default subscription",  // ← Does not show actual name
80  "Let me specify"
81]
82```
83 
84If user wants a different subscription:
85```bash
86az account list --output table
87```
88 
89---
90 
91## Step 4: Confirm Location with User
92 
931. Consult [Region Availability](region-availability.md) for services with limited availability
942. Present only regions that support ALL selected services
953. Use `ask_user`:
964. After customer selected region, do provisioning limit check, consult [Resource Limits and Quotas](resources-limits-quotas.md). For this also invoke azure-quotas
97 
98```
99Question: "Which Azure region would you like to deploy to?"
100Based on your architecture ({list services}), these regions support all services:
101Choices: [
102  "eastus2 (Recommended)",
103  "westus2",
104  "westeurope"
105]
106```
107 
108⚠️ Do NOT include regions that don't support all services — deployment will fail.
109 
110---
111## Step 5: Check Resource Provisioning Limits
112 
1131. **List resource types and quantities** that will be deployed from the planned architecture (e.g., 2x Standard D4s v3 VMs, 1x VNet, 3x Storage Accounts)
114 
1152. **Determine limits for each resource type** using the user-selected subscription and region:
116   - Reference [./resources-limits-quotas.md](./resources-limits-quotas.md) for documented limits
117   - Use **azure-quotas** skill to check current quotas and usage for the selected subscription and region
118   - If `az quota list` returns `BadRequest` error, the resource provider doesn't support quota API
119 
1203. **For resources that don't support quota API** (e.g., Microsoft.DocumentDB, or when you get `BadRequest` from `az quota list`):
121   - Invoke **azure-resource-lookup** skill to count existing deployments of that resource type in the selected subscription and region
122   - Use the count to calculate: `Total After Deployment = Current Count + Planned Deployment`
123   - Reference [Azure service limits documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits) for the limit value
124   - Document in provisioning checklist as "Fetched from: azure-resource-lookup + Official docs"
125 
1264. **Validate deployment capacity**:
127   - Compare planned deployment quantities against available quota (limit - current usage)
128   - If **insufficient capacity** is found, notify the customer and return to **Step 4** to select a different region
129   - Use **azure-quotas** skill to compare capacity across multiple regions and recommend alternatives
130 
131## Record in Plan
132 
133After confirmation, record in `.azure/deployment-plan.md`:
134 
135```markdown
136## Azure Context
137- **Subscription**: jongdevdiv (25fd0362-aa79-488b-b37b-d6e892009fdf)
138- **Location**: eastus2
139```
140 
141---
142 
143## Step 6: Apply to AZD Environment
144 
145> **⛔ CRITICAL for Aspire and azd projects**: After user confirms subscription and location, you **MUST** set these values in the azd environment immediately after running `azd init` or `azd env new`. Always use `--no-prompt` with these commands to prevent interactive prompts from blocking execution.
146>
147> **DO NOT** wait until validation or deployment. The Azure CLI and azd maintain separate configuration contexts.
148 
149**For Aspire projects using `azd init --from-code`:**
150 
151```bash
152# 1. Run azd init
153azd init --from-code -e <environment-name> --no-prompt
154 
155# 2. IMMEDIATELY set the user-confirmed subscription
156azd env set AZURE_SUBSCRIPTION_ID <subscription-id>
157 
158# 3. Set the location
159azd env set AZURE_LOCATION <location>
160 
161# 4. Verify
162azd env get-values
163```
164 
165**For non-Aspire projects using `azd env new`:**
166 
167```bash
168# 1. Create environment
169azd env new <environment-name> --no-prompt
170 
171# 2. IMMEDIATELY set the user-confirmed subscription
172azd env set AZURE_SUBSCRIPTION_ID <subscription-id>
173 
174# 3. Set the location
175azd env set AZURE_LOCATION <location>
176 
177# 4. Verify
178azd env get-values
179```
180 
181**Why this is critical:**
182- `az account show` returns the Azure CLI's default subscription
183- `azd` maintains its own configuration with potentially different defaults
184- If you don't set `AZURE_SUBSCRIPTION_ID` explicitly, azd will use its own default
185- This can result in deploying to the wrong subscription despite user confirmation
186