Edit

Share via

Configure a custom container for Azure App Service

  • Article

This article shows you how to configure a custom container to run on Azure App Service.

This guide provides key concepts and instructions for containerization of Windows apps in App Service. New Azure App Service users should follow the custom container quickstart and tutorial first.

This guide provides key concepts and instructions for containerization of Linux apps in App Service. If are new to Azure App Service, follow the custom container quickstart and tutorial first. For sidecar containers (preview), see Tutorial: Configure a sidecar container for custom container in Azure App Service (preview).

Note

Service Principal is no longer supported for Windows container image pull authentication. The recommended way is to use Managed Identity for both Windows and Linux containers

Supported parent images

For your custom Windows image, you must choose the right parent image (base image) for the framework you want:

It takes some time to download a parent image during app start-up. However, you can reduce start-up time by using one of the following parent images that are already cached in Azure App Service:

Change the Docker image of a custom container

To change an existing custom container from the current Docker image to a new image, use the following command:

az webapp config container set --name <app-name> --resource-group <group-name> --docker-custom-image-name <docker-hub-repo>/<image>

Use an image from a private registry

To use an image from a private registry, such as Azure Container Registry, run the following command:

az webapp config container set --name <app-name> --resource-group <group-name> --docker-custom-image-name <image-name> --docker-registry-server-url <private-repo-url> --docker-registry-server-user <username> --docker-registry-server-password <password>

For <username> and <password>, supply the sign-in credentials for your private registry account.

Use managed identity to pull image from Azure Container Registry

Use the following steps to configure your web app to pull from Azure Container Registry (ACR) using managed identity. The steps use system-assigned managed identity, but you can use user-assigned managed identity as well.

  1. Enable the system-assigned managed identity for the web app by using the az webapp identity assign command:

    az webapp identity assign --resource-group <group-name> --name <app-name> --query principalId --output tsv

    Replace <app-name> with the name you used in the previous step. The output of the command (filtered by the --query and --output arguments) is the service principal ID of the assigned identity.

  2. Get the resource ID of your Azure Container Registry:

    az acr show --resource-group <group-name> --name <registry-name> --query id --output tsv

    Replace <registry-name> with the name of your registry. The output of the command (filtered by the --query and --output arguments) is the resource ID of the Azure Container Registry.

  3. Grant the managed identity permission to access the container registry:

    az role assignment create --assignee <principal-id> --scope <registry-resource-id> --role "AcrPull"

    Replace the following values:

    • <principal-id> with the service principal ID from the az webapp identity assign command
    • <registry-resource-id> with the ID of your container registry from the az acr show command

    For more information about these permissions, see What is Azure role-based access control.

  4. Configure your app to use the managed identity to pull from Azure Container Registry.

    az webapp config set --resource-group <group-name> --name <app-name> --generic-configurations '{"acrUseManagedIdentityCreds": true}'

    Replace the following values:

    • <app-name> with the name of your web app.

    Tip

    If you are using PowerShell console to run the commands, you need to escape the strings in the --generic-configurations argument in this and the next step. For example: --generic-configurations '{\"acrUseManagedIdentityCreds\": true'

  5. (Optional) If your app uses a user-assigned managed identity, make sure the identity is configured on the web app and then set the acrUserManagedIdentityID property to specify its client ID:

    az identity show --resource-group <group-name> --name <identity-name> --query clientId --output tsv

    Replace the <identity-name> of your user-assigned managed identity and use the output <client-id> to configure the user-assigned managed identity ID.

    az  webapp config set --resource-group <group-name> --name <app-name> --generic-configurations '{"acrUserManagedIdentityID": "<client-id>"}'

You're all set, and the web app now uses managed identity to pull from Azure Container Registry.

Use an image from a network protected registry

To connect and pull from a registry inside a virtual network or on-premises, your app must integrate with a virtual network (VNET). VNET integration is also needed for Azure Container Registry with private endpoint. When your network and DNS resolution is configured, you enable the routing of the image pull through the virtual network by configuring the vnetImagePullEnabled site setting:

az resource update --resource-group <group-name> --name <app-name> --resource-type "Microsoft.Web/sites" --set properties.vnetImagePullEnabled [true|false]

