debug 调试运行中的 Pod

Kubernetes

在 pod 运行的时候，除了可以通过kubectl describe pod查看 pod 的事件信息，或者通过kubectl exec外，还可以通过临时容器来进行调试。

使用临时容器来调试

可以使用 kubectl debug 命令来给正在运行中的 Pod 增加一个临时容器。首先，像示例一样创建一个 pod：

kubectl run ephemeral-demo --image=registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.9 --restart=Never

本节示例中使用 pause 容器镜像，因为它不包含调试程序，但是这个方法适用于所有容器镜像。
如果你尝试使用 kubectl exec 来创建一个 shell，你将会看到一个错误，因为这个容器镜像中没有 shell：

kubectl exec -it ephemeral-demo -- sh

error: Internal error occurred: error executing command in container: failed to exec in container: failed to start exec "eaa129200e2fb3b4657385eb0d612c0152abde700e448e037d2999049f1390c2": OCI runtime exec failed: exec failed: unable to start container process: exec: "sh": executable file not found in $PATH: unknown

你可以改为使用 kubectl debug 添加调试容器。如果你指定 -i 或者 --interactive 参数，kubectl 将自动挂接到临时容器的控制台。

kubectl debug -it ephemeral-demo --image=busybox:1.28 --target=ephemeral-demo

Targeting container "ephemeral-demo". If you don't see processes from this container it may be because the container runtime doesn't support this feature.
Defaulting debug container name to debugger-gw5rl.
If you don't see a command prompt, try pressing enter.
/ # ps
PID   USER     TIME  COMMAND
    1 65535     0:00 /pause
   13 root      0:00 sh
   19 root      0:00 ps

此命令添加一个新的 busybox 容器并将其挂接到该容器。--target 参数指定另一个容器的进程命名空间。这个指定进程命名空间的操作是必需的，因为 kubectl run 不能在它创建的 Pod 中启用共享进程命名空间。

说明：

容器运行时必须支持 --target 参数。如果不支持，则临时容器可能不会启动，或者可能使用隔离的进程命名空间启动，导致 ps 不显示其他容器内的进程。

你可以使用 kubectl describe 查看新创建的临时容器的状态：

kubectl describe pod ephemeral-demo

...
Ephemeral Containers:
  debugger-gw5rl:
    Container ID:   containerd://ce0846df818cd209fc4d16caa69886f91cb92ed740c96040cc4a0f1e3494db5a
    Image:          busybox:1.28
    Image ID:       docker.io/library/busybox@sha256:58ac43b2cc92c687a32c8be6278e50a063579655fe3090125dcb2af0ff9e1a64
    Port:           <none>
    Host Port:      <none>
    State:          Running
      Started:      Sun, 14 Jul 2024 23:24:40 +0800
    Ready:          False
    Restart Count:  0
    Environment:    <none>
    Mounts:         <none>
...

使用 kubectl delete 来移除已经结束掉的 Pod：

kubectl delete pod ephemeral-demo

通过 Pod 副本调试

有些时候 Pod 的配置参数使得在某些情况下很难执行故障排查。例如，在容器镜像中不包含 shell 或者你的应用程序在启动时崩溃的情况下，就不能通过运行 kubectl exec 来排查容器故障。在这些情况下，你可以使用 kubectl debug 来创建 Pod 的副本，通过更改配置帮助调试。

在添加新的容器时创建 Pod 副本

当应用程序正在运行但其表现不符合预期时，你会希望在 Pod 中添加额外的调试工具，这时添加新容器是很有用的。
例如，应用的容器镜像是建立在 busybox 的基础上，但是你需要 busybox 中并不包含的调试工具。你可以使用 kubectl run 模拟这个场景:

kubectl run myapp --image=busybox:1.28 --restart=Never -- sleep 1d

通过运行以下命令，建立 myapp 的一个名为 myapp-debug 的副本，新增了一个用于调试的 Ubuntu 容器：

kubectl debug myapp -it --image=ubuntu --share-processes --copy-to=myapp-debug

Defaulting debug container name to debugger-xzqqt.
If you don't see a command prompt, try pressing enter.
root@myapp-debug:/# ps axf
    PID TTY      STAT   TIME COMMAND
     13 pts/0    Ss     0:00 /bin/bash
     21 pts/0    R+     0:00  \_ ps axf
      7 ?        Ss     0:00 sleep 1d
      1 ?        Ss     0:00 /pause

说明：

如果你没有使用 --container 指定新的容器名，kubectl debug 会自动生成的。

默认情况下，-i 标志使 kubectl debug 附加到新容器上。你可以通过指定 --attach=false 来防止这种情况。如果你的会话断开连接，你可以使用 kubectl attach 重新连接。

--share-processes 允许在此 Pod 中的其他容器中查看该容器的进程。

