Skip to content

Commit 8367e8d

Browse files
cephalincephalin
committed
add sidecar conceptuals
1 parent 003bcb1 commit 8367e8d

10 files changed

+410
-59
lines changed

‎articles/app-service/configure-sidecar.md

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
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/02/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 in the **Deployment Center** > **Containers** page of an existing application.
25+
26+
With the Azure CLI, set `LinuxFxVersion` to `sitecontainers`. For example:
27+
28+
```azurecli
29+
az webapp config set --name <app-name> --resource-group <resource-group> --linux-fx-version sitecontainers
30+
```
31+
32+
For more information, see [What are the differences for sidecar-enabled custom containers?](#what-are-the-differences-for-sidecar-enabled-custom-containers)
33+
34+
### What are the differences for sidecar-enabled custom containers?
35+
36+
Sidecar-enabled apps are configured differently than apps that aren't sidecar-enabled.
37+
38+
- Sidecar-enabled apps are designated by `LinuxFxVersion=sitecontainers` and configured with [`sitecontainers`](/azure/templates/microsoft.web/sites/sitecontainers) resources.
39+
- Apps that aren't sidecar enabled configure the container name and type directly with `LinuxFxVersion=DOCKER|<image-details>`.
40+
41+
For more information, see [az webapp config set --linux-fx-version](/cli/azure/webapp/config).
42+
43+
Apps that aren't sidecar-enabled configure the main container with app settings such as:
44+
45+
- `DOCKER_REGISTRY_SERVER_URL`
46+
- `DOCKER_REGISTRY_SERVER_USERNAME`
47+
- `DOCKER_REGISTRY_SERVER_PASSWORD`
48+
- `WEBSITES_PORT`
49+
50+
These settings don't apply for sidecar-enabled apps.
51+
52+
## Define a sidecar with an ARM template
53+
54+
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`:
55+
56+
```json
57+
{
58+
"type": "Microsoft.Web/sites/sitecontainers",
59+
"apiVersion": "2024-04-01",
60+
"name": "<app-name>/<sidecar-name>",
61+
"properties": {
62+
"image": "<acr-name>.azurecr.io/<image-name>:<version>",
63+
"isMain": false,
64+
"authType": "UserAssigned",
65+
"userManagedIdentityClientId": "<client-id>",
66+
"environmentVariables": [
67+
{ "name": "MY_ENV_VAR", "value": "my-value" }
68+
]
69+
}
70+
}
71+
```
72+
73+
> [!IMPORTANT]
74+
> 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`.
75+
76+
For more information, see [Microsoft.Web sites/sitecontainers](/azure/templates/microsoft.web/sites/sitecontainers).
77+
78+
## How to Define Environment Variables for a Sidecar
79+
80+
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.
81+
82+
- In ARM templates, use the `environmentVariables` array in the sidecar's properties.
83+
- In the Portal, add environment variables in the container configuration UI.
84+
- Environment variables can reference app settings by name; the value will be resolved at runtime.
85+
86+
## Add the Redis sidecar extension
87+
88+
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.
89+
90+
To use the Redis sidecar:
91+
92+
- In your application code, set the Redis connection string to `localhost:6379`.
93+
- Configure Redis in your app’s startup code.
94+
- Use caching patterns to store and retrieve data.
95+
- Test by accessing your app and checking logs to confirm cache usage.
96+
97+
## Add the Datadog sidecar extension
98+
99+
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.
100+
101+
**For code-based apps:**
102+
103+
1. Create a `startup.sh` script to download and initialize the Datadog tracer. The following script is an example for a .NET app:
104+
105+
```bash
106+
#!/bin/bash
107+
108+
# Create log directory. This should correspond to the "Datadog Trace Log Directory" extension setting
109+
mkdir -p /home/LogFiles/dotnet
110+
111+
# Download the Datadog tracer tarball
112+
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
113+
114+
# Navigate to the tracer directory, extract the tarball, and return to the original directory
115+
mkdir -p /datadog/tracer
116+
pushd /datadog/tracer
117+
tar -zxf datadog-dotnet-apm-2.49.0.tar.gz
118+
popd
119+
120+
dotnet /home/site/wwwroot/<yourapp>.dll
121+
```
122+
123+
2. Set the startup command in App Service to run this script.
124+
125+
3. Run the application and confirm the telemetry is shipped by signing into your Datadog dashboard.
126+
127+
**For container-based apps:**
128+
129+
Before you add the Datadog sidecar extension, add the Datadog tracer setup in your Dockerfile, similar to the script example for code-based apps.
130+
131+
## Add the Phi-3/Phi-4
132+
133+
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.
134+
135+
- The Phi-3/Phi-4 sidecar exposes a chat completion API at http://localhost:11434/v1/chat/completions.
136+
- After the sidecar is added, initial startup may be slow due to model loading.
137+
- 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).
138+
139+
For end-to-end walkthroughs, see:
140+
141+
- [Tutorial: Run chatbot in App Service with a Phi-4 sidecar extension (ASP.NET Core)](tutorial-ai-slm-dotnet.md)
142+
- [Tutorial: Run chatbot in App Service with a Phi-4 sidecar extension (Spring Boot)](tutorial-ai-slm-spring-boot.md)
143+
- [Tutorial: Run chatbot in App Service with a Phi-4 sidecar extension (FastAPI)](tutorial-ai-slm-fastapi.md)
144+
- [Tutorial: Run chatbot in App Service with a Phi-4 sidecar extension (Express.js)](tutorial-ai-slm-expressjs.md)
145+
146+
147+
## Access a sidecar from the main container or from another sidecar
148+
149+
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`.
150+
151+
The **Port** field in the Portal is metadata only and not used by App Service for routing.
152+
153+
## Add volume mounts
154+
155+
By default, the default `/home` volume is mounted to all containers unless disabled. You can configure additional volumn mounts for your sidecars.
156+
157+
Volume mounts enable you to share non-persistent files and directories between containers within your Web App.
158+
159+
- **Volume sub path:** Logical directory path created by App Service. Containers with the same sub path share files.
160+
- **Container mount path:** Directory path inside the container mapped to the volume sub path.
161+
162+
Example configuration:
163+
164+
| Sidecar name | Volume sub path | Container mount path | Read-only |
165+
| ------------ | --------------- | -------------------- | --------- |
166+
| Container1 | /directory1/directory2 | /container1Vol | False |
167+
| Container2 | /directory1/directory2 | /container2Vol | True |
168+
| Container3 | /directory1/directory2/directory3 | /container3Vol | False |
169+
| Container4 | /directory4 | /container1Vol | False |
170+
171+
- If Container1 creates `/container1Vol/myfile.txt`, Container2 can read it via `/container2Vol/myfile.txt`.
172+
- 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`.
173+
- Container4 does not share a volume with the others.
174+
175+
> [!Note]
176+
> For code-based Linux apps, the built-in Linux container cannot use volume mounts.