I don't see the updated container

If you change your Docker container settings to point to a new container, it might take a few minutes before the app serves HTTP requests from the new container. While the new container is being pulled and started, App Service continues to serve requests from the old container. Only when the new container is started and ready to receive requests does App Service start sending requests to it.

How container images are stored

The first time you run a custom Docker image in App Service, App Service does a docker pull and pulls all image layers. These layers are stored on disk, like if you were using Docker on-premises. Each time the app restarts, App Service does a docker pull, but only pulls layers that have changed. If there are no changes, App Service uses existing layers on the local disk.

If the app changes compute instances for any reason, such as scaling up and down the pricing tiers, App Service must pull down all layers again. The same is true if you scale out to add more instances. There are also rare cases where the app instances might change without a scale operation.

Configure port number

By default, App Service assumes your custom container is listening on port 80. If your container listens to a different port, set the WEBSITES_PORT app setting in your App Service app. You can set it via the Cloud Shell. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITES_PORT=8000

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"WEBSITES_PORT"="8000"}

App Service currently allows your container to expose only one port for HTTP requests.

Configure environment variables

Your custom container might use environment variables that need to be supplied externally. You can pass them in via the Cloud Shell. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings DB_HOST="myownserver.mysql.database.azure.com"

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"DB_HOST"="myownserver.mysql.database.azure.com"}

When your app runs, the App Service app settings are injected into the process as environment variables automatically. You can verify container environment variables with the URL https://<app-name>.scm.azurewebsites.net/Env.

If your app uses images from a private registry or from Docker Hub, credentials for accessing the repository are saved in environment variables: DOCKER_REGISTRY_SERVER_URL, DOCKER_REGISTRY_SERVER_USERNAME and DOCKER_REGISTRY_SERVER_PASSWORD. Because of security risks, none of these reserved variable names are exposed to the application.

For IIS or .NET Framework (4.0 or above) based containers, they're injected into System.ConfigurationManager as .NET app settings and connection strings automatically by App Service. For all other language or framework, they're provided as environment variables for the process, with one of the following corresponding prefixes:

  • APPSETTING_
  • SQLCONTR_
  • MYSQLCONTR_
  • SQLAZURECOSTR_
  • POSTGRESQLCONTR_
  • CUSTOMCONNSTR_

This method works both for single-container apps or multi-container apps, where the environment variables are specified in the docker-compose.yml file.

Use persistent shared storage

You can use the C:\home directory in your custom container file system to persist files across restarts and share them across instances. The C:\home directory is provided to enable your custom container to access persistent storage.

When persistent storage is disabled, then writes to the C:\home directory aren't persisted across app restarts or across multiple instances. When persistent storage is enabled, all writes to the C:\home directory are persisted and can be accessed by all instances of a scaled-out app. Additionally, any contents inside the C:\home directory of the container are overwritten by any existing files already present on the persistent storage when the container starts.

The only exception is the C:\home\LogFiles directory, which is used to store the container and application logs. This folder always persists upon app restarts if application logging is enabled with the File System option, independently of the persistent storage being enabled or disabled. In other words, enabling or disabling the persistent storage doesn't affect the application logging behavior.

By default, persistent storage is enabled on Windows custom containers. To disable it, set the WEBSITES_ENABLE_APP_SERVICE_STORAGE app setting value to false via the Cloud Shell. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITES_ENABLE_APP_SERVICE_STORAGE=false

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"WEBSITES_ENABLE_APP_SERVICE_STORAGE"=false}

You can use the /home directory in your custom container file system to persist files across restarts and share them across instances. The /home directory is provided to enable your custom container to access persistent storage. Saving data within /home contributes to the storage space quota included with your App Service Plan.

When persistent storage is disabled, then writes to the /home directory aren't persisted across app restarts or across multiple instances. When persistent storage is enabled, all writes to the /home directory are persisted and can be accessed by all instances of a scaled-out app. Additionally, any contents inside the /home directory of the container are overwritten by any existing files already present on the persistent storage when the container starts.

