Edit

Share via

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

  • Article

In this tutorial, you add an OpenTelemetry collector as a sidecar container to a Linux custom container app in Azure App Service. For bring-your-own-code Linux apps, see Tutorial: Configure a sidecar container for a Linux app in Azure App Service.

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

What's a sidecar container?

In Azure App Service, you can add up to nine sidecar containers for each Linux app. Sidecar containers let you deploy extra services and features to your Linux apps without making them tightly coupled to the main container (built-in or custom). For example, you can add monitoring, logging, configuration, and networking services as sidecar containers. An OpenTelemetry collector sidecar is one such monitoring example.

The sidecar containers run alongside the main application container in the same App Service plan.

1. Set up the needed resources

First you create the resources that the tutorial uses. They're used for this particular scenario and aren't required for sidecar containers in general.

  1. In the Azure Cloud Shell, run the following commands:

    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

  2. When prompted, supply the subscription and region you want. For example:

    • Subscription: Your subscription.
    • Region: (Europe) West Europe.

    When deployment completes, you should see the following output:

     APPLICATIONINSIGHTS_CONNECTION_STRING = InstrumentationKey=...;IngestionEndpoint=...;LiveEndpoint=...

 Open resource group in the portal: https://portal.azure.com/#@/resource/subscriptions/.../resourceGroups/...

  3. Open the resource group link in a browser tab. You'll need to use the connection string later.

    Note

    azd provision uses the included templates to create the following Azure resources:

2. Create a sidecar-enabled app

  1. In the resource group's management page, select Create.

  2. Search for web app, then select the down arrow on Create and select Web App.

    Screenshot showing the Azure Marketplace page with the web app being searched and create web app buttons being clicked.

  3. Configure the Basics panel as follows:

    • Name: A unique name
    • Publish: Container
    • Operating System: Linux
    • Region: Same region as the one you chose with azd provision
    • Linux Plan: A new App Service plan

    Screenshot showing the web app create wizard and settings for a Linux custom container app highlighted.

  4. Select Container. Configure the Container panel as follows:

    • Sidecar support: Enabled
    • Image Source: Azure Container Registry
    • Registry: The registry created by azd provision
    • Image: nginx
    • Tag: latest
    • Port: 80

    Screenshot showing the web app create wizard and settings for the container image and the sidecar support highlighted.

    Note

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

  5. Select Review + create, then select Create.

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

  7. In a new browser tab, navigate to https://<app-name>.azurewebsites.net and see the default Nginx page.

3. Add a sidecar container

In this section, you add a sidecar container to your custom container app.

  1. In the app's management page, from the left menu, select Deployment Center.

    The deployment center shows you all the containers in the app. Right now, it only has the main container.

  2. Select Add and configure the new container as follows:

    • Name: otel-collector
    • Image source: Azure Container Registry
    • Registry: The registry created by azd provision
    • Image: otel-collector
    • Tag: latest

  3. Select Apply.

    Screenshot showing how to configure a sidecar container in a web app's deployment center.

    You should now see two containers in the deployment center. The main container is marked Main, and the sidecar container is marked Sidecar. Each app must have one main container but can have multiple sidecar containers.

4. Configure environment variables

For the sample scenario, the otel-collector sidecar is configured to export the OpenTelemetry data to Azure Monitor, but it needs the connection string as an environment variable (see the OpenTelemetry configuration file for the otel-collector image).

You configure environment variables for the containers like any App Service app, by configuring app settings. The app settings are accessible to all the containers in the app.

  1. In the app's management page, from the left menu, select Environment variables.

  2. Add an app setting by selecting Add and configure it as follows:

    • Name: APPLICATIONINSIGHTS_CONNECTION_STRING
    • Value: The connection string in the output of azd provision. If you lost the Cloud Shell session, you can also find it in the Overview page of the Application Insight resource, under Connection String.

  3. Select Apply, then Apply, then Confirm.

    Screenshot showing a web app's Configuration page with two app settings added.

Note

Certain 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 export data to Application Insights now.

  1. Back in the browser tab for https://<app-name>.azurewebsites.net, refresh the page a few times to generate some web requests.

  2. Go back to the resource group overview page, then select the Application Insights resource. You should now see some data in the default charts.

    Screenshot of the Application Insights page showing data in the default charts.

Note

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

Clean up resources

When you no longer need the environment, you can delete the resource group, App service, and all related resources. Just run this command in the Cloud Shell, in the cloned repository:

azd down

Frequently asked questions

What are the differences for sidecar-enabled custom containers?

You configure sidecar-enabled apps differently than apps that aren't sidecar-enabled.

Not sidecar-enabled

  • Container name and types are configured directly with LinuxFxVersion=DOCKER|<image-details> (see az webapp config set --linux-fx-version).
  • The main container is configured with app settings, such as:
    • DOCKER_REGISTRY_SERVER_URL
    • DOCKER_REGISTRY_SERVER_USERNAME
    • DOCKER_REGISTRY_SERVER_PASSWORD
    • WEBSITES_PORT

Sidecar-enabled

  • A sidecar-enabled app is designated by LinuxFxVersion=sitecontainers (see az webapp config set --linux-fx-version).
  • The main container is configured with a sitecontainers resource. These settings don't apply for sidecar-enabled apps
    • DOCKER_REGISTRY_SERVER_URL
    • DOCKER_REGISTRY_SERVER_USERNAME
    • DOCKER_REGISTRY_SERVER_PASSWORD
    • WEBSITES_PORT

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 box 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 container (sitecontainers) should be added with IsMain=false. For custom containers, all but one of the sitecontainers should have IsMain=false.

For more information on configuring IsMain, see Microsoft.Web sites/sitecontainers.

More resources