Edit

Implement per-app scaling for high-density hosting

Note

We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

You can scale your Azure App Service apps by scaling the App Service plan they run on. By default, the plan-level perSiteScaling property is false, and every app and deployment slot uses all available instances in the plan.

When perSiteScaling is true, each app and deployment slot can have its own siteConfig.numberOfWorkers limit. For example, a plan can have a configured capacity of 10 workers while an app has a configured limit of five workers. Each deployment slot has its own limit; configuring the production app doesn't also configure its slots.

Note

  • Per-app scaling is available only for Standard, Premium, Premium V2, Premium V3, and Isolated pricing tiers.
  • A per-app limit doesn't reduce the dedicated capacity configured for the App Service plan or its billing by itself.

Keep these values distinct:

  • Configured plan capacity: The plan's sku.capacity value.
  • Configured app or slot worker limit: The resource's siteConfig.numberOfWorkers value.
  • Observed active app instances: A point-in-time runtime observation. The actual count can't exceed the available plan workers. Plan scale-in can reduce this count below the configured app or slot limit.

The platform places an app on distinct available plan workers by using a best-effort approach. Placement is metric-independent.

Scenario Value semantics
Limit of 1 The app or slot can use at most one available plan worker. Choose this value only when single-worker placement is acceptable for the workload.
Limit greater than 1 The value caps how many distinct plan workers the app or slot can use. Actual active instances can be fewer.
Limit above available plan capacity Available plan workers cap the actual app or slot instances.
Plan scale-in The app or slot can run on fewer workers than its configured limit after plan workers are removed.

Per-app scaling is fixed, metric-independent placement within the plan's available workers. It doesn't respond to demand or change plan capacity. To change capacity based on demand, use automatic scaling or Azure Monitor autoscale.

Important

Zone redundancy distributes App Service plan instances; it doesn't create hidden app replicas. With per-app scaling, an app or slot limit of 1 permits placement on at most one plan instance and must not be treated as a simultaneous cross-zone replica. Limits of 2 or more permit placement on multiple distinct plan workers, but don't provide a public guarantee that those app instances span physical zones. For reliability design guidance, see Reliability in App Service.

Property model and prerequisites

Use a supported pricing tier, an account that can update the plan, app, and slot, and the current version of your chosen tool. The examples use Azure CLI 2.89.1 and Az PowerShell 16.2.0.

Scope Resource property Example
Plan feature properties.perSiteScaling true
Plan capacity sku.capacity 10
App desired limit properties.siteConfig.numberOfWorkers 5
Slot desired limit properties.siteConfig.numberOfWorkers 2
App or slot configuration GET response properties.numberOfWorkers 5 or 2

In Azure CLI, similarly named options have different scopes: az appservice plan ... --number-of-workers sets plan capacity, while az webapp config set ... --number-of-workers sets the app or slot limit.

Configure per-app scaling

Use the tab for your preferred tool. Replace placeholder names and locations before running a command or deploying a template.

Choose either the create step or the update step for the plan. The update step changes only perSiteScaling; it doesn't change the existing plan capacity.

resourceGroup='<resource-group-name>'
planName='<app-service-plan-name>'
appName='<app-name>'
slotName='staging'
location='westus3'

# Create a plan with capacity 10 and per-app scaling.
az appservice plan create \
    --resource-group $resourceGroup \
    --name $planName \
    --location $location \
    --sku P1V3 \
    --number-of-workers 10 \
    --per-site-scaling

# Or enable per-app scaling on an existing plan without changing its capacity.
az appservice plan update \
    --resource-group $resourceGroup \
    --name $planName \
    --set properties.perSiteScaling=true

# Configure the production app and its staging slot independently.
az webapp config set \
    --resource-group $resourceGroup \
    --name $appName \
    --number-of-workers 5

az webapp config set \
    --resource-group $resourceGroup \
    --name $appName \
    --slot $slotName \
    --number-of-workers 2

Here, the plan --number-of-workers 10 is capacity. The web app configuration option with the same name is the desired app or slot limit. Inspect the configured values:

az appservice plan show \
    --resource-group $resourceGroup \
    --name $planName \
    --query "{planCapacity:sku.capacity, perSiteScaling:perSiteScaling}"

az webapp config show \
    --resource-group $resourceGroup \
    --name $appName \
    --query "{appWorkerLimit:numberOfWorkers}"

az webapp config show \
    --resource-group $resourceGroup \
    --name $appName \
    --slot $slotName \
    --query "{slotWorkerLimit:numberOfWorkers}"

For command details, see az appservice plan and az webapp config.

Verify the configuration

Check each configured value after a change or deployment.

Value Expected example Where to verify
Plan feature true Plan response properties.perSiteScaling
Plan capacity 10 Plan response sku.capacity
Production app desired limit 5 Production config/web response properties.numberOfWorkers
Staging slot desired limit 2 Slot config/web response properties.numberOfWorkers

These values are configuration, not observed active instance counts. Runtime placement remains best effort and is bounded by available plan workers. Before combining per-app scaling with zone redundancy, review the plan capacity and each app or slot limit in Set zone redundancy for an existing App Service plan.

Configure high-density hosting for your scenario

Per-app scaling is available in both global Azure regions and App Service Environments. Choose app and slot limits according to workload capacity and reliability requirements rather than applying one limit to every workload.

For a high-density hosting scenario:

  1. Designate an App Service plan as the high-density plan and scale it out to the desired capacity.

  2. Set the PerSiteScaling flag to true on the App Service plan.

  3. Set each app and deployment slot's numberOfWorkers limit based on its needs.

    • A limit of 1 provides the highest density, but use it only for workloads where placement on at most one plan worker is acceptable.
    • Use a limit of 2 or more when the workload should be eligible for placement on multiple distinct plan workers, subject to available plan capacity.

  4. Review limits independently as workload requirements change. For example, a higher-use app can use a limit of 3 for more processing capacity, while another app can use 1 when single-worker placement is appropriate.

Related content

  • Last updated on