调试运行中的 Pod

本页解释如何在节点上调试运行中(或崩溃)的 Pod。

准备开始

  • 你的 Pod 应该已经被调度并正在运行中, 如果你的 Pod 还没有运行,请参阅调试 Pod

  • 对于一些高级调试步骤,你应该知道 Pod 具体运行在哪个节点上,并具有在该节点上运行命令的 shell 访问权限。 你不需要任何访问权限就可以使用 kubectl 去运行一些标准调试步骤。

使用 kubectl describe pod 命令获取 Pod 详情

与之前的例子类似,我们使用一个 Deployment 来创建两个 Pod。

application/nginx-with-request.yaml调试运行中的 Pod - 图1

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4. name: nginx-deployment
  5. spec:
  6. selector:
  7. matchLabels:
  8. app: nginx
  9. replicas: 2
  10. template:
  11. metadata:
  12. labels:
  13. app: nginx
  14. spec:
  15. containers:
  16. - name: nginx
  17. image: nginx
  18. resources:
  19. limits:
  20. memory: "128Mi"
  21. cpu: "500m"
  22. ports:
  23. - containerPort: 80

使用如下命令创建 Deployment:

  1. kubectl apply -f https://k8s.io/examples/application/nginx-with-request.yaml
  1. deployment.apps/nginx-deployment created

使用如下命令查看 Pod 状态:

  1. kubectl get pods
  1. NAME READY STATUS RESTARTS AGE
  2. nginx-deployment-67d4bdd6f5-cx2nz 1/1 Running 0 13s
  3. nginx-deployment-67d4bdd6f5-w6kd7 1/1 Running 0 13s

我们可以使用 kubectl describe pod 命令来查询每个 Pod 的更多信息,比如:

  1. kubectl describe pod nginx-deployment-67d4bdd6f5-w6kd7
  1. Name: nginx-deployment-67d4bdd6f5-w6kd7
  2. Namespace: default
  3. Priority: 0
  4. Node: kube-worker-1/192.168.0.113
  5. Start Time: Thu, 17 Feb 2022 16:51:01 -0500
  6. Labels: app=nginx
  7. pod-template-hash=67d4bdd6f5
  8. Annotations: <none>
  9. Status: Running
  10. IP: 10.88.0.3
  11. IPs:
  12. IP: 10.88.0.3
  13. IP: 2001:db8::1
  14. Controlled By: ReplicaSet/nginx-deployment-67d4bdd6f5
  15. Containers:
  16. nginx:
  17. Container ID: containerd://5403af59a2b46ee5a23fb0ae4b1e077f7ca5c5fb7af16e1ab21c00e0e616462a
  18. Image: nginx
  19. Image ID: docker.io/library/nginx@sha256:2834dc507516af02784808c5f48b7cbe38b8ed5d0f4837f16e78d00deb7e7767
  20. Port: 80/TCP
  21. Host Port: 0/TCP
  22. State: Running
  23. Started: Thu, 17 Feb 2022 16:51:05 -0500
  24. Ready: True
  25. Restart Count: 0
  26. Limits:
  27. cpu: 500m
  28. memory: 128Mi
  29. Requests:
  30. cpu: 500m
  31. memory: 128Mi
  32. Environment: <none>
  33. Mounts:
  34. /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-bgsgp (ro)
  35. Conditions:
  36. Type Status
  37. Initialized True
  38. Ready True
  39. ContainersReady True
  40. PodScheduled True
  41. Volumes:
  42. kube-api-access-bgsgp:
  43. Type: Projected (a volume that contains injected data from multiple sources)
  44. TokenExpirationSeconds: 3607
  45. ConfigMapName: kube-root-ca.crt
  46. ConfigMapOptional: <nil>
  47. DownwardAPI: true
  48. QoS Class: Guaranteed
  49. Node-Selectors: <none>
  50. Tolerations: node.kubernetes.io/not-ready:NoExecute op=Exists for 300s
  51. node.kubernetes.io/unreachable:NoExecute op=Exists for 300s
  52. Events:
  53. Type Reason Age From Message
  54. ---- ------ ---- ---- -------
  55. Normal Scheduled 34s default-scheduler Successfully assigned default/nginx-deployment-67d4bdd6f5-w6kd7 to kube-worker-1
  56. Normal Pulling 31s kubelet Pulling image "nginx"
  57. Normal Pulled 30s kubelet Successfully pulled image "nginx" in 1.146417389s
  58. Normal Created 30s kubelet Created container nginx
  59. Normal Started 30s kubelet Started container nginx

