From fa922ced320901a6811a4628ef19b24d85532076 Mon Sep 17 00:00:00 2001 From: Harsh-Microsoft Date: Wed, 11 Mar 2026 16:33:11 +0530 Subject: [PATCH 1/2] Update VM size defaults and enhance troubleshooting documentation for the same --- docs/CustomizingAzdParameters.md | 1 + docs/TroubleShootingSteps.md | 4 ++-- infra/main.bicep | 2 +- infra/main.json | 6 +++--- infra/main.waf.parameters.json | 7 +++++-- infra/modules/virtualNetwork.bicep | 10 ++++++---- 6 files changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/CustomizingAzdParameters.md b/docs/CustomizingAzdParameters.md index c2faeae7..4c54bbe9 100644 --- a/docs/CustomizingAzdParameters.md +++ b/docs/CustomizingAzdParameters.md @@ -22,6 +22,7 @@ By default this template will use the environment name as the prefix to prevent | `AZURE_LOCATION` | string | `eastus` | Sets the primary Azure region for resource deployment. | | `AZURE_ENV_LOG_ANALYTICS_WORKSPACE_ID` | string | Guide to get your [Existing Workspace ID](/docs/re-use-log-analytics.md) | Reuses an existing Log Analytics Workspace instead of provisioning a new one. | | `AZURE_EXISTING_AI_PROJECT_RESOURCE_ID` | string | `` | Reuses an existing AIFoundry and AIFoundryProject instead of creating a new one. | +| `AZURE_ENV_VM_SIZE` | string | `Standard_D2s_v5` | Overrides the jumpbox VM size (private networking only). Default: `Standard_D2s_v5`. | ## How to Set a Parameter diff --git a/docs/TroubleShootingSteps.md b/docs/TroubleShootingSteps.md index 974b77b0..69c90fd8 100644 --- a/docs/TroubleShootingSteps.md +++ b/docs/TroubleShootingSteps.md @@ -61,7 +61,7 @@ Use these as quick reference guides to unblock your deployments. | **ServiceQuotaExceeded** | Free tier service quota limit reached for Azure AI Search | This error occurs when you attempt to deploy an Azure AI Search service but have already reached the **free tier quota limit** for your subscription. Each Azure subscription is limited to **one free tier Search service**.

**Example error message:**
`ServiceQuotaExceeded: Operation would exceed 'free' tier service quota. You are using 1 out of 1 'free' tier service quota.`

**Common causes:**

**Resolution:**

**Reference:**
| | **InsufficientQuota** | Not enough quota available in subscription | | | **MaxNumberOfRegionalEnvironmentsInSubExceeded** | Maximum Container App Environments limit reached for region |This error occurs when you attempt to create more **Azure Container App Environments** than the regional quota limit allows for your subscription. Each Azure region has a specific limit on the number of Container App Environments that can be created per subscription.

**Common Causes:**

**Resolution:**

**Reference:**
| -| **SkuNotAvailable** | Requested SKU not available in selected location or zone | You receive this error in the following scenarios:
| +| **SkuNotAvailable** | Requested SKU not available in selected location or zone | This error occurs when the resource SKU you've selected (such as VM size) isn't available for the target location or availability zone.

**In this deployment**, the jumpbox VM defaults to `Standard_D2s_v5`. While this size is available in 60+ regions, certain regions or zones may not support it.

**Resolution:**

**Reference:**
| | **Conflict - No available instances to satisfy this request** | Azure App Service has insufficient capacity in the region | This error occurs when Azure App Service doesn't have enough available compute instances in the selected region to provision or scale your app.

**Common Causes:**

**Resolution:**