The only exception is the /home/LogFiles directory, which is used to store the container and application logs. This folder always persists upon app restarts if application logging is enabled with the File System option, independently of the persistent storage being enabled or disabled. In other words, enabling or disabling the persistent storage doesn't affect the application logging behavior.

It's recommended to write data to /home or a mounted Azure storage path. Data written outside these paths isn't persistent during restarts and is saved to platform-managed host disk space separate from the App Service Plans file storage quota.

By default, persistent storage is disabled on Linux custom containers. To enable it, set the WEBSITES_ENABLE_APP_SERVICE_STORAGE app setting value to true via the Cloud Shell. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITES_ENABLE_APP_SERVICE_STORAGE=true

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"WEBSITES_ENABLE_APP_SERVICE_STORAGE"=true}

Note

You can also configure your own persistent storage.

Detect HTTPS session

App Service terminates TLS/SSL at the front ends. That means that TLS/SSL requests never get to your app. You don't need to, and shouldn't implement any support for TLS/SSL into your app.

The front ends are located inside Azure data centers. If you use TLS/SSL with your app, your traffic across the Internet is always safely encrypted.

Customize ASP.NET machine key injection

During the container start, automatically generated keys are injected into the container as the machine keys for ASP.NET cryptographic routines. You can find these keys in your container by looking for the following environment variables: MACHINEKEY_Decryption, MACHINEKEY_DecryptionKey, MACHINEKEY_ValidationKey, MACHINEKEY_Validation.

The new keys at each restart might reset ASP.NET forms authentication and view state, if your app depends on them. To prevent the automatic regeneration of keys, set them manually as App Service app settings.

Connect to the container

You can connect to your Windows container directly for diagnostic tasks by navigating to https://<app-name>.scm.azurewebsites.net/ and choosing the SSH option. A direct SSH session with your container is established in which you can run commands inside your container.

  • It functions separately from the graphical browser above it, which only shows the files in your shared storage.
  • In a scaled-out app, the SSH session is connected to one of the container instances. You can select a different instance from the Instance dropdown in the top Kudu menu.
  • Any change you make to the container from within the SSH session doesn't persist when your app is restarted (except for changes in the shared storage), because it's not part of the Docker image. To persist your changes, such as registry settings and software installation, make them part of the Dockerfile.

Access diagnostic logs

App Service logs actions by the Docker host and activities from within the container. Logs from the Docker host (platform logs) are shipped by default, but application logs or web server logs from within the container need to be enabled manually. For more information, see Enable application logging and Enable web server logging.

There are several ways to access Docker logs:

In Azure portal

Docker logs are displayed in the portal, in the Container Settings page of your app. The logs are truncated, but you can download all the logs selecting Download.

From Kudu

Navigate to https://<app-name>.scm.azurewebsites.net/DebugConsole and select the LogFiles folder to see the individual log files. To download the entire LogFiles directory, select the "Download" icon to the left of the directory name. You can also access this folder using an FTP client.

In the SSH terminal, you can't access the C:\home\LogFiles folder by default because persistent shared storage isn't enabled. To enable this behavior in the console terminal, enable persistent shared storage.

If you try to download the Docker log that is currently in use by using an FTP client, you might get an error because of a file lock.

With the Kudu API

Navigate directly to https://<app-name>.scm.azurewebsites.net/api/logs/docker to see metadata for the Docker logs. You might see more than one log file listed, and the href property lets you download the log file directly.

To download all the logs together in one ZIP file, access https://<app-name>.scm.azurewebsites.net/api/logs/docker/zip.

Customize container memory

By default all Windows Containers deployed in Azure App Service have a memory limit configured. The following table lists the default settings per App Service Plan SKU.

App Service Plan SKU Default memory limit per app in MB
P1v3 1024
P1Mv3 1024
P2v3 1536
P2Mv3 1536
P3v3 2048
P3Mv3 2048
P4Mv3 2560
P5Mv3 3072

You can change this value by providing the WEBSITE_MEMORY_LIMIT_MB app setting via the Cloud Shell. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITE_MEMORY_LIMIT_MB=2000

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"WEBSITE_MEMORY_LIMIT_MB"=2000}

