使用命令排查 Kubernetes 问题

---

---

Previous

Quiz

Next

使用 Kubernetes 既令人兴奋又充满挑战。虽然它提供了强大的工具来管理容器化应用，但问题在所难免。无论是 pod 卡在 CrashLoopBackOff 状态，还是 service 无响应，掌握有效的排查方法都至关重要。

在本章中，我们将介绍一些常见场景以及帮助诊断和解决问题的 kubectl 命令。

检查集群健康状态

在深入排查具体问题之前，确保集群健康是必不可少的。

查看集群节点

使用以下命令查看集群节点 -

$ kubectl get nodes

输出

NAME           STATUS   ROLES           AGE   VERSION
controlplane   Ready    control-plane   71m   v1.31.6
node01         Ready    <none>          71m   v1.31.6

此命令列出集群中的所有节点。我们应该看到所有节点处于 Ready 状态。如果有节点处于 NotReady 状态，则可能表示节点健康或连接性问题。

检查节点详情

使用以下命令检查节点详情 -

$ kubectl describe node <node-name>

它提供特定节点详细信息，包括资源使用情况、条件和事件。有助于识别磁盘压力或内存不足等问题。

排查 Pods

Pod 是 Kubernetes 中最小的可部署单元。当出现问题时，Pod 往往是首先检查的地方。

列出所有 Pods

使用以下命令列出所有 Pod -

$ kubectl get pods -A

输出

NAMESPACE      NAME                                    READY   STATUS    RESTARTS   AGE
kube-flannel   kube-flannel-ds-fbqdb                   1/1     Running   0          75m
kube-flannel   kube-flannel-ds-jln5p                   1/1     Running   0          75m
kube-system    coredns-7c65d6cfc9-4t6gh                1/1     Running   0          75m
kube-system    coredns-7c65d6cfc9-gprrn                1/1     Running   0          75m
kube-system    etcd-controlplane                       1/1     Running   0          75m
kube-system    hostpath-provisioner-5558658586-md76l   1/1     Running   0          75m

它列出所有 namespace 中的所有 Pod。查找不在 Running 或 Completed 状态的 Pod。

描述 Pod

使用以下命令描述 Pod -

$ kubectl describe pod <pod-name> -n <namespace>

例如：

$ kubectl describe pod kube-flannel-ds-fbqdb -n kube-flannel

输出

Name:                 kube-flannel-ds-fbqdb
Namespace:            kube-flannel
Priority:             2000001000
Priority Class Name:  system-node-critical
Service Account:      flannel
Node:                 controlplane/172.16.8.5
Start Time:           Tue, 29 Apr 2025 11:15:04 +0000

它提供 Pod 的详细信息，包括事件，这些事件可以指示调度失败或 image 拉取错误等问题。

查看 Pod 日志

要查看 Pod 日志，使用以下命令 -

$ kubectl logs kube-flannel-ds-fbqdb -n kube-flannel

输出

I0429 11:15:25.762540       1 kube.go:139] Waiting 10m0s for node controller to sync
I0429 11:15:25.762636       1 kube.go:469] Starting kube subnet manager
I0429 11:15:25.769460       1 kube.go:490] Creating the node lease for IPv4. This is the n.Spec.PodCIDRs: [10.244.1.0/24]

它显示 Pod 主容器的日志。如果 Pod 有多个容器，请指定容器名称：

$ kubectl logs <pod-name> -c <container-name> -n <namespace>

常见的 Pod 问题

常见的 Pod 问题包括应用错误、配置错误的的环境变量或资源不足。让我们来探讨一些常见的与 Pod 相关的问题以及如何排查它们。

CrashLoopBackOff

$ kubectl get pods

输出

NAME            READY   STATUS             RESTARTS   AGE
crashloop-pod   0/1     CrashLoopBackOff   5          30s

此状态表示 Pod 正在反复崩溃。

描述 Pod 以查看最近的事件：

$ kubectl describe pod crashloop-pod

输出

Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Normal   Scheduled  30s   default-scheduler  Successfully assigned default/crashloop-pod to node1
  Normal   Pulled     30s   kubelet, node1     Container image "busybox" already present on machine
  Warning  BackOff    5s    kubelet, node1     Back-off restarting failed container
  Normal   Killing    5s    kubelet, node1     Killing container with id docker://crashloop-container:container has runAsNonRoot and image has non-numeric user (busybox), cannot find user busybox in /etc/passwd

检查 Pod 的日志以查看错误消息：

$ kubectl logs crashloop-pod

输出

sh: nonexistent-command: not found

当 container 尝试运行无效命令时，就会出现此错误。我们可以通过以下方式排查此问题：

• 通过设置有效的命令或从 YAML 文件中移除无效命令来修复它。
• 进行更改后删除并重新创建 Pod。
• 确保 Pod 的状态为 Running，并检查日志以验证修复是否成功。

ImagePullBackOff / ErrImagePull

当 Kubernetes 无法拉取 container image 时，就会出现此错误，通常是由于认证问题或 image 名称不正确导致。

描述 Pod 以获取错误详情：

$ kubectl describe pod <pod-name> -n <namespace>

验证 deployment 配置中的 image 名称和标签。确保指定的 registry 中存在该 image，并且 Kubernetes 有权访问它。私有 registry 的认证问题是常见原因。

