Edit

Share via

Connect to a container debug console in Azure Container Apps

  • Article

Azure Container Apps platform offers a debugging console to help you troubleshoot your application under the following circumstances:

  • You can't connect to the target container when you use a container that only includes the application and its runtime dependencies, or a "distroless" image.
  • When encounter networking issues, your images don't have debugging utilities to investigate them.

You can connect to debug console using the Azure CLI.

Note

The debug console creates a separate container, which shares the underlying resources with the container where your app is running. If a debug container already exists, the debug console reuses the existing one instead of creating a new one. There is at most one running debug container per container app replica. If you don't need to keep a debug container running, enter exit or use Ctrl/Cmd + D in the debug console session.

Azure CLI

To connect to a container the debug console, use the az containerapp debug command. To exit the console, enter exit or use Ctrl/Cmd + D.

For example, connect to a container debug console in a container app with a single container using the following command. Before you run this command, replace the <PLACEHOLDERS> with your container app's values.

az containerapp debug \
  --name <CONTAINER_APP_NAME> \
  --resource-group <RESOURCE_GROUP>

To connect to a container debug console in a container app with multiple revisions, replicas, and containers, include the following parameters in the az containerapp debug command.

Argument Description
--revision The revision name of the container to debug.
--replica The replica name of the container to debug.
--container The container name of the container to debug.

You can get the revision names with the az containerapp revision list command. Before you run this command, replace the <PLACEHOLDERS> with your container app's values.

az containerapp revision list \
  --name <CONTAINER_APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --query "[].name"

Use the az containerapp replica list command to get the replica and container names. Before you run this command, replace the <PLACEHOLDERS> with your container app's values.

az containerapp replica list \
  --name <CONTAINER_APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --revision <REVISION_NAME> \
  --query "[].{Containers:properties.containers[].name, Name:name}"

Connect to the container debug console with the az containerapp debug command. Before you run this command, replace the <PLACEHOLDERS> with your container app's values.

az containerapp debug \
  --name <CONTAINER_APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --revision <REVISION_NAME> \
  --replica <REPLICA_NAME> \
  --container <CONTAINER_NAME>

Built-in tools in Debug Console

The following diagnostic tools are preinstalled to the debug console to help you troubleshoot issues:

If you want to install other tools, run the tdnf install -y <TOOL_NAME> command. Before you run this command, replace the <PLACEHOLDERS> with your container app's values.

For example, install JDK in the debug console using the following command:

tdnf install -y msopenjdk-17

Scenario - Accessing container's file system via Debug Console

By default, debug console runs as root user.

You can access /proc/1 to access container's file system if your container runs as root user. If your container doesn't run as root user, run below command to switch user before accessing /proc/1 directory, or you'll get a permission denied error.

switch-user

View log streams from the Azure portal