Tutorial: Configure a sidecar container for a custom container app

This tutorial shows you how to add an OpenTelemetry collector as a sidecar container to a Linux custom container app in Azure App Service.

Sidecar containers in App Service let you deploy extra services and features to your Linux apps without tightly coupling them to the built-in or custom main container. The sidecar containers run alongside the main application container in the same App Service plan.

You can add up to nine sidecar containers for each Linux app in App Service. For example, you can add monitoring, logging, configuration, and networking services as sidecar containers. An OpenTelemetry collector sidecar is one example for monitoring.

For bring-your-own-code Linux apps, see Tutorial: Configure a sidecar container for a Linux app in Azure App Service.

Prerequisites

• If you don't have an Azure account, create a free account before you begin.

• You can run the commands in this tutorial by using Azure Cloud Shell, an interactive shell you use through your browser to work with Azure services. To use Cloud Shell:

  1. Select the following Launch Cloud Shell button or go to https://shell.azure.com to open Cloud Shell in your browser.

     

  2. Sign in to Azure if necessary, and make sure you're in the Bash environment of Cloud Shell.

  3. Select Copy in any code block, paste the code into Cloud Shell, and run it.

     The azd commands in this tutorial use the Azure Developer CLI, an open-source tool that accelerates provisioning and deploying app resources on Azure.

1. Set up the tutorial resources

To clone the sample repository and create the resources for this tutorial, run the following commands in Cloud Shell. When prompted, select the Azure subscription and Azure region you want to use.

git clone https://github.com/Azure-Samples/app-service-sidecar-tutorial-prereqs
cd app-service-sidecar-tutorial-prereqs
azd env new my-sidecar-env
azd provision

The azd provision command uses the included templates to create an Azure resource group called my-sidecar-env_group that contains the following Azure resources:

• A container registry with two repositories that have the following images:
  • An nginx image that has the OpenTelemetry module.
  • An otel-collector OpenTelemetry collector image configured to export to Azure Monitor.
• A Log Analytics workspace.
• An Application Insights component.
• A user-assigned managed identity called id-my-sidecar-env_group.

When deployment completes, you should see output similar to the following example:

Success!

APPLICATIONINSIGHTS_CONNECTION_STRING = InstrumentationKey=aaaaaaaa-0b0b-1c1c-2d2d-333333333333;IngestionEndpoint=https://eastus2-3.in.applicationinsights.azure.com/;LiveEndpoint=https://eastus2.livediagnostics.monitor.azure.com/;ApplicationId=00001111-aaaa-2222-bbbb-3333cccc4444
Azure container registry name = acro2lc774l6vjgg
Managed identity resource ID = /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-sidecar-env_group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/id-my-sidecar-env_group
Managed identity client ID = 00aa00aa-bb11-cc22-dd33-44ee44ee44ee

Open resource group in the portal: https://portal.azure.com/#@/resource/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-sidecar-env_group

Copy and save the value for APPLICATIONINSIGHTS_CONNECTION_STRING to use later in this tutorial.

Select the link for Open resource group in the portal to open the provisioned resource group in the Azure portal.

2. Create a sidecar-enabled app

In the resource group in the Azure portal, create a Linux custom container app with sidecar support, and configure the main container.

1. On the resource group's page in the Azure portal, select Create.

2. On the Marketplace page, search for web app, select the down arrow next to Create on the Web App tile, and select Web App.

   

3. On the Basics tab of the Create Web App page, provide the following information:

   • Name: Enter a unique name for the web app.
   • Publish: Select Container.
   • Operating System: Select Linux.
   • Region: Select the same region you chose for azd provision.
   • Linux Plan: Select the provided (New) App Service plan.

   

4. Leave the rest of the settings as they are, and select the Container tab at the top of the page.

5. On the Container tab, provide the following information:

   • Sidecar support: Set to Enhanced configuration with sidecar support on.
   • Image Source: Select Azure Container Registry.
   • Name: Make sure main appears.
   • Registry: Select the registry created by azd provision.
   • Authentication: Select Managed identity.
   • Identity: Select the managed identity created by azd provision.
   • Image: Enter nginx.
   • Tag: Enter latest.
   • Port: Enter 80 if not already set.

   

   Note

   These settings are configured differently in sidecar-enabled apps than in apps not enabled for sidecars. For more information, see What are the differences for sidecar-enabled custom containers.

6. Select Review + create, and when validation passes, select Create.

7. Once the deployment completes, select Go to resource.

8. On your app's page, open the URL next to Default domain, https://<app-name>.azurewebsites.net, in a new browser tab to see the default nginx page.

3. Add a sidecar container to the app

Add a sidecar container to your Linux custom container app.

1. On the app's page in the Azure portal, select Deployment Center under Deployment in the left navigation menu. The Deployment Center page shows all the containers in the app, currently only the main container.

2. Select Add > Custom container.

3. On the Add container pane, complete the following information:

   • Name: Enter otel-collector.
   • Image source: Select Azure Container Registry.
   • Registry: Select the registry created by azd provision.
   • Authentication: Select Managed Identity.
   • Identity: Under User assigned, select the managed identity created by azd provision.
   • Image: Enter otel-collector.
   • Image tag: Enter latest.
   • Port: Enter 4317.

