Web App for Containers¶

Web App for Containers is the App Service hosting model that runs a custom Docker container instead of a built-in runtime stack. It gives you full control over the OS, runtime, dependencies, and configuration while App Service manages the underlying infrastructure, scaling, and platform integration.

Use Web App for Containers when:

• Your app requires a specific runtime version, native library, or OS package not available in the built-in stacks.
• You want to standardize deployments around a container image across environments.
• You are migrating a containerized workload from another platform to App Service.

Main Content¶

Linux vs Windows Container Hosting¶

App Service supports custom containers on both Linux and Windows. The two hosting paths differ in capabilities and recommended patterns.

Container Lifecycle on App Service¶

Deploying a containerized app to App Service follows a consistent flow regardless of language or registry.

Portal view: Deployment Center — Containers tab¶

The Containers (new) tab exposes the runtime contract that App Service must satisfy to start a containerized workload. Columns such as Source, Image, Tag, and Port map directly to the image-pull and startup phases: the platform must fetch the selected image, launch it with the configured port, and then watch logs and HTTP reachability to decide whether startup succeeded. The Add action and sidecar-focused table also show that container lifecycle on App Service is not just about one image, but about coordinating the main app container and any companion containers inside the same app boundary.

flowchart TD
    A[Write Dockerfile] --> B[Build image locally]
    B --> C[Push image to registry]
    C --> D[Create or update Web App]
    D --> E[Configure container image and registry]
    E --> F[App Service pulls image on startup]
    F --> G[Platform evaluates startup HTTP reachability]
    G --> H{Health check passes?}
    H -->|Yes| I[App is Running]
    H -->|No| J[Startup failure — check PORT/WEBSITES_PORT, binding, and logs]

Each stage has a corresponding verification step:

Verify container configuration and running state:

az webapp config container show \
  --name $APP_NAME \
  --resource-group $RG \
  --output table

Name                                 SlotSetting    Value
-----------------------------------  -------------  ---------------------------------------------------
WEBSITES_ENABLE_APP_SERVICE_STORAGE  False          false
DOCKER_REGISTRY_SERVER_URL           False          https://<registry-name>.azurecr.io
DOCKER_CUSTOM_IMAGE_NAME                            DOCKER|<registry-name>.azurecr.io/flask-test:v1

az webapp show \
  --name $APP_NAME \
  --resource-group $RG \
  --query "{name:name, state:state, defaultHostName:defaultHostName, linuxFxVersion:siteConfig.linuxFxVersion}" \
  --output yaml

defaultHostName: <app-name>.azurewebsites.net
linuxFxVersion: DOCKER|<registry-name>.azurecr.io/flask-test:v1
name: <app-name>
state: Running

Registry Authentication Patterns¶

App Service supports three registry authentication patterns. Choose based on your registry type and security requirements.

flowchart TD
    Q1{Registry type?} -->|Azure Container Registry| Q2{Production workload?}
    Q1 -->|Docker Hub or other public| A2[No credentials needed\nSet image name only]
    Q1 -->|Private non-ACR registry| A3[Store credentials\nDOCKER_REGISTRY_SERVER_URL\nDOCKER_REGISTRY_SERVER_USERNAME\nDOCKER_REGISTRY_SERVER_PASSWORD]

    Q2 -->|Yes| A1[Managed identity\nacrUseManagedIdentityCreds: true]
    Q2 -->|No / Dev| A4[Admin credentials\ndocker-registry-server-user/password]

ACR with Managed Identity (Recommended)¶

Managed identity eliminates stored credentials and is the recommended pattern for ACR.

az webapp identity assign \
  --name $APP_NAME \
  --resource-group $RG

principalId: <object-id>
tenantId: <tenant-id>
type: SystemAssigned
userAssignedIdentities: null

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --scope $REGISTRY_RESOURCE_ID \
  --role "AcrPull"

roleDefinitionName: AcrPull
principalType: ServicePrincipal
scope: /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ContainerRegistry/registries/<registry-name>

az webapp config set \
  --name $APP_NAME \
  --resource-group $RG \
  --generic-configurations '{"acrUseManagedIdentityCreds": true}'

Verify managed identity is active:

az webapp config show \
  --name $APP_NAME \
  --resource-group $RG \
  --query "acrUseManagedIdentityCreds" \
  --output tsv

true

Private Non-ACR Registry (Credentials)¶

For Docker Hub private repositories or any non-ACR private registry, supply credentials:

az webapp config container set \
  --name $APP_NAME \
  --resource-group $RG \
  --container-image-name $IMAGE_NAME \
  --docker-registry-server-url $REGISTRY_URL \
  --docker-registry-server-user $REGISTRY_USER \
  --docker-registry-server-password $REGISTRY_PASSWORD

Network-Protected Registry¶

To pull from a registry inside a virtual network or behind a private endpoint, enable VNet image pull:

az webapp config set \
  --name $APP_NAME \
  --resource-group $RG \
  --generic-configurations '{"vnetImagePullEnabled": true}'

Multi-Container and Sidecar Pattern¶

App Service supports adding up to nine sidecar containers alongside the main application container. Sidecars run in the same App Service plan and share the network namespace with the main container.

flowchart TD
    subgraph Plan ["App Service Plan"]
        subgraph App ["Web App"]
            M[Main container\nYour application]
            S1[Sidecar 1\nOpenTelemetry collector]
            S2[Sidecar 2\nLog shipper]
        end
    end
    M -- shared network --> S1
    M -- shared network --> S2
    S1 --> OBS[Observability backend]
    S2 --> LOG[Log aggregator]

Use sidecars for:

• Observability agents (OpenTelemetry, Datadog, Dynatrace)
• Log shippers (Fluent Bit, Logstash)
• Configuration or secrets sync sidecars

Configure a Sidecar¶

az webapp sitecontainers create \
  --name $APP_NAME \
  --resource-group $RG \
  --container-name $SIDECAR_NAME \
  --image $SIDECAR_IMAGE \
  --is-main false \
  --target-port 4317

{
  "authType": "Anonymous",
  "image": "otel/opentelemetry-collector:latest",
  "isMain": false,
  "name": "otel-collector",
  "targetPort": "4317",
  "type": "Microsoft.Web/sites/sitecontainer"
}

Port Configuration and Health Checks¶

App Service sends startup HTTP checks to verify that the app became reachable. For Linux custom containers, port handling is more nuanced than a simple WEBSITES_PORT probe rule: the app should usually bind to the runtime-injected PORT value, and WEBSITES_PORT is one of the settings that can influence platform behavior. See Container HTTP Pings — Lab Guide for experimental evidence on Linux port behavior.

If your custom container uses a non-default HTTP port, configure WEBSITES_PORT and make sure the process actually listens on the value exposed through PORT:

az webapp config appsettings set \
  --name $APP_NAME \
  --resource-group $RG \
  --settings WEBSITES_PORT=8080

- name: WEBSITES_PORT
  slotSetting: false
  value: '8080'

Security Considerations¶

See Also¶

• Container Deployment — Operations Guide
• Node.js Custom Container Recipe
• Python Custom Container Recipe
• Container Did Not Respond to HTTP Pings — Playbook
• Windows Container Health Probes — Playbook
• Container HTTP Pings — Lab Guide

Sources¶

• Run a custom container in Azure App Service — Microsoft Learn
• Configure a custom container for App Service — Microsoft Learn
• Configure a sidecar container for a custom container app — Microsoft Learn