在这里,你可以看到有关容器和 Pod 的配置信息(标签、资源需求等), 以及有关容器和 Pod 的状态信息(状态、就绪、重启计数、事件等)。

容器状态是 Waiting、Running 和 Terminated 之一。 根据状态的不同,还有对应的额外的信息 —— 在这里你可以看到, 对于处于运行状态的容器,系统会告诉你容器的启动时间。

Ready 指示是否通过了最后一个就绪态探测。 (在本例中,容器没有配置就绪态探测;如果没有配置就绪态探测,则假定容器已经就绪。)

Restart Count 告诉你容器已重启的次数; 这些信息对于定位配置了 “Always” 重启策略的容器持续崩溃问题非常有用。

目前,唯一与 Pod 有关的状态是 Ready 状况,该状况表明 Pod 能够为请求提供服务, 并且应该添加到相应服务的负载均衡池中。

最后,你还可以看到与 Pod 相关的近期事件。 “From” 标明记录事件的组件, “Reason” 和 “Message” 告诉你发生了什么。

例子: 调试 Pending 状态的 Pod

可以使用事件来调试的一个常见的场景是,你创建 Pod 无法被调度到任何节点。 比如,Pod 请求的资源比较多,没有任何一个节点能够满足,或者它指定了一个标签,没有节点可匹配。 假定我们创建之前的 Deployment 时指定副本数是 5(不再是 2),并且请求 600 毫核(不再是 500), 对于一个 4 个节点的集群,若每个节点只有 1 个 CPU,这时至少有一个 Pod 不能被调度。 (需要注意的是,其他集群插件 Pod,比如 fluentd、skydns 等等会在每个节点上运行, 如果我们需求 1000 毫核,将不会有 Pod 会被调度。)

  1. kubectl get pods
  1. NAME READY STATUS RESTARTS AGE
  2. nginx-deployment-1006230814-6winp 1/1 Running 0 7m
  3. nginx-deployment-1006230814-fmgu3 1/1 Running 0 7m
  4. nginx-deployment-1370807587-6ekbw 1/1 Running 0 1m
  5. nginx-deployment-1370807587-fg172 0/1 Pending 0 1m
  6. nginx-deployment-1370807587-fz9sd 0/1 Pending 0 1m

为了查找 Pod nginx-deployment-1370807587-fz9sd 没有运行的原因,我们可以使用 kubectl describe pod 命令描述 Pod,查看其事件:

  1. kubectl describe pod nginx-deployment-1370807587-fz9sd
  1. Name: nginx-deployment-1370807587-fz9sd
  2. Namespace: default
  3. Node: /
  4. Labels: app=nginx,pod-template-hash=1370807587
  5. Status: Pending
  6. IP:
  7. Controllers: ReplicaSet/nginx-deployment-1370807587
  8. Containers:
  9. nginx:
  10. Image: nginx
  11. Port: 80/TCP
  12. QoS Tier:
  13. memory: Guaranteed
  14. cpu: Guaranteed
  15. Limits:
  16. cpu: 1
  17. memory: 128Mi
  18. Requests:
  19. cpu: 1
  20. memory: 128Mi
  21. Environment Variables:
  22. Volumes:
  23. default-token-4bcbi:
  24. Type: Secret (a volume populated by a Secret)
  25. SecretName: default-token-4bcbi
  26. Events:
  27. FirstSeen LastSeen Count From SubobjectPath Type Reason Message
  28. --------- -------- ----- ---- ------------- -------- ------ -------
  29. 1m 48s 7 {default-scheduler } Warning FailedScheduling pod (nginx-deployment-1370807587-fz9sd) failed to fit in any node
  30. fit failure on node (kubernetes-node-6ta5): Node didn't have enough resource: CPU, requested: 1000, used: 1420, capacity: 2000
  31. fit failure on node (kubernetes-node-wul5): Node didn't have enough resource: CPU, requested: 1000, used: 1100, capacity: 2000

这里你可以看到由调度器记录的事件,它表明了 Pod 不能被调度的原因是 FailedScheduling(也可能是其他值)。 其 message 部分表明没有任何节点拥有足够多的资源。

要纠正这种情况,可以使用 kubectl scale 更新 Deployment,以指定 4 个或更少的副本。 (或者你可以让 Pod 继续保持这个状态,这是无害的。)

你在 kubectl describe pod 结尾处看到的事件都保存在 etcd 中, 并提供关于集群中正在发生的事情的高级信息。 如果需要列出所有事件,可使用命令:

  1. kubectl get events

但是,需要注意的是,事件是区分名字空间的。 如果你对某些名字空间域的对象(比如 my-namespace 名字下的 Pod)的事件感兴趣, 你需要显式地在命令行中指定名字空间:

  1. kubectl get events --namespace=my-namespace

查看所有 namespace 的事件,可使用 --all-namespaces 参数。

除了 kubectl describe pod 以外,另一种获取 Pod 额外信息(除了 kubectl get pod)的方法 是给 kubectl get pod 增加 -o yaml 输出格式参数。 该命令将以 YAML 格式为你提供比 kubectl describe pod 更多的信息 —— 实际上是系统拥有的关于 Pod 的所有信息。 在这里,你将看到注解(没有标签限制的键值元数据,由 Kubernetes 系统组件在内部使用)、 重启策略、端口和卷等。

  1. kubectl get pod nginx-deployment-1006230814-6winp -o yaml
  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4. creationTimestamp: "2022-02-17T21:51:01Z"
  5. generateName: nginx-deployment-67d4bdd6f5-
  6. labels:
  7. app: nginx
  8. pod-template-hash: 67d4bdd6f5
  9. name: nginx-deployment-67d4bdd6f5-w6kd7
  10. namespace: default
  11. ownerReferences:
  12. - apiVersion: apps/v1
  13. blockOwnerDeletion: true
  14. controller: true
  15. kind: ReplicaSet
  16. name: nginx-deployment-67d4bdd6f5
  17. uid: 7d41dfd4-84c0-4be4-88ab-cedbe626ad82
  18. resourceVersion: "1364"
  19. uid: a6501da1-0447-4262-98eb-c03d4002222e
  20. spec:
  21. containers:
  22. - image: nginx
  23. imagePullPolicy: Always
  24. name: nginx
  25. ports:
  26. - containerPort: 80
  27. protocol: TCP
  28. resources:
  29. limits:
  30. cpu: 500m
  31. memory: 128Mi
  32. requests:
  33. cpu: 500m
  34. memory: 128Mi
  35. terminationMessagePath: /dev/termination-log
  36. terminationMessagePolicy: File
  37. volumeMounts:
  38. - mountPath: /var/run/secrets/kubernetes.io/serviceaccount
  39. name: kube-api-access-bgsgp
  40. readOnly: true
  41. dnsPolicy: ClusterFirst
  42. enableServiceLinks: true
  43. nodeName: kube-worker-1
  44. preemptionPolicy: PreemptLowerPriority
  45. priority: 0
  46. restartPolicy: Always
  47. schedulerName: default-scheduler
  48. securityContext: {}
  49. serviceAccount: default
  50. serviceAccountName: default
  51. terminationGracePeriodSeconds: 30
  52. tolerations:
  53. - effect: NoExecute
  54. key: node.kubernetes.io/not-ready
  55. operator: Exists
  56. tolerationSeconds: 300
  57. - effect: NoExecute
  58. key: node.kubernetes.io/unreachable
  59. operator: Exists
  60. tolerationSeconds: 300
  61. volumes:
  62. - name: kube-api-access-bgsgp
  63. projected:
  64. defaultMode: 420
  65. sources:
  66. - serviceAccountToken:
  67. expirationSeconds: 3607
  68. path: token
  69. - configMap:
  70. items:
  71. - key: ca.crt
  72. path: ca.crt
  73. name: kube-root-ca.crt
  74. - downwardAPI:
  75. items:
  76. - fieldRef:
  77. apiVersion: v1
  78. fieldPath: metadata.namespace
  79. path: namespace
  80. status:
  81. conditions:
  82. - lastProbeTime: null
  83. lastTransitionTime: "2022-02-17T21:51:01Z"
  84. status: "True"
  85. type: Initialized
  86. - lastProbeTime: null
  87. lastTransitionTime: "2022-02-17T21:51:06Z"
  88. status: "True"
  89. type: Ready
  90. - lastProbeTime: null
  91. lastTransitionTime: "2022-02-17T21:51:06Z"
  92. status: "True"
  93. type: ContainersReady
  94. - lastProbeTime: null
  95. lastTransitionTime: "2022-02-17T21:51:01Z"
  96. status: "True"
  97. type: PodScheduled
  98. containerStatuses:
  99. - containerID: containerd://5403af59a2b46ee5a23fb0ae4b1e077f7ca5c5fb7af16e1ab21c00e0e616462a
  100. image: docker.io/library/nginx:latest
  101. imageID: docker.io/library/nginx@sha256:2834dc507516af02784808c5f48b7cbe38b8ed5d0f4837f16e78d00deb7e7767
  102. lastState: {}
  103. name: nginx
  104. ready: true
  105. restartCount: 0
  106. started: true
  107. state:
  108. running:
  109. startedAt: "2022-02-17T21:51:05Z"
  110. hostIP: 192.168.0.113
  111. phase: Running
  112. podIP: 10.88.0.3
  113. podIPs:
  114. - ip: 10.88.0.3
  115. - ip: 2001:db8::1
  116. qosClass: Guaranteed
  117. startTime: "2022-02-17T21:51:01Z"

检查 Pod 的日志

首先,查看受到影响的容器的日志:

  1. kubectl logs ${POD_NAME} ${CONTAINER_NAME}

如果你的容器之前崩溃过,你可以通过下面命令访问之前容器的崩溃日志:

  1. kubectl logs --previous ${POD_NAME} ${CONTAINER_NAME}

使用容器 exec 进行调试

如果 容器镜像 包含调试程序, 比如从 Linux 和 Windows 操作系统基础镜像构建的镜像,你可以使用 kubectl exec 命令 在特定的容器中运行一些命令:

  1. kubectl exec ${POD_NAME} -c ${CONTAINER_NAME} -- ${CMD} ${ARG1} ${ARG2} ... ${ARGN}

说明: -c ${CONTAINER_NAME} 是可选择的。如果 Pod 中仅包含一个容器,就可以忽略它。

例如,要查看正在运行的 Cassandra Pod 中的日志,可以运行:

  1. kubectl exec cassandra -- cat /var/log/cassandra/system.log

你可以在 kubectl exec 命令后面加上 -i-t 来运行一个连接到你的终端的 Shell,比如:

  1. kubectl exec -it cassandra -- sh

若要了解更多内容,可查看获取正在运行容器的 Shell

使用临时调试容器来进行调试

特性状态: Kubernetes v1.25 [stable]

当由于容器崩溃或容器镜像不包含调试程序(例如无发行版镜像等) 而导致 kubectl exec 无法运行时,临时容器对于排除交互式故障很有用。

使用临时容器来调试的例子

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

  1. kubectl run ephemeral-demo --image=registry.k8s.io/pause:3.1 --restart=Never

本节示例中使用 pause 容器镜像,因为它不包含调试程序,但是这个方法适用于所有容器镜像。

如果你尝试使用 kubectl exec 来创建一个 shell,你将会看到一个错误,因为这个容器镜像中没有 shell。

  1. kubectl exec -it ephemeral-demo -- sh
  1. OCI runtime exec failed: exec failed: container_linux.go:346: starting container process caused "exec: \"sh\": executable file not found in $PATH": unknown

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

  1. kubectl debug -it ephemeral-demo --image=busybox:1.28 --target=ephemeral-demo
  1. Defaulting debug container name to debugger-8xzrl.
  2. If you don't see a command prompt, try pressing enter.
  3. / #

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

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

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

  1. kubectl describe pod ephemeral-demo
  1. ...
  2. Ephemeral Containers:
  3. debugger-8xzrl:
  4. Container ID: docker://b888f9adfd15bd5739fefaa39e1df4dd3c617b9902082b1cfdc29c4028ffb2eb
  5. Image: busybox
  6. Image ID: docker-pullable://busybox@sha256:1828edd60c5efd34b2bf5dd3282ec0cc04d47b2ff9caa0b6d4f07a21d1c08084
  7. Port: <none>
  8. Host Port: <none>
  9. State: Running
  10. Started: Wed, 12 Feb 2020 14:25:42 +0100
  11. Ready: False
  12. Restart Count: 0
  13. Environment: <none>
  14. Mounts: <none>
  15. ...

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

  1. kubectl delete pod ephemeral-demo

通过 Pod 副本调试

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

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

当应用程序正在运行但其表现不符合预期时,你会希望在 Pod 中添加额外的调试工具, 这时添加新容器是很有用的。

例如,应用的容器镜像是建立在 busybox 的基础上, 但是你需要 busybox 中并不包含的调试工具。 你可以使用 kubectl run 模拟这个场景:

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

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

  1. kubectl debug myapp -it --image=ubuntu --share-processes --copy-to=myapp-debug
  1. Defaulting debug container name to debugger-w7xmf.
  2. If you don't see a command prompt, try pressing enter.
  3. root@myapp-debug:/#

说明:

  • 如果你没有使用 --container 指定新的容器名,kubectl debug 会自动生成的。
  • 默认情况下,-i 标志使 kubectl debug 附加到新容器上。 你可以通过指定 --attach=false 来防止这种情况。 如果你的会话断开连接,你可以使用 kubectl attach 重新连接。
  • --share-processes 允许在此 Pod 中的其他容器中查看该容器的进程。 参阅在 Pod 中的容器之间共享进程命名空间 获取更多信息。

不要忘了清理调试 Pod:

  1. kubectl delete pod myapp myapp-debug

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

有时更改容器的命令很有用,例如添加调试标志或因为应用崩溃。

为了模拟应用崩溃的场景,使用 kubectl run 命令创建一个立即退出的容器:

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

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

  1. Containers:
  2. myapp:
  3. Image: busybox
  4. ...
  5. Args:
  6. false
  7. State: Waiting
  8. Reason: CrashLoopBackOff
  9. Last State: Terminated
  10. Reason: Error
  11. Exit Code: 1

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

  1. kubectl debug myapp -it --copy-to=myapp-debug --container=myapp -- sh
  1. If you don't see a command prompt, try pressing enter.
  2. / #

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

说明:

  • 要更改指定容器的命令,你必须用 --container 命令指定容器的名字, 否则 kubectl debug 将建立一个新的容器运行你指定的命令。
  • 默认情况下,标志 -i 使 kubectl debug 附加到容器。 你可通过指定 --attach=false 来防止这种情况。 如果你的断开连接,可以使用 kubectl attach 重新连接。

不要忘了清理调试 Pod:

  1. kubectl delete pod myapp myapp-debug

在更改容器镜像时拷贝 Pod

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

下面的例子,用 kubectl run 创建一个 Pod:

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

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

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

--set-imagecontainer_name=image 使用相同的 kubectl set image 语法。 *=ubuntu 表示把所有容器的镜像改为 ubuntu

  1. kubectl delete pod myapp myapp-debug

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

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

  1. kubectl debug node/mynode -it --image=ubuntu
  1. Creating debugging pod node-debugger-mynode-pdx84 with container debugger on node mynode.
  2. If you don't see a command prompt, try pressing enter.
  3. root@ek8s:/#

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

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

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

  1. kubectl delete pod node-debugger-mynode-pdx84