Skip to content

Commit 17874d4

Browse files
JillGrant615JillGrant615
authored
Merge pull request #286927 from fangjian0423/aca-debug-console
ACA add debug console
2 parents 942c738 + a770f3d commit 17874d4

File tree

3 files changed

+175
-0
lines changed

3 files changed

+175
-0
lines changed

‎articles/container-apps/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,8 @@
184184
href: log-streaming.md
185185
- name: Container console
186186
href: container-console.md
187+
- name: Container debug console
188+
href: container-debug-console.md
187189
- name: Metrics
188190
href: metrics.md
189191
- name: Log monitoring

‎articles/container-apps/container-console.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ ms.author: cshoe
1515

1616
Connecting to a container's console is useful when you want to troubleshoot your application inside a container. Azure Container Apps allows you to connect to a container's console using the Azure portal or Azure CLI.
1717

18+
> [!NOTE]
19+
> Azure Container Apps platform offers a [debug console](container-debug-console.md) to help you troubleshoot your applications if your applications use containers that only include your application and its runtime dependencies, or a "distroless" image.
20+
1821
## Azure portal
1922

2023
To connect to a container's console in the Azure portal, follow these steps.

‎articles/container-apps/container-debug-console.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: Connect to a container debug console in Azure Container Apps
3+
description: Connect to a container debug console in your container app.
4+
services: container-apps
5+
author: fangjian0423
6+
ms.service: azure-container-apps
7+
ms.custom: devx-track-azurecli
8+
ms.topic: how-to
9+
ms.date: 09/18/2024
10+
ms.author: fangjimmy
11+
---
12+
13+
14+
# Connect to a container debug console in Azure Container Apps
15+
16+
Azure Container Apps platform offers a debugging console to help you troubleshoot your application under the following circumstances:
17+
18+
- 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.
19+
- When encounter networking issues, your images don't have debugging utilities to investigate them.
20+
21+
You can connect to debug console using the Azure CLI.
22+
23+
> [!NOTE]
24+
> 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.
25+
26+
## Azure CLI
27+
28+
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**.
29+
30+
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.
31+
32+
# [Bash](#tab/bash)
33+
34+
```azurecli
35+
az containerapp debug \
36+
--name <CONTAINER_APP_NAME> \
37+
--resource-group <RESOURCE_GROUP>
38+
```
39+
40+
# [PowerShell](#tab/powershell)
41+
42+
```azurecli
43+
az containerapp debug `
44+
--name <CONTAINER_APP_NAME> `
45+
--resource-group <RESOURCE_GROUP>
46+
```
47+
48+
---
49+
50+
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.
51+
52+
| Argument | Description |
53+
|----------|-------------|
54+
| `--revision` | The revision name of the container to debug. |
55+
| `--replica` | The replica name of the container to debug. |
56+
| `--container` | The container name of the container to debug. |
57+
58+
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.
59+
60+
# [Bash](#tab/bash)
61+
62+
```azurecli
63+
az containerapp revision list \
64+
--name <CONTAINER_APP_NAME> \
65+
--resource-group <RESOURCE_GROUP> \
66+
--query "[].name"
67+
```
68+
69+
# [PowerShell](#tab/powershell)
70+
71+
```azurecli
72+
az containerapp revision list `
73+
--name <CONTAINER_APP_NAME> `
74+
--resource-group <RESOURCE_GROUP> `
75+
--query "[].name"
76+
```
77+
78+
---
79+
80+
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.
81+
82+
# [Bash](#tab/bash)
83+
84+
```azurecli
85+
az containerapp replica list \
86+
--name <CONTAINER_APP_NAME> \
87+
--resource-group <RESOURCE_GROUP> \
88+
--revision <REVISION_NAME> \
89+
--query "[].{Containers:properties.containers[].name, Name:name}"
90+
```
91+
92+
# [PowerShell](#tab/powershell)
93+
94+
```azurecli
95+
az containerapp replica list `
96+
--name <CONTAINER_APP_NAME> `
97+
--resource-group <RESOURCE_GROUP> `
98+
--revision <REVISIONNAME> `
99+
--query "[].{Containers:properties.containers[].name, Name:name}"
100+
```
101+
102+
---
103+
104+
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.
105+
106+
# [Bash](#tab/bash)
107+
108+
```azurecli
109+
az containerapp debug \
110+
--name <CONTAINER_APP_NAME> \
111+
--resource-group <RESOURCE_GROUP> \
112+
--revision <REVISION_NAME> \
113+
--replica <REPLICA_NAME> \
114+
--container <CONTAINER_NAME>
115+
```
116+
117+
# [PowerShell](#tab/powershell)
118+
119+
```azurecli
120+
az containerapp debug `
121+
--name <CONTAINER_APP_NAME> `
122+
--resource-group <RESOURCE_GROUP> `
123+
--revision <REVISION_NAME> `
124+
--replica <REPLICA_NAME> `
125+
--container <CONTAINER_NAME>
126+
```
127+
128+
---
129+
130+
## Built-in tools in Debug Console
131+
132+
The following diagnostic tools are preinstalled to the debug console to help you troubleshoot issues:
133+
134+
- [ip-utils](https://github.com/iputils/iputils)
135+
- [net-tools](https://github.com/ecki/net-tools)
136+
- [procps](https://github.com/warmchang/procps)
137+
- [lsof](https://github.com/lsof-org/lsof)
138+
- [util-linux](https://github.com/util-linux/util-linux)
139+
- [nc](https://en.wikipedia.org/wiki/Netcat)
140+
- [wget](https://github.com/mirror/wget)
141+
- [openssl](https://github.com/openssl/openssl)
142+
- [traceroute](https://en.wikipedia.org/wiki/Traceroute)
143+
- [ca-certificates](https://fedoraproject.org/wiki/CA-Certificates)
144+
- [bind-utils](https://www.linuxfromscratch.org/~ken/inkscape-python-deps/blfs-book-sysv/basicnet/bind-utils.html)
145+
- [tcpping](http://www.vdberg.org/~richard/tcpping.html)
146+
147+
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.
148+
149+
For example, install JDK in the debug console using the following command:
150+
151+
```bash
152+
tdnf install -y msopenjdk-17
153+
```
154+
155+
---
156+
157+
## Scenario - Accessing container's file system via Debug Console
158+
159+
By default, debug console runs as root user.
160+
161+
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.
162+
163+
```bash
164+
switch-to-app-user
165+
```
166+
167+
---
168+
169+
> [!div class="nextstepaction"]
170+
> [View log streams from the Azure portal](log-streaming.md)

0 commit comments

Comments
 (0)