Pending Pods

如果 Pod 卡在 Pending 状态，通常意味着它尚未被调度到节点上，可能是由于资源限制或节点选择器导致。

描述 Pod 以查看调度事件：

$ kubectl describe pod <pod-name> -n <namespace>

检查可能阻止调度的资源限制或节点选择器。集群资源不足或配置错误的 affinity 规则可能导致此问题。

Service 和网络问题

Service 将运行在 pod 上的应用程序暴露出来。网络问题可能阻止 service 和 pod 之间的通信。

列出 Service

使用以下命令列出 service -

$ kubectl get svc -A

输出

NAMESPACE     NAME                   TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                  AGE
default       kubernetes             ClusterIP   10.96.0.1     <none>        443/TCP                  50m
kube-system   kube-dns               ClusterIP   10.96.0.10    <none>        53/UDP,53/TCP,9153/TCP   50m
kube-system   kubelet-csr-approver   ClusterIP   10.107.94.7   <none>        8080/TCP                 50m

它会列出所有 namespace 中的 service。

描述 Service

使用以下命令描述 service -

$ kubectl describe svc kubelet-csr-approver -n kube-system

输出

Type:                     ClusterIP
IP Family Policy:         SingleStack
IP Families:              IPv4
IP:                       10.107.94.7
IPs:                      10.107.94.7
Port:                     metrics  8080/TCP
TargetPort:               metrics/TCP
Endpoints:                10.244.1.3:8080,10.244.1.6:8080
Session Affinity:         None
Internal Traffic Policy:  Cluster
Events:                   <none>

它提供了 service 配置和 endpoints 的详细信息。

测试 Service 连通性

使用 port forwarding 测试 service 访问：

$ kubectl port-forward svc/kubelet-csr-approver 8080:8080 -n kube-system

输出

Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080
Handling connection for 8080
Handling connection for 8080

然后，在 http://localhost:8080 访问该 service。

DNS 解析

如果 pod 无法解析 service 名称，请检查 DNS 配置：

$ kubectl exec -it <pod-name> -n <namespace> -- nslookup <service-name>

确保 CoreDNS pod 正在运行且健康。

节点级故障排除

有时，问题源于节点本身。

检查节点状态

使用以下命令检查节点状态 -

$ kubectl get nodes

输出

NAME           STATUS   ROLES           AGE     VERSION
controlplane   Ready    control-plane   6m37s   v1.31.6
node01         Ready    <none>          6m23s   v1.31.6

节点应处于 Ready 状态。

描述节点

如果需要获取节点的描述信息，则使用以下命令 -

$ kubectl describe node <node-name>

查找类似 MemoryPressure 或 DiskPressure 的条件。

配置和 Secret

配置错误的 ConfigMap 或 Secret 可能导致应用程序失败。

列出 ConfigMap

使用以下命令列出 ConfigMap -

$ kubectl get configmaps -n dev

输出

NAME               DATA   AGE
app-config         3      25m
env-settings       2      25m

描述 ConfigMap

使用以下命令描述 ConfigMap -

$ kubectl describe configmap app-config -n dev

输出

Name:         app-config
Namespace:    dev
Data
====
PORT:         80
DB_HOST:      db-service
DB_PORT:      not-a-number

在这个例子中，DB_PORT 值被错误设置为 not-a-number>，但它应该是一个整数（一个有效的（一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个一个

事件和审计轨迹

$ kubectl get events -A --sort-by='.metadata.creationTimestamp'

kube-system    15m         Normal    Pulled
pod/metrics-server-54bf7cdd6-7khch           Successfully pulled image
"registry.k8s.io/metrics-server/metrics-server:v0.7.2" in 2.458s 
(2.458s including waiting). Image size: 19494617 bytes.
kube-system    15m         Normal    Created
pod/metrics-server-54bf7cdd6-7khch   Created container: metrics-server
kube-system    15m         Normal    Started
pod/metrics-server-54bf7cdd6-7khch   Started container metrics-server

$ kubectl exec -it <pod-name> -n <namespace> -- /bin/bash

$ kubectl exec -it my-app-5f4d8c6f6c-rm87x -n dev -- /bin/bash

$ kubectl run debug-pod --rm -i --tty --image=busybox -- /bin/sh

$ kubectl get pvc -n dev

NAME            STATUS   VOLUME  CAPACITY   ACCESS MODES
data-my-db-0    Pending                                                   

$ kubectl describe pvc data-my-db-0 -n dev

Events:
  Type    Reason                Message
  ----    ------                -------
Warning ProvisioningFailed   no persistent volumes available for this claim

$ kubectl get ds -n kube-system

NAME         DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR            AGE
kube-proxy   2         2         2       2            2           kubernetes.io/os=linux   39m

$ kubectl get jobs -n dev

NAME               COMPLETIONS   DURATION   AGE
my-job             1/1           2s         10m
failed-job         0/1           1m         15m

$ kubectl logs <pod-name>
$ kubectl describe job <job-name>

$ kubectl auth can-i create deployments --as=dev-user

no

$ kubectl debug pod/my-app -n dev --image=busybox --target=main-container

Pod "my-app-debug" created.

$ kubectl exec -it my-app-debug -n dev -- /bin/sh