Connect to a container debug console in Azure Container Apps
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:
- ip-utils
- net-tools
- procps
- lsof
- util-linux
- nc
- wget
- openssl
- traceroute
- ca-certificates
- bind-utils
- tcpping
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-to-app-user