**Reference:** [Azure App Service Plans](https://learn.microsoft.com/en-us/azure/app-service/overview-hosting-plans) | -------------------------------- @@ -120,7 +120,7 @@ Use these as quick reference guides to unblock your deployments. |-----------------|-------------|------------------| | **NetcfgSubnetRangeOutsideVnet** | Subnet IP range outside virtual network address space | | | **DisableExport_PublicNetworkAccessMustBeDisabled** | Public network access must be disabled when export is disabled | | -| **VMSizeIsNotPermittedToEnableAcceleratedNetworking** | VM size does not support accelerated networking | This error occurs when you attempt to enable accelerated networking on a VM size that does not support it.

**How to reproduce:**

**Resolution:**
| +| **VMSizeIsNotPermittedToEnableAcceleratedNetworking** | VM size does not support accelerated networking | This error occurs when you attempt to enable accelerated networking on a VM size that does not support it. This deployment's jumpbox VM **requires** accelerated networking.

**Default VM size:** `Standard_D2s_v5` — supports accelerated networking.

**How this error happens:**

**Resolution:**
| **NetworkSecurityGroupNotCompliantForAzureBastionSubnet** / **SecurityRuleParameterContainsUnsupportedValue** | NSG rules blocking required Azure Bastion ports | This error occurs when the Network Security Group (NSG) attached to `AzureBastionSubnet` explicitly denies inbound TCP ports 443 and/or 4443, which Azure Bastion requires for management and tunneling.

**How to reproduce:**

**Resolution:**
| | **RouteTableCannotBeAttachedForAzureBastionSubnet** | Route table attached to Azure Bastion subnet | This error occurs because Azure Bastion subnet (`AzureBastionSubnet`) has a platform restriction that prevents route tables from being attached.

**How to reproduce:**

**Resolution:**
| diff --git a/infra/main.bicep b/infra/main.bicep index fddd01bc..72c29e9d 100644 --- a/infra/main.bicep +++ b/infra/main.bicep @@ -240,7 +240,7 @@ module jumpboxVM 'br/public:avm/res/compute/virtual-machine:0.20.0' = if (enable enableTelemetry: enableTelemetry computerName: take(jumpboxVmName, 15) osType: 'Windows' - vmSize: empty(vmSize) ? 'Standard_DS2_v2' : vmSize + vmSize: empty(vmSize) ? 'Standard_D2s_v5' : vmSize adminUsername: empty(vmAdminUsername) ? 'JumpboxAdminUser' : vmAdminUsername adminPassword: empty(vmAdminPassword) ? 'JumpboxAdminP@ssw0rd1234!' : vmAdminPassword managedIdentities: { diff --git a/infra/main.json b/infra/main.json index 4a195a2b..c8c60343 100644 --- a/infra/main.json +++ b/infra/main.json @@ -6,7 +6,7 @@ "_generator": { "name": "bicep", "version": "0.40.2.10011", - "templateHash": "4821257159531769907" + "templateHash": "12321899448461321231" }, "name": "Content Processing Solution Accelerator", "description": "Bicep template to deploy the Content Processing Solution Accelerator with AVM compliance." @@ -4928,7 +4928,7 @@ "osType": { "value": "Windows" }, - "vmSize": "[if(empty(parameters('vmSize')), createObject('value', 'Standard_DS2_v2'), createObject('value', parameters('vmSize')))]", + "vmSize": "[if(empty(parameters('vmSize')), createObject('value', 'Standard_D2s_v5'), createObject('value', parameters('vmSize')))]", "adminUsername": "[if(empty(parameters('vmAdminUsername')), createObject('value', 'JumpboxAdminUser'), createObject('value', parameters('vmAdminUsername')))]", "adminPassword": "[if(empty(parameters('vmAdminPassword')), createObject('value', 'JumpboxAdminP@ssw0rd1234!'), createObject('value', parameters('vmAdminPassword')))]", "managedIdentities": { @@ -40925,9 +40925,9 @@ "dependsOn": [ "avmContainerApp", "avmManagedIdentity", - "[format('avmPrivateDnsZones[{0}]', variables('dnsZoneIndex').openAI)]", "[format('avmPrivateDnsZones[{0}]', variables('dnsZoneIndex').cognitiveServices)]", "[format('avmPrivateDnsZones[{0}]', variables('dnsZoneIndex').aiServices)]", + "[format('avmPrivateDnsZones[{0}]', variables('dnsZoneIndex').openAI)]", "[format('avmPrivateDnsZones[{0}]', variables('dnsZoneIndex').contentUnderstanding)]", "logAnalyticsWorkspace", "virtualNetwork" diff --git a/infra/main.waf.parameters.json b/infra/main.waf.parameters.json index 4964710c..f98c56ce 100644 --- a/infra/main.waf.parameters.json +++ b/infra/main.waf.parameters.json @@ -41,12 +41,15 @@ "enableScalability": { "value": true }, - "virtualMachineAdminUsername": { + "vmAdminUsername": { "value": "${AZURE_ENV_VM_ADMIN_USERNAME}" }, - "virtualMachineAdminPassword": { + "vmAdminPassword": { "value": "${AZURE_ENV_VM_ADMIN_PASSWORD}" }, + "vmSize": { + "value": "${AZURE_ENV_VM_SIZE}" + }, "publicContainerImageEndpoint": { "value": "${AZURE_ENV_CONTAINER_REGISTRY_ENDPOINT}" }, diff --git a/infra/modules/virtualNetwork.bicep b/infra/modules/virtualNetwork.bicep index 575cdfa6..8bc399c1 100644 --- a/infra/modules/virtualNetwork.bicep +++ b/infra/modules/virtualNetwork.bicep @@ -212,10 +212,12 @@ param resourceSuffix string // VM Size Notes: // 1 B-series VMs (like Standard_B2ms) do not support accelerated networking. -// 2 Pick a VM size that does support accelerated networking (the usual jump-box candidates): -// Standard_DS2_v2 (2 vCPU, 7 GiB RAM, Premium SSD) // The most broadly available (it’s a legacy SKU supported in virtually every region). -// Standard_D2s_v3 (2 vCPU, 8 GiB RAM, Premium SSD) // next most common -// Standard_D2s_v4 (2 vCPU, 8 GiB RAM, Premium SSD) // Newest, so fewer regions availabl +// 2 Pick a VM size that supports accelerated networking + Premium SSD (the usual jump-box candidates): +// Standard_D2s_v5 (2 vCPU, 8 GiB RAM, Premium SSD/v2/Ultra) // DEFAULT - current-gen Intel, broad regional availability. +// Standard_D2as_v5 (2 vCPU, 8 GiB RAM, Premium SSD/Ultra) // AMD alternative, typically ~15% cheaper. +// Standard_D2s_v4 (2 vCPU, 8 GiB RAM, Premium SSD) // Previous gen, also broadly available. +// Standard_DS2_v2 (2 vCPU, 7 GiB RAM, Premium SSD) // Legacy SKU, being retired from some regions - avoid for new deployments. +// 3 A-series (Av2) is NOT suitable: no Premium SSD support, no accelerated networking. // Subnet Classless Inter-Doman Routing (CIDR) Sizing Reference Table (Best Practices) // | CIDR | # of Addresses | # of /24s | Notes | From de15e59412b61cd300f87705957c60157463b821 Mon Sep 17 00:00:00 2001 From: Harsh-Microsoft Date: Fri, 13 Mar 2026 12:52:52 +0530 Subject: [PATCH 2/2] Update troubleshooting steps for SKU availability errors --- docs/TroubleShootingSteps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TroubleShootingSteps.md b/docs/TroubleShootingSteps.md index 69c90fd8..035da3af 100644 --- a/docs/TroubleShootingSteps.md +++ b/docs/TroubleShootingSteps.md @@ -61,7 +61,7 @@ Use these as quick reference guides to unblock your deployments. | **ServiceQuotaExceeded** | Free tier service quota limit reached for Azure AI Search | This error occurs when you attempt to deploy an Azure AI Search service but have already reached the **free tier quota limit** for your subscription. Each Azure subscription is limited to **one free tier Search service**.

**Example error message:**
`ServiceQuotaExceeded: Operation would exceed 'free' tier service quota. You are using 1 out of 1 'free' tier service quota.`

**Common causes:**
  • Already have a free tier Azure AI Search service in the subscription
  • Previous deployment created a free tier Search service that wasn't deleted
  • Attempting to deploy multiple environments with free tier Search services

**Resolution:**
  • **Option 1: Delete existing free tier Search service:**
    `az search service list --query "[?sku.name=='free']" -o table`
    `az search service delete --name --resource-group --yes`
  • **Option 2: Upgrade to a paid SKU:**
    Modify your Bicep/ARM template to use `basic`, `standard`, or higher SKU instead of `free`
  • **Option 3: Use existing Search service:**
    Reference the existing free tier Search service in your deployment instead of creating a new one
  • **Request quota increase:**
    Submit a support request with issue type 'Service and subscription limits (quota)' and quota type 'Search' via [Azure Quota Request](https://aka.ms/AddQuotaSubscription)

**Reference:**
  • [Azure AI Search service limits](https://learn.microsoft.com/en-us/azure/search/search-limits-quotas-capacity)
  • [Azure AI Search pricing tiers](https://learn.microsoft.com/en-us/azure/search/search-sku-tier)
| | **InsufficientQuota** | Not enough quota available in subscription |
  • Check if you have sufficient quota available in your subscription before deployment
  • To verify, refer to the [quota_check](../docs/quota_check.md) file for details
| | **MaxNumberOfRegionalEnvironmentsInSubExceeded** | Maximum Container App Environments limit reached for region |This error occurs when you attempt to create more **Azure Container App Environments** than the regional quota limit allows for your subscription. Each Azure region has a specific limit on the number of Container App Environments that can be created per subscription.

**Common Causes:**
  • Deploying to regions with low quota limits (e.g., Sweden Central allows only 1 environment)
  • Multiple deployments without cleaning up previous environments
  • Exceeding the standard limit of 15 environments in most major regions

**Resolution:**
  • **Delete unused environments** in the target region, OR
  • **Deploy to a different region** with available capacity, OR
  • **Request quota increase** via [Azure Support](https://go.microsoft.com/fwlink/?linkid=2208872)

**Reference:**
  • [Azure Container Apps quotas](https://learn.microsoft.com/en-us/azure/container-apps/quotas)
  • [Azure subscription and service limits](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits)
| -| **SkuNotAvailable** | Requested SKU not available in selected location or zone | This error occurs when the resource SKU you've selected (such as VM size) isn't available for the target location or availability zone.

**In this deployment**, the jumpbox VM defaults to `Standard_D2s_v5`. While this size is available in 60+ regions, certain regions or zones may not support it.

**Resolution:**
  • **Check SKU availability** for your target region:
    `az vm list-skus --location --size Standard_D2s --output table`
  • **Override the VM size** if the default isn't available in your region:
    `azd env set AZURE_ENV_VM_SIZE Standard_D2s_v4`
  • **Recommended alternatives** (all support accelerated networking + Premium SSD):
    - `Standard_D2s_v4` — previous gen, identical pricing
    - `Standard_D2as_v5` — AMD-based, similar pricing
    - `Standard_D2s_v3` — older gen, widely available
  • **Avoid A-series VMs** (e.g., `Standard_A2m_v2`) — they do not support accelerated networking or Premium SSD, which are required by this deployment

**Reference:**
  • [Resolve errors for SKU not available](https://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/error-sku-not-available)
  • [Azure VM sizes - Dsv5 series](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/general-purpose/dsv5-series)
| +| **SkuNotAvailable** | Requested SKU not available in selected location or zone | This error occurs when the resource SKU you've selected (such as VM size) isn't available for the target location or availability zone.

**In this deployment**, the jumpbox VM defaults to `Standard_D2s_v5`. While this size is available in most regions, certain regions or zones may not support it.

**Resolution:**
  • **Check SKU availability** for your target region:
    `az vm list-skus --location --size Standard_D2s --output table`
  • **Override the VM size** if the default isn't available in your region:
    `azd env set AZURE_ENV_VM_SIZE Standard_D2s_v4`
  • **Recommended alternatives** (all support accelerated networking + Premium SSD):
    - `Standard_D2s_v4` — previous gen, identical pricing
    - `Standard_D2as_v5` — AMD-based, similar pricing
    - `Standard_D2s_v3` — older gen, widely available
  • **Avoid A-series VMs** (e.g., `Standard_A2m_v2`) — they do not support accelerated networking or Premium SSD, which are required by this deployment

**Reference:**
  • [Resolve errors for SKU not available](https://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/error-sku-not-available)
  • [Azure VM sizes - Dsv5 series](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/general-purpose/dsv5-series)
| | **Conflict - No available instances to satisfy this request** | Azure App Service has insufficient capacity in the region | This error occurs when Azure App Service doesn't have enough available compute instances in the selected region to provision or scale your app.

**Common Causes:**
  • High demand in the selected region (e.g., East US, West Europe)
  • Specific SKUs experiencing capacity constraints (Free, Shared, or certain Premium tiers)
  • Multiple rapid deployments in the same region

**Resolution:**
  • **Wait and Retry** (15-30 minutes): `azd up`
  • **Deploy to a New Resource Group** (Recommended for urgent cases):
    ```
    azd down --force --purge
    azd up
    ```
  • **Try a Different Region:**
    Update region in `main.bicep` or `azure.yaml` to a less congested region (e.g., `westus2`, `centralus`, `northeurope`)
  • **Use a Different SKU/Tier:**
    If using Free/Shared tier, upgrade to Basic or Standard
    Check SKU availability: `az appservice list-locations --sku `

**Reference:** [Azure App Service Plans](https://learn.microsoft.com/en-us/azure/app-service/overview-hosting-plans) | --------------------------------