调试正在运行的 Pod

本页说明如何调试在节点上运行（或崩溃）的 Pod。

在您开始之前

  • 您的 Pod 应该已经计划并运行。如果您的 Pod 尚未运行，请从 调试 Pod 开始。
  • 对于某些高级调试步骤，您需要知道 Pod 在哪个节点上运行，并且需要拥有该节点的 shell 访问权限才能在该节点上运行命令。您无需使用 kubectl 运行标准调试步骤。

使用 kubectl describe pod 获取有关 pod 的详细信息

对于此示例，我们将使用 Deployment 创建两个 pod，类似于前面的示例。

application/nginx-with-request.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        resources:
          limits:
            memory: "128Mi"
            cpu: "500m"
        ports:
        - containerPort: 80

通过运行以下命令创建部署

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

deployment.apps/nginx-deployment created

通过以下命令检查 pod 状态

kubectl get pods

NAME                                READY   STATUS    RESTARTS   AGE
nginx-deployment-67d4bdd6f5-cx2nz   1/1     Running   0          13s
nginx-deployment-67d4bdd6f5-w6kd7   1/1     Running   0          13s

我们可以使用 kubectl describe pod 获取有关这些 pod 中的每一个的更多信息。例如

kubectl describe pod nginx-deployment-67d4bdd6f5-w6kd7

Name:         nginx-deployment-67d4bdd6f5-w6kd7
Namespace:    default
Priority:     0
Node:         kube-worker-1/192.168.0.113
Start Time:   Thu, 17 Feb 2022 16:51:01 -0500
Labels:       app=nginx
              pod-template-hash=67d4bdd6f5
Annotations:  <none>
Status:       Running
IP:           10.88.0.3
IPs:
  IP:           10.88.0.3
  IP:           2001:db8::1
Controlled By:  ReplicaSet/nginx-deployment-67d4bdd6f5
Containers:
  nginx:
    Container ID:   containerd://5403af59a2b46ee5a23fb0ae4b1e077f7ca5c5fb7af16e1ab21c00e0e616462a
    Image:          nginx
    Image ID:       docker.io/library/nginx@sha256:2834dc507516af02784808c5f48b7cbe38b8ed5d0f4837f16e78d00deb7e7767
    Port:           80/TCP
    Host Port:      0/TCP
    State:          Running
      Started:      Thu, 17 Feb 2022 16:51:05 -0500
    Ready:          True
    Restart Count:  0
    Limits:
      cpu:     500m
      memory:  128Mi
    Requests:
      cpu:        500m
      memory:     128Mi
    Environment:  <none>
    Mounts:
      /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-bgsgp (ro)
Conditions:
  Type              Status
  Initialized       True 
  Ready             True 
  ContainersReady   True 
  PodScheduled      True 
Volumes:
  kube-api-access-bgsgp:
    Type:                    Projected (a volume that contains injected data from multiple sources)
    TokenExpirationSeconds:  3607
    ConfigMapName:           kube-root-ca.crt
    ConfigMapOptional:       <nil>
    DownwardAPI:             true
QoS Class:                   Guaranteed
Node-Selectors:              <none>
Tolerations:                 node.kubernetes.io/not-ready:NoExecute op=Exists for 300s
                             node.kubernetes.io/unreachable:NoExecute op=Exists for 300s
Events:
  Type    Reason     Age   From               Message
  ----    ------     ----  ----               -------
  Normal  Scheduled  34s   default-scheduler  Successfully assigned default/nginx-deployment-67d4bdd6f5-w6kd7 to kube-worker-1
  Normal  Pulling    31s   kubelet            Pulling image "nginx"
  Normal  Pulled     30s   kubelet            Successfully pulled image "nginx" in 1.146417389s
  Normal  Created    30s   kubelet            Created container nginx
  Normal  Started    30s   kubelet            Started container nginx

在这里您可以看到有关容器和 Pod 的配置信息（标签、资源需求等），以及有关容器和 Pod 的状态信息（状态、就绪性、重启次数、事件等）。

容器状态可以是等待、正在运行或已终止之一。根据状态，将提供其他信息——在这里您可以看到，对于处于正在运行状态的容器，系统会告诉您容器何时启动。

就绪告诉您容器是否通过了其最后一次就绪探测。（在本例中，容器没有配置就绪探测；如果未配置就绪探测，则假定容器已就绪。）

重启次数告诉您容器重启了多少次；此信息可用于检测配置为“始终”重启策略的容器中的崩溃循环。

目前，与 Pod 关联的唯一条件是二进制就绪条件，它指示 Pod 能够处理请求，并且应该添加到所有匹配服务的负载均衡池中。

最后，您会看到与您的 Pod 相关的最近事件的日志。“来源”指示记录事件的组件。“原因”和“消息”告诉您发生了什么。

示例：调试处于挂起状态的 Pod

您可以使用事件检测到的一个常见场景是，您创建了一个无法容纳在任何节点上的 Pod。例如，Pod 可能请求的资源超过任何节点上的可用资源，或者它可能指定了与任何节点都不匹配的标签选择器。假设我们创建了之前的 Deployment，具有 5 个副本（而不是 2 个），并请求 600 毫核而不是 500 毫核，在一个每台（虚拟）机器有 1 个 CPU 的四个节点集群中。在这种情况下，其中一个 Pod 将无法调度。（请注意，由于每个节点上运行的集群附加 pod（如 fluentd、skydns 等），如果我们请求 1000 毫核，那么没有一个 Pod 能够调度。）

kubectl get pods

NAME                                READY     STATUS    RESTARTS   AGE
nginx-deployment-1006230814-6winp   1/1       Running   0          7m
nginx-deployment-1006230814-fmgu3   1/1       Running   0          7m
nginx-deployment-1370807587-6ekbw   1/1       Running   0          1m
nginx-deployment-1370807587-fg172   0/1       Pending   0          1m
nginx-deployment-1370807587-fz9sd   0/1       Pending   0          1m

要找出 nginx-deployment-1370807587-fz9sd pod 为何没有运行，我们可以对处于挂起状态的 Pod 使用 kubectl describe pod 并查看其事件

kubectl describe pod nginx-deployment-1370807587-fz9sd

  Name:		nginx-deployment-1370807587-fz9sd
  Namespace:	default
  Node:		/
  Labels:		app=nginx,pod-template-hash=1370807587
  Status:		Pending
  IP:
  Controllers:	ReplicaSet/nginx-deployment-1370807587
  Containers:
    nginx:
      Image:	nginx
      Port:	80/TCP
      QoS Tier:
        memory:	Guaranteed
        cpu:	Guaranteed
      Limits:
        cpu:	1
        memory:	128Mi
      Requests:
        cpu:	1
        memory:	128Mi
      Environment Variables:
  Volumes:
    default-token-4bcbi:
      Type:	Secret (a volume populated by a Secret)
      SecretName:	default-token-4bcbi
  Events:
    FirstSeen	LastSeen	Count	From			        SubobjectPath	Type		Reason			    Message
    ---------	--------	-----	----			        -------------	--------	------			    -------
    1m		    48s		    7	    {default-scheduler }			        Warning		FailedScheduling	pod (nginx-deployment-1370807587-fz9sd) failed to fit in any node
  fit failure on node (kubernetes-node-6ta5): Node didn't have enough resource: CPU, requested: 1000, used: 1420, capacity: 2000
  fit failure on node (kubernetes-node-wul5): Node didn't have enough resource: CPU, requested: 1000, used: 1100, capacity: 2000

在这里您可以看到调度程序生成的事件，说明 Pod 由于原因 FailedScheduling（以及其他可能的原因）而无法调度。该消息告诉我们，任何节点上都没有足够的资源供 Pod 使用。

要更正这种情况，您可以使用 kubectl scale 更新您的 Deployment 以指定四个或更少的副本。（或者您可以将一个 Pod 保持在挂起状态，这无害。）

例如您在 kubectl describe pod 末尾看到的事件会持久保存在 etcd 中，并提供有关集群中正在发生的事情的高级信息。要列出所有事件，您可以使用

kubectl get events

但您必须记住，事件是命名空间的。这意味着，如果您对某个命名空间对象的事件感兴趣（例如，my-namespace 命名空间中 Pod 发生了什么），您需要显式地为该命令提供命名空间

kubectl get events --namespace=my-namespace

要查看所有命名空间中的事件，可以使用 --all-namespaces 参数。

除了 kubectl describe pod 之外，还可以通过将 -o yaml 输出格式标志传递给 kubectl get pod 来获取有关 pod 的更多信息（超出 kubectl get pod 提供的信息）。这将以 YAML 格式提供比 kubectl describe pod 更多的信息——基本上是系统对 Pod 的所有信息。在这里，您将看到诸如注释（没有标签限制的键值元数据，系统组件在内部使用），重启策略、端口和卷之类的内容。

kubectl get pod nginx-deployment-1006230814-6winp -o yaml

apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: "2022-02-17T21:51:01Z"
  generateName: nginx-deployment-67d4bdd6f5-
  labels:
    app: nginx
    pod-template-hash: 67d4bdd6f5
  name: nginx-deployment-67d4bdd6f5-w6kd7
  namespace: default
  ownerReferences:
  - apiVersion: apps/v1
    blockOwnerDeletion: true
    controller: true
    kind: ReplicaSet
    name: nginx-deployment-67d4bdd6f5
    uid: 7d41dfd4-84c0-4be4-88ab-cedbe626ad82
  resourceVersion: "1364"
  uid: a6501da1-0447-4262-98eb-c03d4002222e
spec:
  containers:
  - image: nginx
    imagePullPolicy: Always
    name: nginx
    ports:
    - containerPort: 80
      protocol: TCP
    resources:
      limits:
        cpu: 500m
        memory: 128Mi
      requests:
        cpu: 500m
        memory: 128Mi
    terminationMessagePath: /dev/termination-log
    terminationMessagePolicy: File
    volumeMounts:
    - mountPath: /var/run/secrets/kubernetes.io/serviceaccount
      name: kube-api-access-bgsgp
      readOnly: true
  dnsPolicy: ClusterFirst
  enableServiceLinks: true
  nodeName: kube-worker-1
  preemptionPolicy: PreemptLowerPriority
  priority: 0
  restartPolicy: Always
  schedulerName: default-scheduler
  securityContext: {}
  serviceAccount: default
  serviceAccountName: default
  terminationGracePeriodSeconds: 30
  tolerations:
  - effect: NoExecute
    key: node.kubernetes.io/not-ready
    operator: Exists
    tolerationSeconds: 300
  - effect: NoExecute
    key: node.kubernetes.io/unreachable
    operator: Exists
    tolerationSeconds: 300
  volumes:
  - name: kube-api-access-bgsgp
    projected:
      defaultMode: 420
      sources:
      - serviceAccountToken:
          expirationSeconds: 3607
          path: token
      - configMap:
          items:
          - key: ca.crt
            path: ca.crt
          name: kube-root-ca.crt
      - downwardAPI:
          items:
          - fieldRef:
              apiVersion: v1
              fieldPath: metadata.namespace
            path: namespace
status:
  conditions:
  - lastProbeTime: null
    lastTransitionTime: "2022-02-17T21:51:01Z"
    status: "True"
    type: Initialized
  - lastProbeTime: null
    lastTransitionTime: "2022-02-17T21:51:06Z"
    status: "True"
    type: Ready
  - lastProbeTime: null
    lastTransitionTime: "2022-02-17T21:51:06Z"
    status: "True"
    type: ContainersReady
  - lastProbeTime: null
    lastTransitionTime: "2022-02-17T21:51:01Z"
    status: "True"
    type: PodScheduled
  containerStatuses:
  - containerID: containerd://5403af59a2b46ee5a23fb0ae4b1e077f7ca5c5fb7af16e1ab21c00e0e616462a
    image: docker.io/library/nginx:latest
    imageID: docker.io/library/nginx@sha256:2834dc507516af02784808c5f48b7cbe38b8ed5d0f4837f16e78d00deb7e7767
    lastState: {}
    name: nginx
    ready: true
    restartCount: 0
    started: true
    state:
      running:
        startedAt: "2022-02-17T21:51:05Z"
  hostIP: 192.168.0.113
  phase: Running
  podIP: 10.88.0.3
  podIPs:
  - ip: 10.88.0.3
  - ip: 2001:db8::1
  qosClass: Guaranteed
  startTime: "2022-02-17T21:51:01Z"

检查 pod 日志

首先，查看受影响容器的日志

kubectl logs ${POD_NAME} ${CONTAINER_NAME}

如果您的容器先前已崩溃，您可以使用以下方法访问先前容器的崩溃日志

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

使用容器 exec 调试

如果 容器映像 包含调试实用程序，例如从 Linux 和 Windows 操作系统基本映像构建的映像，您可以在特定容器内运行命令，方法是使用 kubectl exec

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

例如，要查看运行中的 Cassandra pod 的日志，您可能需要运行

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

您可以运行连接到终端的 shell，方法是将 -i 和 -t 参数传递给 kubectl exec，例如

kubectl exec -it cassandra -- sh

有关更多详细信息，请参阅 获取运行容器的 shell。

使用短暂调试容器调试

功能状态： Kubernetes v1.25 [稳定]

短暂容器 在 kubectl exec 不足的情况下（因为容器已崩溃或容器映像不包含调试实用程序，例如使用 distroless 映像）非常有用，可用于交互式故障排除。

使用短暂容器进行调试的示例

您可以使用 kubectl debug 命令将短暂容器添加到运行中的 Pod 中。首先，为示例创建一个 pod

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

本节中的示例使用 pause 容器映像，因为它不包含调试实用程序，但此方法适用于所有容器映像。

如果尝试使用 kubectl exec 创建 shell，您将看到错误，因为此容器映像中没有 shell。

kubectl exec -it ephemeral-demo -- sh

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 会自动附加到短暂容器的控制台。

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

Defaulting debug container name to debugger-8xzrl.
If you don't see a command prompt, try pressing enter.
/ #

此命令添加一个新的 busybox 容器并附加到它。--target 参数将目标定位到另一个容器的进程命名空间。这里需要它，因为 kubectl run 不会在它创建的 pod 中启用 进程命名空间共享。

您可以使用 kubectl describe 查看新创建的短暂容器的状态

kubectl describe pod ephemeral-demo

...
Ephemeral Containers:
  debugger-8xzrl:
    Container ID:   docker://b888f9adfd15bd5739fefaa39e1df4dd3c617b9902082b1cfdc29c4028ffb2eb
    Image:          busybox
    Image ID:       docker-pullable://busybox@sha256:1828edd60c5efd34b2bf5dd3282ec0cc04d47b2ff9caa0b6d4f07a21d1c08084
    Port:           <none>
    Host Port:      <none>
    State:          Running
      Started:      Wed, 12 Feb 2020 14:25:42 +0100
    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-w7xmf.
If you don't see a command prompt, try pressing enter.
root@myapp-debug:/#

完成操作后，不要忘记清理调试 Pod

kubectl delete pod myapp myapp-debug

在更改命令的同时复制 Pod

有时更改容器的命令很有用，例如，添加调试标志，或者因为应用程序正在崩溃。

要模拟崩溃的应用程序，请使用 kubectl run 创建一个立即退出的容器

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

您可以使用 kubectl describe pod myapp 查看此容器正在崩溃

Containers:
  myapp:
    Image:         busybox
    ...
    Args:
      false
    State:          Waiting
      Reason:       CrashLoopBackOff
    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，可用于执行诸如检查文件系统路径或手动运行容器命令之类的任务。

完成操作后，不要忘记清理调试 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 的语法与 kubectl set image 中使用的 container_name=image 语法相同。*=ubuntu 表示将所有容器的镜像更改为 ubuntu。

完成操作后，不要忘记清理调试 Pod

kubectl delete pod myapp myapp-debug

通过节点上的 shell 进行调试

如果上述方法都不起作用，您可以找到运行 Pod 的节点，并在节点上创建一个运行在节点上的 Pod。要使用 kubectl debug 在节点上创建交互式 shell，请运行

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

Creating debugging pod node-debugger-mynode-pdx84 with container debugger on node mynode.
If you don't see a command prompt, try pressing enter.
root@ek8s:/#

在节点上创建调试会话时，请记住

  • kubectl debug 会根据节点的名称自动生成新 Pod 的名称。
  • 节点的根文件系统将挂载到 /host。
  • 容器在主机 IPC、网络和 PID 命名空间中运行，尽管 pod 没有特权，因此读取某些进程信息可能会失败，chroot /host 也可能会失败。
  • 如果您需要特权 pod，请手动创建它或使用 --profile=sysadmin 标志。

完成操作后，不要忘记清理调试 Pod

kubectl delete pod node-debugger-mynode-pdx84

调试配置文件

当使用 kubectl debug 通过调试 Pod 调试节点，通过短暂容器调试 Pod 或调试复制的 Pod 时，您可以使用 --profile 标志将调试配置文件应用到它们。通过应用配置文件，可以设置特定属性，例如 securityContext，从而适应各种场景。

可用的配置文件如下所示

配置文件描述
legacy一组与 1.22 行为向后兼容的属性
general每种调试旅程的一组合理的通用属性
baseline一组与 PodSecurityStandard 基线策略 兼容的属性
restricted一组与 PodSecurityStandard 受限策略 兼容的属性
netadmin一组包含网络管理员特权的属性
sysadmin一组包含系统管理员（root）特权的属性

假设您创建一个 Pod 并对其进行调试。首先，创建一个名为 myapp 的 Pod 作为示例

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

然后，使用短暂容器调试 Pod。如果短暂容器需要拥有特权，您可以使用 sysadmin 配置文件

kubectl debug -it myapp --image=busybox:1.28 --target=myapp --profile=sysadmin

Targeting container "myapp". 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-6kg4x.
If you don't see a command prompt, try pressing enter.
/ #

通过在容器内运行以下命令来检查短暂容器进程的功能

/ # grep Cap /proc/$$/status

...
CapPrm:	000001ffffffffff
CapEff:	000001ffffffffff
...

这意味着通过应用 sysadmin 配置文件，容器进程被授予了特权容器的全部功能。有关 功能 的更多详细信息，请参见。

您还可以检查短暂容器是否作为特权容器创建

kubectl get pod myapp -o jsonpath='{.spec.ephemeralContainers[0].securityContext}'

{"privileged":true}

完成操作后，清理 Pod

kubectl delete pod myapp
上次修改时间：2024 年 6 月 27 日下午 8:48 PST：添加有关调试配置文件的描述 (0c8a63f4a2)