/azure-prepare

Azure Context (Subscription & Location)

Detect and confirm Azure subscription and location before generating artifacts. Run region capacity check for customer selected location

Step 1: Check for Existing AZD Environment

If the project already uses AZD, check for an existing environment with values already set:

azd env list

If an environment is selected (marked with *), check its values:

azd env get-values

If AZURE_SUBSCRIPTION_ID and AZURE_LOCATION are already set, use ask_user to confirm reuse:

Question: "I found an existing AZD environment with these settings. Would you like to continue with them?"

  Environment: {env-name}
  Subscription: {subscription-name} ({subscription-id})
  Location: {location}

Choices: [
  "Yes, use these settings (Recommended)",
  "No, let me choose different settings"
]

If user confirms → skip to Record in Plan. Otherwise → continue to Step 2.

Step 2: Detect Defaults

Check for user-configured defaults:

azd config get defaults

Returns JSON with any configured defaults:

{
  "subscription": "25fd0362-aa79-488b-b37b-d6e892009fdf",
  "location": "eastus2"
}

Use these as recommended values if present.

If no defaults, fall back to az CLI:

az account show --query "{name:name, id:id}" -o json

Step 3: Confirm Subscription with User

Use ask_user with the actual subscription name and ID:

✅ Correct:

Question: "Which Azure subscription would you like to deploy to?"
Choices: [
  "Use current: jongdevdiv (25fd0362-aa79-488b-b37b-d6e892009fdf) (Recommended)",
  "Let me specify a different subscription"
]

❌ Wrong (never do this):

Choices: [
  "Use default subscription",  // ← Does not show actual name
  "Let me specify"
]

If user wants a different subscription:

az account list --output table

Step 4: Confirm Location with User

1. Consult Region Availability for services with limited availability
2. Present only regions that support ALL selected services
3. Use ask_user:
4. After customer selected region, do provisioning limit check, consult Resource Limits and Quotas. For this also invoke azure-quotas

Question: "Which Azure region would you like to deploy to?"
Based on your architecture ({list services}), these regions support all services:
Choices: [
  "eastus2 (Recommended)",
  "westus2",
  "westeurope"
]

⚠️ Do NOT include regions that don't support all services — deployment will fail.

Step 5: Check Resource Provisioning Limits

1. 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)

2. Determine limits for each resource type using the user-selected subscription and region:

   • Reference ./resources-limits-quotas.md for documented limits
   • Use azure-quotas skill to check current quotas and usage for the selected subscription and region
   • If az quota list returns BadRequest error, the resource provider doesn't support quota API

3. For resources that don't support quota API (e.g., Microsoft.DocumentDB, or when you get BadRequest from az quota list):

   • Invoke azure-resource-lookup skill to count existing deployments of that resource type in the selected subscription and region
   • Use the count to calculate: Total After Deployment = Current Count + Planned Deployment
   • Reference Azure service limits documentation for the limit value
   • Document in provisioning checklist as "Fetched from: azure-resource-lookup + Official docs"

4. Validate deployment capacity:

   • Compare planned deployment quantities against available quota (limit - current usage)
   • If insufficient capacity is found, notify the customer and return to Step 4 to select a different region
   • Use azure-quotas skill to compare capacity across multiple regions and recommend alternatives

Record in Plan

After confirmation, record in .azure/deployment-plan.md:

## Azure Context
- **Subscription**: jongdevdiv (25fd0362-aa79-488b-b37b-d6e892009fdf)
- **Location**: eastus2

Step 6: Apply to AZD Environment

⛔ 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.

DO NOT wait until validation or deployment. The Azure CLI and azd maintain separate configuration contexts.

For Aspire projects using azd init --from-code:

# 1. Run azd init
azd init --from-code -e <environment-name> --no-prompt

# 2. IMMEDIATELY set the user-confirmed subscription
azd env set AZURE_SUBSCRIPTION_ID <subscription-id>

# 3. Set the location
azd env set AZURE_LOCATION <location>

# 4. Verify
azd env get-values

For non-Aspire projects using azd env new:

# 1. Create environment
azd env new <environment-name> --no-prompt

# 2. IMMEDIATELY set the user-confirmed subscription
azd env set AZURE_SUBSCRIPTION_ID <subscription-id>

# 3. Set the location
azd env set AZURE_LOCATION <location>

# 4. Verify
azd env get-values

Why this is critical:

• az account show returns the Azure CLI's default subscription
• azd maintains its own configuration with potentially different defaults
• If you don't set AZURE_SUBSCRIPTION_ID explicitly, azd will use its own default
• This can result in deploying to the wrong subscription despite user confirmation