The value is defined in MB and must be less and equal to the total physical memory of the host. For example, in an App Service plan with 8 GB RAM, the cumulative total of WEBSITE_MEMORY_LIMIT_MB for all the apps must not exceed 8 GB. Information on how much memory is available for each pricing tier can be found in App Service pricing, in the Premium v3 service plan section.

Customize the number of compute cores

By default, a Windows container runs with all available cores for your chosen pricing tier. You might want to reduce the number of cores that your staging slot uses, for example. To reduce the number of cores used by a container, set the WEBSITE_CPU_CORES_LIMIT app setting to the preferred number of cores. You can set it via the Cloud Shell. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --slot staging --settings WEBSITE_CPU_CORES_LIMIT=1

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"WEBSITE_CPU_CORES_LIMIT"=1}

Note

Updating the app setting triggers automatic restart, causing minimal downtime. For a production app, consider swapping it into a staging slot, change the app setting in the staging slot, and then swap it back into production.

Verify your adjusted number by opening an SSH session from the portal or via the Kudu portal (https://<app-name>.scm.azurewebsites.net/webssh/host) and typing in the following commands using PowerShell. Each command outputs a number.

Get-ComputerInfo | ft CsNumberOfLogicalProcessors # Total number of enabled logical processors. Disabled processors are excluded.
Get-ComputerInfo | ft CsNumberOfProcessors # Number of physical processors.

The processors might be multicore or hyperthreading processors. Information on how many cores are available for each pricing tier can be found in App Service pricing, in the Premium v3 service plan section.

Customize health ping behavior

App Service considers a container to be successfully started when the container starts and responds to an HTTP ping. The health ping request contains the header User-Agent= "App Service Hyper-V Container Availability Check". If the container starts but doesn't respond pings after a certain amount of time, App Service logs an event in the Docker log, saying that the container didn't start.

If your application is resource-intensive, the container might not respond to the HTTP ping in time. To control the actions when HTTP pings fail, set the CONTAINER_AVAILABILITY_CHECK_MODE app setting. You can set it via the Cloud Shell. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings CONTAINER_AVAILABILITY_CHECK_MODE="ReportOnly"

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"CONTAINER_AVAILABILITY_CHECK_MODE"="ReportOnly"}

The following table shows the possible values:

Value Descriptions
Repair Restart the container after three consecutive availability checks
ReportOnly The default value. Don't restart the container but report in the Docker logs for the container after three consecutive availability checks.
Off Don't check for availability.

Support for Group Managed Service Accounts

Group Managed Service Accounts (gMSAs) are currently not supported in Windows containers in App Service.

Enable SSH

Secure Shell (SSH) is commonly used to execute administrative commands remotely from a command-line terminal. In order to enable the Azure portal SSH console feature with custom containers, the following steps are required:

  1. Create a standard sshd_config file with the following example contents and place it on the application project root directory:

    Port 			2222
ListenAddress 		0.0.0.0
LoginGraceTime 		180
X11Forwarding 		yes
Ciphers aes128-cbc,3des-cbc,aes256-cbc,aes128-ctr,aes192-ctr,aes256-ctr
MACs hmac-sha1,hmac-sha1-96
StrictModes 		yes
SyslogFacility 		DAEMON
PasswordAuthentication 	yes
PermitEmptyPasswords 	no
PermitRootLogin 	yes
Subsystem sftp internal-sftp

    Note

    This file configures OpenSSH and must include the following items in order to comply with the Azure portal SSH feature:

    • Port must be set to 2222.
    • Ciphers must include at least one item in this list: aes128-cbc,3des-cbc,aes256-cbc.
    • MACs must include at least one item in this list: hmac-sha1,hmac-sha1-96.

  2. Create an entrypoint script with the name entrypoint.sh (or change any existing entrypoint file) and add the command to start the SSH service, along with the application startup command. The following example demonstrates starting a Python application. Replace the last command according to the project language/stack:

    #!/bin/sh