‎articles/app-service/migrate-sidecar-multi-container-apps.md

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
title: Migrate Docker Compose to sidecars
3+
description: Guidance for migrating from Docker Compose or custom multi-container apps to the sidecar model in Azure App Service.
4+
ms.topic: how-to
5+
ms.date: 07/02/2025
6+
ms.author: cephalin
7+
author: cephalin
8+
---
9+
10+
# Migrate Docker Compose apps to sidecars in Azure App Service
11+
12+
If you're running a Docker Compose app in Azure App Service, you should migrate it to sidecars. There are two main strategies for migrating a Docker Compose app to sidecars.
13+
14+
- Script-based migration - recommended for simple setups.
15+
- Manual migration
16+
17+
## a. Prerequisites
18+
19+
- PowerShell
20+
- Azure CLI
21+
- Docker (for building and pushing images)
22+
- Text editor (e.g., VS Code)
23+
24+
## Script-based migration
25+
26+
If your Docker Compose file is straightforward, you can use the official migration script to automate the process.
27+
28+
> [!IMPORTANT]
29+
> Always back up your app from the Azure portal before running the migration script.
30+
31+
1. [Download the migration script from the Azure Samples GitHub repository.](https://github.com/Azure-Samples/sidecar-samples/blob/main/migration-script/update_sidecars.ps1)
32+
2. Run the script in PowerShell, providing your subscription ID, web app name, resource group, registry URL, base64-encoded Docker Compose file, main service name, and target port.
33+
34+
```powershell
35+
./update-webapp.ps1 `
36+
-subscriptionId "<subscriptionId>" `
37+
-webAppName "<webAppName>" `
38+
-resourceGroup "<resourceGroup>" `
39+
-registryUrl "<registryUrl>" `
40+
-base64DockerCompose "<base64DockerCompose>" `
41+
-mainServiceName "<mainServiceName>" `
42+
-targetPort "<targetPort>"
43+
```
44+
45+
If your registry requires authentication, the script prompts you to provide `dockerRegistryServerUsername` and `dockerRegistryServerPassword` interactively.
46+
47+
## Manual migration
48+
49+
1. Sign in to Azure and set your subscription.
50+
51+
```azurecli
52+
az login
53+
az account set --subscription <your-subscription-id>
54+
```
55+
56+
2. Gather required details.
57+
58+
```azurecli
59+
az account show --query id --output tsv
60+
az webapp list --query "[].{name:name}" --output tsv
61+
az group list --query "[].{name:name}" --output tsv
62+
az acr list --query "[].{name:name}" --output tsv
63+
```
64+
65+
These will help you identify your subscription ID, app name, resource group, and Azure container registry.
66+
67+
3. Create a deployment slot. You will validate the migrated sidecars before switching the slot into production.
68+
69+
```azurecli
70+
az webapp deployment slot create --name <webapp-name> --resource-group <resource-group> --slot <slot-name>
71+
```
72+
73+
4. Decode the existing Docker Compose configuration from the production app.
74+
75+
```azurecli
76+
az webapp config show --name <webapp-name> --resource-group <resource-group> --query linuxFxVersion
77+
```
78+
79+
Copy the base64 part from the output and decode it in PowerShell:
80+
81+
```powershell
82+
[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("<base64value>"))
83+
```
84+
85+
5. For each service in your Compose file, create a corresponding `container` resource in the deployment slot under the `sitecontainers` URL path:
86+
87+
```azurecli
88+
az rest --method PUT \
89+
--url https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/sites/<webapp-name>/slots/<slot-name>/sitecontainers/<container-name>?api-version=2023-12-01 \
90+
--body '{"name":"<container-name>", "properties":{"image":"<image-name>", "isMain": <true/false>, "targetPort": <port>}}'
91+
```
92+
- Use [Mapping of Docker Compose Attributes and Sidecar Configuration](#mapping-of-docker-compose-attributes-and-sidecar-configuration) to help you with the mapping.
93+
- Use a container name you want in `<container-name>`.
94+
- Set `isMain` to `true` for the main app container, `false` for sidecars.
95+
- For `<image-name>`, use the full path for the image that includes the server name. For example:
96+
97+
```json
98+
"image":"myregistry.azurecr.io/myapp/backend:latest"
99+
```
100+
- Repeat for all containers.
101+
102+
6. Switch the deployment slot to use sidecar mode.
103+
104+
```azurecli
105+
az webapp config set --name <webapp-name> --resource-group <resource-group> --slot <slot-name> --linux-fx-version "sitecontainers"
106+
```
107+
108+
7. Restart the deployment slot, then validate the functionatity of the migrated app in the deployment slot.
109+
110+
```azurecli
111+
az webapp restart --name <webapp-name> --resource-group <resource-group> --slot <slot-name>
112+
```
113+
114+
8. Once validated, swap the slot to production:
115+
```azurecli
116+
az webapp deployment slot swap --name <webapp-name> --resource-group <resource-group> --slot <slot-name> --target-slot production
117+
```
118+
119+
## Mapping of Docker Compose Attributes and Sidecar Configuration
120+
121+
The following Docker Compose fields are mapped to sidecar configuration:
122+
123+
| Docker Compose | Sidecar Configuration | Notes |
124+
|---------------|----------------------|-------|
125+
| `command`, `entrypoint` | `startUpCommand` | |
126+
| `environment` | `environmentVariables` | |
127+
| `image` | `image` | |
128+
| `ports` | `targetPort` | Only ports 80 and 8080 are supported for external traffic |
129+
| `volumes` | `volumeMounts` | Persistent Azure storage not supported |
130+
131+
The following Docker Compose fields are unsupported in sidecars:
132+
133+
| Docker Compose Field | Support | Notes |
134+
|---------------------|---------|-------|
135+
| `build` | Not allowed | Pre-build and push images to a registry |
136+
| `depends_on` | Ignored | No container startup ordering guaranteed |
137+
| `networks` | Ignored | Network handled internally |
138+
| `secrets` | Ignored | Use App Settings or Key Vault |
139+
| `volumes` using `{WEBAPP_STORAGE_HOME}` or `{WEBSITES_ENABLE_APP_SERVICE_STORAGE}` | Not supported | |
140+
141+
## Migration limitations and considerations
142+
143+
The following table shows the features currently supported in Docker Compose apps that are not supported or have limit support in sidecars.
144+
145+
| Feature | Docker Compose | Sidecar |
146+
|---------|---------------|---------|
147+
| Storage | Volumes shared between containers | Container-specific, persistent storage limited |
148+
| Networking | Service names as hostnames | All containers share `localhost`; unique ports required |
149+
| Logging & Monitoring | Custom drivers, external tools | Integrated with Azure Monitor and Log Analytics |
150+
| App Service Environment (ASE) | Supported | Not yet supported |
151+
| National Clouds | Supported | Not yet supported |
152+
153+
## More resources
154+
155+
- [Sidecar overview](overview-sidecar.md)
156+
- [Configure sidecars](configure-sidecar.md)
157+
- [Microsoft Q&A for Azure App Service](https://learn.microsoft.com/answers/tags/436/azure-app-service)

0 commit comments

Comments
 (0)