Skip to content

Commit c6594e9

Browse files
tulikactulikac
authored
Merge pull request #499 from Azure/sidecars-deepdive
Feature spec for sidecars
2 parents 5851aa5 + 9d036d5 commit c6594e9

File tree

1 file changed

+121
-0
lines changed

1 file changed

+121
-0
lines changed

‎_posts/2025-03-06-Sidecars-Deep-Dive-Part1.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: "Sidecars in Azure App Service: A Deep Dive"
3+
author_name: "Tulika Chaudharie"
4+
---
5+
6+
# Sidecars in Azure App Service: A Deep Dive
7+
8+
In November 2024, we announced the [General Availability (GA) of the Sidecar feature for Azure App Service for Linux](https://techcommunity.microsoft.com/blog/appsonazureblog/announcing-the-general-availability-of-sidecar-extensibility-in-azure-app-servic/4267985). Today, we want to dive deep into this feature to help developers understand its capabilities and configurations. This blog post is the first in a series that will explore various aspects of Sidecars, from specification details to deployment and advanced use cases.
9+
10+
### What is a Sidecar in Azure App Service?
11+
In a typical App Service deployment, a single container runs the application workload. With the new **Sidecar feature**, you can now deploy additional supporting containers that run alongside the main application container within the same site unit.
12+
13+
This feature applies to **both single-container and multi-container applications**, introducing a new, more intuitive way to configure single-container applications as well. Previously, configuring a single container required setting `LinuxFxVersion=DOCKER|<image details>` and defining multiple app settings for details like port configuration. With **SiteContainers**, configuration is now **unified and streamlined** across:
14+
- **Single-container applications**
15+
- **Multi-container applications**
16+
- **Code-based applications** that want to add a sidecar
17+
18+
This feature is available for **custom container-based deployments** under a new `LinuxFxVersion`:
19+
```
20+
LinuxFxVersion=sitecontainers
21+
```
22+
23+
For **code-based apps**, customers can also add sidecars that will run alongside the the main code container as part of the site unit.
24+
25+
**Note: The content in this document does not apply to sites using Docker Compose**
26+
27+
## Sidecar Specification Format
28+
A **sidecar-enabled site unit** is defined using a JSON specification. Below is an example of what this spec looks like:
29+
30+
```json
31+
{
32+
"image": "mcr.microsoft.com/appsvc/staticsite:latest",
33+
"isMain": true,
34+
"targetPort": "80",
35+
"startUpCommand": null,
36+
"authType": "Anonymous",
37+
"userName": null,
38+
"passwordSecret": null,
39+
"userManagedIdentityClientId": null,
40+
"inheritAppSettingsAndConnectionStrings": false,
41+
"volumeMounts": [
42+
{
43+
"volumeSubPath": "/host/path",
44+
"containerMountPath": "/path/in/container",
45+
"readOnly": false
46+
}
47+
],
48+
"environmentVariables": [
49+
{
50+
"name": "envVarName",
51+
"value": "APPSETTING_REF"
52+
}
53+
]
54+
}
55+
```
56+
57+
## Sidecar Specification Attributes
58+
The table below outlines the attributes used in the Sidecar specification. These attributes define the properties of each container within the site unit.
59+
60+
| Name | Type | Is Required | Default Value | Description |
61+
|-------|------|------------|--------------|-------------|
62+
| `image` | String | Yes | N/A | The fully qualified container image to be used. |
63+
| `isMain` | Boolean | Yes | false | Indicates whether this container is the main application container. |
64+
| `targetPort` | String | No | null | The port on which the container listens. |
65+
| `startUpCommand` | String | No | null | The startup command to run when the container is starting. |
66+
| `authType` | String | No | null | Authentication type for the container registry. The allowed values are 1. Anonymous 2. UserCredentials 3. SystemIdentity 4. UserAssigned |
67+
| `userName` | String | No | null | Username for the container registry if required. |
68+
| `passwordSecret` | String | No | null | Secret key reference for the container registry password. |
69+
| `userManagedIdentityClientId` | String | No | null | The Managed Identity used for authentication to the container registry. |
70+
| `inheritAppSettingsAndConnectionStrings` | Boolean | No | true | If false, prevents AppSettings from being inherited. |
71+
| `volumeMounts` | Array | No | [] | List of volumes mounted to the container. |
72+
| `environmentVariables` | Array | No | [] | List of environment variables for the container. |
73+
74+
75+
**Attributes for volumeMounts**
76+
77+
| Name | Type | Is Required | Default Value | Description |
78+
|-------|------|------------|--------------|-------------|
79+
| `volumeSubPath` | String | Yes | N/A | Path of the directory relative to the volume on the host. |
80+
| `containerMountPath` | String | Yes | N/A | Target Path on the container. |
81+
| `readOnly` | Boolean | false | N/A | Specify if the mount is read only on container. |
82+
83+
84+
**Attributes for environmentVariables**
85+
86+
| Name | Type | Is Required | Default Value | Description |
87+
|-------|------|------------|--------------|-------------|
88+
| `name` | String | Yes | N/A | Name of the variable on the container. |
89+
| `value` | String | Yes | N/A | The value of this environment variable must be the name of an AppSetting. The actual value of the environment variable in container will be retrieved from the specified AppSetting at runtime. If the AppSetting is not found, the value will be set to an empty string in the container at runtime. |
90+
91+
92+
## Important Considerations
93+
- If you are using custom containers, you would need to set `linuxFxVersion = sitecontainers`. If the `LinuxFxVersion=DOCKER|<>` is set, any sidecars which are added would be ignored.
94+
- App Service **routes traffic only to the container marked as the main container** (`IsMain=true` in the sidecar spec). For Code-based apps, we route traffic to main code container and you should only add other sidecars with IsMain = false.
95+
- All containers **share the same network namespace** and can communicate over `localhost`, so port conflicts must be avoided.
96+
- The default storage volume (`/home`) is **mounted to all containers** unless App Service Storage is disabled using the app setting:
97+
```
98+
WEBSITES_ENABLE_APP_SERVICE_STORAGE=false
99+
```
100+
- **All application settings** are passed to all containers as environment variables unless overridden using `inheritAppSettingsAndConnectionStrings=false` in the sidecar spec.
101+
- Each container can also have its **own specific environment variables** defined in the spec based on chosen AppSetting references.
102+
- A **custom local volume** can be optionally mounted and shared across containers.
103+
104+
## Additional Resources
105+
If you'd like to explore the specifications further and see how to use them in an **ARM template**, check out this example: [Sidecar ARM Template](https://github.com/Azure-Samples/sidecar-samples/tree/main/sidecar-arm-template).
106+
107+
For hands-on tutorials, refer to:
108+
- **Using sidecars in code-based apps:** [Tutorial](https://learn.microsoft.com/en-us/azure/app-service/tutorial-sidecar?tabs=portal)
109+
- **Using sidecars in container-based apps:** [Tutorial](https://learn.microsoft.com/en-us/azure/app-service/tutorial-custom-container-sidecar)
110+
111+
To explore **scenarios where sidecars add value**, including observability, caching, and AI-based enhancements, refer to the following:
112+
- Enhancing Observability with [Datadog](https://azure.github.io/AppService/2024/07/26/Using-Datadog-with-Sidecar.html) and [Dynatrace](https://azure.github.io/AppService/2024/07/26/Using-Dynatrace-with-Sidecar.html)
113+
- [Improving application performance with Redis sidecar](https://azure.github.io/AppService/2024/07/19/Using-Redis-with-Sidecar.html)
114+
- [Integrating AI Capabilities Using Sidecars](https://azure.github.io/AppService/2024/09/03/Phi3-vector.html)
115+
- [Try out sidecars in this guided lab](https://mslabs.cloudguides.com/guides/Sidecars%20in%20Azure%20App%20Service)
116+
117+
## Summary
118+
The **Sidecars feature in Azure App Service for Linux** introduces **multi-container support**, allowing customers to build **more complex and modular applications**. By using sidecars, developers can extend the capabilities of their applications while keeping their main app lightweight and focused on core functionality.
119+
120+
In the next part of this series, we’ll explore **how to deploy a sidecar-enabled application** and demonstrate practical use cases. Stay tuned!
121+

0 commit comments

Comments
 (0)