set -e
service ssh start
exec gunicorn -w 4 -b 0.0.0.0:8000 app:app

  3. Add to the Dockerfile the following instructions according to the base image distribution. These instructions copy the new files, install OpenSSH server, set proper permissions and configure the custom entrypoint, and expose the ports required by the application and SSH server, respectively:

    COPY entrypoint.sh ./

# Start and enable SSH
RUN apt-get update \
    && apt-get install -y --no-install-recommends dialog \
    && apt-get install -y --no-install-recommends openssh-server \
    && echo "root:Docker!" | chpasswd \
    && chmod u+x ./entrypoint.sh
COPY sshd_config /etc/ssh/

EXPOSE 8000 2222

ENTRYPOINT [ "./entrypoint.sh" ]

    Note

    The root password must be exactly Docker! as it's used by App Service to let you access the SSH session with the container. This configuration doesn't allow external connections to the container. Port 2222 of the container is accessible only within the bridge network of a private virtual network and isn't accessible to an attacker on the internet.

  4. Rebuild and push the Docker image to the registry, and then test the Web App SSH feature on Azure portal.

Further troubleshooting information is available at the Azure App Service blog: Enabling SSH on Linux Web App for Containers

Access diagnostic logs

You can access the console logs generated from inside the container.

First, turn on container logging by running the following command:

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

Replace <app-name> and <resource-group-name> with the names appropriate for your web app.

Once container logging is turned on, run the following command to see the log stream:

az webapp log tail --name <app-name> --resource-group <resource-group-name>

If you don't see console logs immediately, check again in 30 seconds.

To stop log streaming at any time, type Ctrl+C.

You can also inspect the log files in a browser at https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Configure multi-container apps

Note

Sidecar containers (preview) will succeed multi-container apps in App Service. To get started, see Tutorial: Configure a sidecar container for custom container in Azure App Service (preview).

Use persistent storage in Docker Compose

Multi-container apps like WordPress need persistent storage to function properly. To enable it, your Docker Compose configuration must point to a storage location outside your container. Storage locations inside your container don't persist changes beyond app restart.

Enable persistent storage by setting the WEBSITES_ENABLE_APP_SERVICE_STORAGE app setting, using the az webapp config appsettings set command in Cloud Shell.

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITES_ENABLE_APP_SERVICE_STORAGE=TRUE

In your docker-compose.yml file, map the volumes option to ${WEBAPP_STORAGE_HOME}.

WEBAPP_STORAGE_HOME is an environment variable in App Service that is mapped to persistent storage for your app. For example:

wordpress:
  image: <image name:tag>
  volumes:
  - "${WEBAPP_STORAGE_HOME}/site/wwwroot:/var/www/html"
  - "${WEBAPP_STORAGE_HOME}/phpmyadmin:/var/www/phpmyadmin"
  - "${WEBAPP_STORAGE_HOME}/LogFiles:/var/log"

Preview limitations

Multi-container is currently in preview. The following App Service platform features aren't supported:

  • Authentication / Authorization
  • Managed Identities
  • CORS
  • Virtual network integration isn't supported for Docker Compose scenarios
  • Docker Compose on Azure App Services currently has a limit of 4,000 characters at this time.

Docker Compose options

The following lists show supported and unsupported Docker Compose configuration options:

Supported options

Unsupported options

  • build (not allowed)
  • depends_on (ignored)
  • networks (ignored)
  • secrets (ignored)
  • ports other than 80 and 8080 (ignored)
  • default environment variables like $variable and ${variable} unlike in docker

Syntax Limitations

  • "version x.x" always needs to be the first YAML statement in the file
  • ports section must use quoted numbers
  • image > volume section must be quoted and can't have permissions definitions
  • volumes section must not have an empty curly brace after the volume name

Note

Any other options not explicitly called out are ignored in Public Preview.

robots933456 in logs

You may see the following message in the container logs:

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

You can safely ignore this message. /robots933456.txt is a dummy URL path that App Service uses to check if the container is capable of serving requests. A 404 response simply indicates that the path doesn't exist, but it lets App Service know that the container is healthy and ready to respond to requests.

Next steps

Tutorial: Migrate custom software to Azure App Service using a custom container

Tutorial: Configure a sidecar container for custom container in Azure App Service (preview)

Or, see more resources: