|
| 1 | +--- |
| 2 | +title: Configure sidecars |
| 3 | +description: Step-by-step guide to configuring sidecars, including adding built-in extensions. |
| 4 | +ms.topic: how-to |
| 5 | +ms.date: 07/14/2025 |
| 6 | +ms.author: cephalin |
| 7 | +author: cephalin |
| 8 | +--- |
| 9 | + |
| 10 | +# Configure sidecars in Azure App Service |
| 11 | + |
| 12 | +This article provides practical steps for enabling and configuring sidecars in your App Service app. |
| 13 | + |
| 14 | +## Create a sidecar in the Azure portal |
| 15 | + |
| 16 | +1. Go to your App Service resource in the Azure portal. |
| 17 | +2. Select **Deployment Center** and go to the **Containers** tab. |
| 18 | +3. Click **Add container** to add a sidecar. |
| 19 | +4. Fill in the image name, registry authentication (if needed), and environment variables. |
| 20 | +5. Save your changes. The sidecar will be deployed alongside your main app container. |
| 21 | + |
| 22 | +## Enable sidecar support for Linux custom containers |
| 23 | + |
| 24 | +For a custom container, you need to explicitly enable sidecar support. In the portal, you can make the selection in the [App Service create wizard](https://portal.azure.com/#view/WebsitesExtension/AppServiceWebAppCreateV3Blade). You can also enable it for an existing app in the **Deployment Center** > **Containers** page of an existing application, as shown in the following screenshot: |
| 25 | + |
| 26 | +:::image type="content" source="media/configure-sidecar/enable-sidecar.png" alt-text="A screenshot showing a custom container app's container settings with the Start Update button highlighted."::: |
| 27 | + |
| 28 | +With the Azure CLI, set `LinuxFxVersion` to `sitecontainers`. For example: |
| 29 | + |
| 30 | +```azurecli |
| 31 | +az webapp config set --name <app-name> --resource-group <resource-group> --linux-fx-version sitecontainers |
| 32 | +``` |
| 33 | + |
| 34 | +For more information, see [What are the differences for sidecar-enabled custom containers?](#what-are-the-differences-for-sidecar-enabled-custom-containers) |
| 35 | + |
| 36 | +### What are the differences for sidecar-enabled custom containers? |
| 37 | + |
| 38 | +Sidecar-enabled apps are configured differently than apps that aren't sidecar-enabled. |
| 39 | + |
| 40 | +- Sidecar-enabled apps are designated by `LinuxFxVersion=sitecontainers` and configured with [`sitecontainers`](/azure/templates/microsoft.web/sites/sitecontainers) resources. |
| 41 | +- Apps that aren't sidecar enabled configure the container name and type directly with `LinuxFxVersion=DOCKER|<image-details>`. |
| 42 | + |
| 43 | +For more information, see [az webapp config set --linux-fx-version](/cli/azure/webapp/config). |
| 44 | + |
| 45 | +Apps that aren't sidecar-enabled configure the main container with app settings such as: |
| 46 | + |
| 47 | +- `DOCKER_REGISTRY_SERVER_URL` |
| 48 | +- `DOCKER_REGISTRY_SERVER_USERNAME` |
| 49 | +- `DOCKER_REGISTRY_SERVER_PASSWORD` |
| 50 | +- `WEBSITES_PORT` |
| 51 | + |
| 52 | +These settings don't apply for sidecar-enabled apps. |
| 53 | + |
| 54 | +## Define a sidecar with an ARM template |
| 55 | + |
| 56 | +Add the `Microsoft.Web/sites/sitecontainers` resource type to an app. To pull a sidecar image from ACR using a user-assigned managed identity, specify `authType` as `UserAssigned` and provide the `userManagedIdentityClientId`: |
| 57 | + |
| 58 | +```json |
| 59 | +{ |
| 60 | + "type": "Microsoft.Web/sites/sitecontainers", |
| 61 | + "apiVersion": "2024-04-01", |
| 62 | + "name": "<app-name>/<sidecar-name>", |
| 63 | + "properties": { |
| 64 | + "image": "<acr-name>.azurecr.io/<image-name>:<version>", |
| 65 | + "isMain": false, |
| 66 | + "authType": "UserAssigned", |
| 67 | + "userManagedIdentityClientId": "<client-id>", |
| 68 | + "environmentVariables": [ |
| 69 | + { "name": "MY_ENV_VAR", "value": "my-value" } |
| 70 | + ] |
| 71 | + } |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +> [!IMPORTANT] |
| 76 | +> Only the main container (`"isMain": true`) receives external traffic. In a Linux custom container app with sidecar support enabled, your main container has `isMain` set to `true`. All sidecar containers should have `"isMain": false`. |
| 77 | +
|
| 78 | +For more information, see [Microsoft.Web sites/sitecontainers](/azure/templates/microsoft.web/sites/sitecontainers). |
| 79 | + |
| 80 | +## Create sidecars with Azure CLI |
| 81 | + |
| 82 | +Create a sidecar-enabled app with [az webapp create](/cli/azure/webapp#az-webapp-create). For example: |
| 83 | + |
| 84 | +```azurecli-interactive |
| 85 | +az webapp create --name <app-name> --resource-group <group-name> --sitecontainers-app |
| 86 | +``` |
| 87 | + |
| 88 | +Create a sidecar container with [az webapp sitecontainers create](/cli/azure/webapp/sitecontainers#az-webapp-sitecontainers-create). For example: |
| 89 | + |
| 90 | +```azurecli-interactive |
| 91 | +az webapp sitecontainers create --name <app-name> --resource-group <group-name> --container-name <container> --image <image> --target-port <port> |
| 92 | +``` |
| 93 | + |
| 94 | +Create a sidecar container with a JSON file: |
| 95 | + |
| 96 | +```azurecli-interactive |
| 97 | +az webapp sitecontainers create --name <app-name> --resource-group <group-name> --sitecontainers-spec-file <file-path> |
| 98 | +``` |
| 99 | + |
| 100 | +For all sidecar commands, see [az webapp sitecontainers](/cli/azure/webapp/sitecontainers). |
| 101 | + |
| 102 | +## Set environment variables |
| 103 | + |
| 104 | +In a Linux app, all containers (main and sidecars) share environment variables. To override a specific variable for a sidecar, add it in the sidecar's configuration. |
| 105 | + |
| 106 | +- In ARM templates, use the `environmentVariables` array in the sidecar's properties. |
| 107 | +- In the Portal, add environment variables in the container configuration UI. |
| 108 | +- Environment variables can reference app settings by name; the value will be resolved at runtime. |
| 109 | + |
| 110 | +## Add the Redis sidecar extension |
| 111 | + |
| 112 | +From the Azure portal, you can add a Redis sidecar extension to your app for caching. The Redis sidecar is for lightweight caching only, not a replacement for Azure Cache for Redis. |
| 113 | + |
| 114 | +To use the Redis sidecar: |
| 115 | + |
| 116 | +- In your application code, set the Redis connection string to `localhost:6379`. |
| 117 | +- Configure Redis in your app’s startup code. |
| 118 | +- Use caching patterns to store and retrieve data. |
| 119 | +- Test by accessing your app and checking logs to confirm cache usage. |
| 120 | + |
| 121 | +## Add the Datadog sidecar extension |
| 122 | + |
| 123 | +From the Azure portal, you can add a Datadog sidecar extension to collect logs, metrics, and traces for observability without modifying app code. When you add the extension, you specify your Datadog account information so that the sidecar extension can ship telemetry directly to Datadog. |
| 124 | + |
| 125 | +**For code-based apps:** |
| 126 | + |
| 127 | +1. Create a `startup.sh` script to download and initialize the Datadog tracer. The following script is an example for a .NET app: |
| 128 | + |
| 129 | + ```bash |
| 130 | + #!/bin/bash |
| 131 | + |
| 132 | + # Create log directory. This should correspond to the "Datadog Trace Log Directory" extension setting |
| 133 | + mkdir -p /home/LogFiles/dotnet |
| 134 | + |
| 135 | + # Download the Datadog tracer tarball |
| 136 | + wget -O /datadog/tracer/datadog-dotnet-apm-2.49.0.tar.gz https://github.com/DataDog/dd-trace-dotnet/releases/download/v2.49.0/datadog-dotnet-apm-2.49.0.tar.gz |
| 137 | + |
| 138 | + # Navigate to the tracer directory, extract the tarball, and return to the original directory |
| 139 | + mkdir -p /datadog/tracer |
| 140 | + pushd /datadog/tracer |
| 141 | + tar -zxf datadog-dotnet-apm-2.49.0.tar.gz |
| 142 | + popd |
| 143 | + |
| 144 | + dotnet /home/site/wwwroot/<yourapp>.dll |
| 145 | + ``` |
| 146 | + |
| 147 | +2. Set the startup command in App Service to run this script. |
| 148 | + |
| 149 | +3. Run the application and confirm the telemetry is shipped by signing into your Datadog dashboard. |
| 150 | + |
| 151 | +**For container-based apps:** |
| 152 | + |
| 153 | +Before you add the Datadog sidecar extension, add the Datadog tracer setup in your Dockerfile, similar to the script example for code-based apps. |
| 154 | + |
| 155 | +## Add the Phi-3/Phi-4 sidecar extension |
| 156 | + |
| 157 | +From the Azure portal, you can add a Phi-3 or Phi-4 sidecar extension to your app to provide a local inference model for AI workloads. Your app must be in a pricing tier that supports the inferencing needs. For unsupported tiers, you don't see the options for the Phi-3/Phi-4 sidecar extensions. |
| 158 | +
|
| 159 | +- The Phi-3/Phi-4 sidecar exposes a chat completion API at http://localhost:11434/v1/chat/completions. |
| 160 | +- After the sidecar is added, initial startup may be slow due to model loading. |
| 161 | +- To invoke the API, send POST requests to this endpoint, in the same style of the [OpenAPI chat completion API](https://platform.openai.com/docs/api-reference/chat/create). |
| 162 | +
|
| 163 | +For end-to-end walkthroughs, see: |
| 164 | +
|
| 165 | +- [Tutorial: Run chatbot in App Service with a Phi-4 sidecar extension (ASP.NET Core)](tutorial-ai-slm-dotnet.md) |
| 166 | +- [Tutorial: Run chatbot in App Service with a Phi-4 sidecar extension (Spring Boot)](tutorial-ai-slm-spring-boot.md) |
| 167 | +- [Tutorial: Run chatbot in App Service with a Phi-4 sidecar extension (FastAPI)](tutorial-ai-slm-fastapi.md) |
| 168 | +- [Tutorial: Run chatbot in App Service with a Phi-4 sidecar extension (Express.js)](tutorial-ai-slm-expressjs.md) |
| 169 | +
|
| 170 | +
|
| 171 | +## Access a sidecar from the main container or from another sidecar |
| 172 | +
|
| 173 | +Sidecar containers share the same network host as the main container. The main container and other sidecars can reach any port on a sidecar using `localhost:<port>`. For example, if a sidecar listens on port 4318, the main app can access it at `localhost:4318`. |
| 174 | +
|
| 175 | +The **Port** field in the Portal is metadata only and not used by App Service for routing. |
| 176 | +
|
| 177 | +## Add volume mounts |
| 178 | +
|
| 179 | +By default, the default `/home` volume is mounted to all containers unless disabled. You can configure additional volume mounts for your sidecars. |
| 180 | +
|
| 181 | +Volume mounts enable you to share non-persistent files and directories between containers within your Web App. |
| 182 | +
|
| 183 | +- **Volume sub path:** Logical directory path created by App Service. Containers with the same sub path share files. |
| 184 | +- **Container mount path:** Directory path inside the container mapped to the volume sub path. |
| 185 | +
|
| 186 | +Example configuration: |
| 187 | +
|
| 188 | +| Sidecar name | Volume sub path | Container mount path | Read-only | |
| 189 | +| ------------ | --------------- | -------------------- | --------- | |
| 190 | +| Container1 | /directory1/directory2 | /container1Vol | False | |
| 191 | +| Container2 | /directory1/directory2 | /container2Vol | True | |
| 192 | +| Container3 | /directory1/directory2/directory3 | /container3Vol | False | |
| 193 | +| Container4 | /directory4 | /container1Vol | False | |
| 194 | +
|
| 195 | +- If Container1 creates `/container1Vol/myfile.txt`, Container2 can read it via `/container2Vol/myfile.txt`. |
| 196 | +- If Container1 creates `/container1Vol/directory3/myfile.txt`, Container2 can read it via `/container2Vol/directory3/myfile.txt`, and Container3 can read/write via `/container3Vol/myfile.txt`. |
| 197 | +- Container4 does not share a volume with the others. |
| 198 | +
|
| 199 | +> [!Note] |
| 200 | +> For code-based Linux apps, the built-in Linux container cannot use volume mounts. |
| 201 | +
|
| 202 | +## More resources |
| 203 | +
|
| 204 | +- [Sidecars overview](overview-sidecar.md) |
| 205 | +- [Migrate Docker Compose apps to sidecars in Azure App Service](migrate-sidecar-multi-container-apps.md) |
| 206 | +- [Microsoft Q&A for Azure App Service](/answers/tags/436/azure-app-service) |
0 commit comments