4. Select Apply.

   

There are now two containers in the deployment center labeled Main and Sidecar. An app must have one main container and can have multiple sidecar containers.

4. Configure environment variables

In the sample scenario, the otel-collector sidecar is configured to export the OpenTelemetry data to Azure Monitor using the connection string as an environment variable. For more information, see the OpenTelemetry configuration file for the otel-collector image.

Configure the environment variable for the container by configuring app settings for the app. App settings are accessible to all the containers in the app.

1. On the app's page in the Azure portal, select Environment variables under Settings in the left navigation menu.

2. On the App settings tab of the Environment variables page, select Add.

3. On the Add/Edit application setting pane, enter the following values:

   • Name: APPLICATIONINSIGHTS_CONNECTION_STRING
   • Value: The value of APPLICATIONINSIGHTS_CONNECTION_STRING from the output of azd provision. You can also find this value as Connection String on the Overview page of the resource group's Application Insight resource.

4. Select Apply, then select Apply again, and then select Confirm. The APPLICATIONINSIGHTS_CONNECTION_STRING app setting now appears on the App settings tab.

   

Note

Some app settings don't apply to sidecar-enabled apps. For more information, see What are the differences for sidecar-enabled custom containers.

5. Verify in Application Insights

The otel-collector sidecar should now export data to Application Insights.

1. Go to your app in a new browser tab and refresh the page a few times to generate some web requests.

2. On the resource group page in the Azure portal, select the Application Insights resource. You should now see some data in the default charts on the Application Insights Overview page.

   

Note

In this common monitoring scenario, Application Insights is just one of the OpenTelemetry targets you can use, such as Jaeger, Prometheus, and Zipkin.

6. Clean up resources

When you no longer need the environment you created for this tutorial, you can delete the resource group, which removes the app service and all related resources. Run the following command in the cloned repository in Cloud Shell.

azd down

Frequently asked questions

• What are the differences for sidecar-enabled custom containers?
• How do sidecar containers handle internal communication?
• Can a sidecar container receive internet requests?
• How do I use volume mounts?

What are the differences for sidecar-enabled custom containers?

Sidecar-enabled apps are configured differently than apps that aren't sidecar-enabled.

• Sidecar-enabled apps are designated by LinuxFxVersion=sitecontainers and configured with sitecontainers resources.
• Apps that aren't sidecar enabled configure the container name and type directly with LinuxFxVersion=DOCKER|<image-details>.

For more information, see az webapp config set --linux-fx-version.

Apps that aren't sidecar-enabled configure the main container with app settings such as:

• DOCKER_REGISTRY_SERVER_URL
• DOCKER_REGISTRY_SERVER_USERNAME
• DOCKER_REGISTRY_SERVER_PASSWORD
• WEBSITES_PORT

These settings don't apply for sidecar-enabled apps.

How do sidecar containers handle internal communication?

Sidecar containers share the same network host as the main container, so the main container and other sidecar containers can reach any port on the sidecar with localhost:<port>. The example startup.sh uses localhost:4318 to access port 4318 on the otel-collector sidecar.

In the Edit container dialog, the Port setting isn't currently used by App Service. You can use it as part of the sidecar metadata, such as to indicate which port the sidecar is listening to.

Can a sidecar container receive internet requests?

No. App Service routes internet requests only to the main container. For code-based Linux apps, the built-in Linux container is the main container, and any sidecar sitecontainers should be added with IsMain=false.

For custom containers, all except one of the sitecontainers should have IsMain=false. For more information on configuring IsMain, see Microsoft.Web sites/sitecontainers.

How do I use volume mounts?

The volume mounts feature lets you share non-persistent files and directories between containers within your web app. To add or configure volume mounts, use Volume mounts on the Add container or Edit container page.

• Volume sub path is an automatically created logical directory path that isn't referenced within the container. Containers that are configured with the same volume sub path can share files and directories.
• Container mount path is a directory path that you reference within the container. The container mount path is mapped to the volume sub path.

For example, suppose you configure the following volume mounts:

Sidecar name	Volume sub path	Container mount path	Read-only
Container1	/directory1/directory2	/container1Vol	False
Container2	/directory1/directory2	/container2Vol	True
Container3	/directory1/directory2/directory3	/container3Vol	False
Container4	/directory4	/container1Vol	False

Based on these settings, the following conditions apply:

• If Container1 creates /container1Vol/myfile.txt, Container2 can read the file via /container2Vol/myfile.txt.
• If Container1 creates /container1Vol/directory3/myfile.txt, Container2 can read the file via /container2Vol/directory3/myfile.txt, and Container3 can read and write to the file via /container3Vol/myfile.txt.
• Container4 doesn't share a volume mount in common with any of the other containers.

Note

For code-based Linux apps, the built-in Linux container can't use volume mounts.

Related resources

• Configure custom container
• REST API: Web Apps - Create Or Update Site Container
• Infrastructure as Code: Microsoft.Web sites/sitecontainers
• Deploy custom containers with GitHub Actions