通过进程共享，我们可以看到 Pod 中另一个容器内的所有内容，包括其进程和文件，这对于调试来说非常方便。如果我们从另一个终端列出正在运行的 Pod，我们将看到以下内容：

kubectl get pods

NAME                     READY   STATUS    RESTARTS   AGE
myapp                    1/1     Running   0          2m12s
myapp-debug              2/2     Running   0          6s

这就是我们在原始应用程序 Pod 上的新调试 Pod。与原始容器相比，它有 2 个容器，因为它还包括临时容器。

kubectl get pod myapp-debug -o jsonpath='{.spec.containers[*].name}'

myapp debugger-2qfss

此外，如果想在任何时候验证 Pod 中是否允许进程共享，那么可以运行：

kubectl get pod myapp-debug -o jsonpath='{.spec.shareProcessNamespace}'

true

清理调试 Pod：

kubectl delete pod myapp myapp-debug

在改变 Pod 命令时创建 Pod 副本

有时更改容器的命令很有用，例如添加调试标志或因为应用崩溃。
为了模拟应用崩溃的场景，使用 kubectl run 命令创建一个立即退出的容器：

kubectl run --image=busybox:1.28 myapp -- false

使用 kubectl describe pod myapp 命令，你可以看到容器崩溃了：

...
Containers:
  myapp:
    Image:         busybox:1.28
    ...
    Args:
      false
    State:          Terminated
      Reason:       Error
      Exit Code:    1
    Last State:     Terminated
      Reason:       Error
      Exit Code:    1

你可以使用 kubectl debug 命令创建该 Pod 的一个副本，在该副本中命令改变为交互式 shell：

kubectl debug myapp -it --copy-to=myapp-debug --container=myapp -- sh

If you don't see a command prompt, try pressing enter.
/ #

现在你有了一个可以执行类似检查文件系统路径或者手动运行容器命令的交互式 shell。

说明：

要更改指定容器的命令，你必须用 --container 命令指定容器的名字，否则 kubectl debug 将建立一个新的容器运行你指定的命令。

默认情况下，标志 -i 使 kubectl debug 附加到容器。你可通过指定 --attach=false 来防止这种情况。如果你的断开连接，可以使用 kubectl attach 重新连接。

清理调试 Pod：

kubectl delete pod myapp myapp-debug

在更改容器镜像时拷贝 Pod

在某些情况下，你可能想要改动一个行为异常的 Pod，即从其正常的生产容器镜像更改为包含调试构建程序或其他实用程序的镜像。
下面的例子，用 kubectl run 创建一个 Pod：

kubectl run myapp --image=busybox:1.28 --restart=Never -- sleep 1d

现在可以使用 kubectl debug 创建一个拷贝并将其容器镜像更改为 ubuntu：

kubectl debug myapp --copy-to=myapp-debug --set-image=*=ubuntu

--set-image 与 container_name=image 使用相同的 kubectl set image 语法。 *=ubuntu 表示把所有容器的镜像改为 ubuntu。
执行kubectl exec -it myapp-debug -- bash进入 bash 环境查看容器：

root@myapp-debug:/# cat /etc/issue
Ubuntu Oracular Oriole (development branch) \n \l

root@myapp-debug:/# ps ax
    PID TTY      STAT   TIME COMMAND
      1 ?        Ss     0:00 sleep 1d
      6 pts/0    Ss     0:00 bash
     16 pts/0    R+     0:00 ps ax

在节点上通过 shell 来进行调试

如果这些方法都不起作用，你可以找到运行 Pod 的节点，然后创建一个 Pod 运行在该节点上。你可以通过 kubectl debug 在节点上创建一个交互式 Shell：

kubectl debug node/mynode -it --image=ubuntu

Creating debugging pod node-debugger-k8s-kdwsm with container debugger on node k8s.
If you don't see a command prompt, try pressing enter.
root@mynode:/# chroot /host
sh-4.4# ls /etc/kubernetes/manifests/
etcd.yaml  kube-apiserver.yaml	kube-controller-manager.yaml  kube-scheduler.yaml

当在节点上创建调试会话，注意以下要点：

kubectl debug 基于节点的名字自动生成新的 Pod 的名字。
节点的根文件系统会被挂载在 /host。
新的调试容器运行在主机 IPC 名字空间、主机网络名字空间以及主机 PID 名字空间内， Pod 没有特权，因此读取某些进程信息可能会失败，并且 chroot /host 也可能会失败。
如果你需要一个特权 Pod，需要手动创建或使用 --profile=sysadmin 标志。

当你完成节点调试时，不要忘记清理调试 Pod：

kubectl delete pod node-debugger-mynode-kdwsm

参考https://kubernetes.io/zh-cn/docs/tasks/debug/debug-application/debug-running-pod/

如果觉得文章对你有用，请随意赞赏

Kubernetes Debug