调试服务

在 Kubernetes 的新安装中，经常出现的一个问题是服务无法正常工作。你通过 Deployment（或其他工作负载控制器）运行了 Pod 并创建了 Service，但当你尝试访问它时却没有任何响应。希望本文档能帮助你找出问题所在。

在 Pod 中运行命令

对于这里的许多步骤，你都需要查看集群中运行的 Pod 所看到的内容。最简单的方法是运行一个交互式的 busybox Pod：

kubectl run -it --rm --restart=Never busybox --image=gcr.io/google-containers/busybox sh

说明

如果没有看到命令提示符，请尝试按回车键。

如果你已经有一个想要使用的运行中 Pod，可以使用以下命令在其中运行命令：

kubectl exec <POD-NAME> -c <CONTAINER-NAME> -- <COMMAND>

设置

为了演示此演练，让我们运行一些 Pod。由于你可能正在调试自己的 Service，你可以替换为你自己的详细信息，也可以跟着操作并获取一个参考数据点。

kubectl create deployment hostnames --image=registry.k8s.io/serve_hostname

deployment.apps/hostnames created

kubectl 命令将打印所创建或变更资源的类型和名称，随后可以在后续命令中使用这些信息。

让我们将 Deployment 扩容到 3 个副本。

kubectl scale deployment hostnames --replicas=3

deployment.apps/hostnames scaled

请注意，这与你使用以下 YAML 启动 Deployment 的效果相同：

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: hostnames
  name: hostnames
spec:
  selector:
    matchLabels:
      app: hostnames
  replicas: 3
  template:
    metadata:
      labels:
        app: hostnames
    spec:
      containers:
      - name: hostnames
        image: registry.k8s.io/serve_hostname

标签 "app" 由 kubectl create deployment 自动设置为 Deployment 的名称。

你可以确认你的 Pod 正在运行：

kubectl get pods -l app=hostnames

NAME                        READY     STATUS    RESTARTS   AGE
hostnames-632524106-bbpiw   1/1       Running   0          2m
hostnames-632524106-ly40y   1/1       Running   0          2m
hostnames-632524106-tlaok   1/1       Running   0          2m

你还可以确认你的 Pod 正在提供服务。你可以获取 Pod IP 地址列表并直接测试它们。

kubectl get pods -l app=hostnames \
    -o go-template='{{range .items}}{{.status.podIP}}{{"\n"}}{{end}}'

10.244.0.5
10.244.0.6
10.244.0.7

此演练使用的示例容器通过端口 9376 上的 HTTP 提供其主机名，但如果你正在调试自己的应用程序，则需要使用你的 Pod 正在监听的端口号。

从 Pod 内部

for ep in 10.244.0.5:9376 10.244.0.6:9376 10.244.0.7:9376; do
    wget -qO- $ep
done

这应该会产生类似以下的结果：

hostnames-632524106-bbpiw
hostnames-632524106-ly40y
hostnames-632524106-tlaok

如果你此时没有得到预期的响应，你的 Pod 可能不健康，或者可能没有在你认为的端口上进行监听。你可能会发现 kubectl logs 对于查看正在发生的事情很有用，或者你可能需要直接使用 kubectl exec 进入你的 Pod 并从那里进行调试。

假设目前为止一切顺利，你可以开始调查为什么你的 Service 无法工作。

服务是否存在？

细心的读者会注意到，你实际上还没有创建 Service——这是故意的。这是一个有时会被遗忘的步骤，也是首先要检查的事情。

如果你尝试访问一个不存在的 Service 会发生什么？如果你有另一个通过名称调用此 Service 的 Pod，你将得到类似以下的内容：

wget -O- hostnames

Resolving hostnames (hostnames)... failed: Name or service not known.
wget: unable to resolve host address 'hostnames'

首先要检查的是该 Service 是否确实存在：

kubectl get svc hostnames

No resources found.
Error from server (NotFound): services "hostnames" not found

让我们创建该 Service。和前面一样，这是为了演示——你可以在这里使用你自己的 Service 详细信息。

kubectl expose deployment hostnames --port=80 --target-port=9376

service/hostnames exposed

然后读取它：

kubectl get svc hostnames

NAME        TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
hostnames   ClusterIP   10.0.1.175   <none>        80/TCP    5s

现在你知道该 Service 存在了。

和前面一样，这与你使用 YAML 启动 Service 的效果相同：

apiVersion: v1
kind: Service
metadata:
  labels:
    app: hostnames
  name: hostnames
spec:
  selector:
    app: hostnames
  ports:
  - name: default
    protocol: TCP
    port: 80
    targetPort: 9376

为了突出完整配置，你在此处创建的 Service 使用了与 Pod 不同的端口号。对于许多实际的 Service，这些值可能是相同的。

是否有任何网络策略（Network Policy）入站规则影响目标 Pod？

如果你部署了任何可能影响 hostnames-* Pod 入站流量的网络策略（Network Policy）入站规则，则需要对它们进行审查。

请参阅网络策略获取更多详细信息。

服务是否能通过 DNS 名称正常工作？

客户端使用 Service 最常见的方式之一是通过 DNS 名称。

从同一命名空间中的 Pod 访问：

nslookup hostnames

Address 1: 10.0.0.10 kube-dns.kube-system.svc.cluster.local

Name:      hostnames
Address 1: 10.0.1.175 hostnames.default.svc.cluster.local

如果这失败了，可能是因为你的 Pod 和 Service 处于不同的命名空间中，请尝试使用命名空间限定名称（同样，从 Pod 内部）：

nslookup hostnames.default

Address 1: 10.0.0.10 kube-dns.kube-system.svc.cluster.local

Name:      hostnames.default
Address 1: 10.0.1.175 hostnames.default.svc.cluster.local

如果这有效，你需要调整你的应用程序以使用跨命名空间名称，或者在同一命名空间中运行你的应用程序和 Service。如果这仍然失败，请尝试使用完全限定名称：

nslookup hostnames.default.svc.cluster.local

Address 1: 10.0.0.10 kube-dns.kube-system.svc.cluster.local

Name:      hostnames.default.svc.cluster.local
Address 1: 10.0.1.175 hostnames.default.svc.cluster.local

注意此处的后缀：“default.svc.cluster.local”。“default” 是你操作的命名空间。“svc” 表示这是一个 Service。“cluster.local” 是你的集群域名，在你的集群中可能有所不同。

你也可以尝试从集群中的节点执行此操作：

说明

10.0.0.10 是集群的 DNS 服务 IP，你的可能不同。

nslookup hostnames.default.svc.cluster.local 10.0.0.10

Server:         10.0.0.10
Address:        10.0.0.10#53

Name:   hostnames.default.svc.cluster.local
Address: 10.0.1.175

如果你能够执行完全限定名称查找但无法执行相对名称查找，则需要检查 Pod 中的 /etc/resolv.conf 文件是否正确。从 Pod 内部：

cat /etc/resolv.conf

你应该看到类似以下的内容：

nameserver 10.0.0.10
search default.svc.cluster.local svc.cluster.local cluster.local example.com
options ndots:5

nameserver 行必须指向你的集群 DNS 服务。这是通过 --cluster-dns 标志传递给 kubelet 的。

search 行必须包含适当的后缀，以便你找到 Service 名称。在这种情况下，它正在查找本地命名空间中的 Service ("default.svc.cluster.local")、所有命名空间中的 Service ("svc.cluster.local")，最后是集群中的名称 ("cluster.local")。根据你的安装方式，在此之后你可能有额外的记录（最多 6 条）。集群后缀是通过 --cluster-domain 标志传递给 kubelet 的。在本文档中，假设集群后缀为 "cluster.local"。你自己的集群配置可能不同，在这种情况下，你应该在之前的所有命令中进行相应更改。

options 行必须将 ndots 设置得足够高，以便你的 DNS 客户端库考虑搜索路径。Kubernetes 默认将其设置为 5，这足以覆盖它生成的所有 DNS 名称。

是否有任何服务能通过 DNS 名称正常工作？

如果以上步骤仍然失败，说明你的 Service 的 DNS 查找无法工作。你可以退后一步，看看还有什么无法工作。Kubernetes 主控 Service 应该始终能正常工作。从 Pod 内部：

nslookup kubernetes.default

Server:    10.0.0.10
Address 1: 10.0.0.10 kube-dns.kube-system.svc.cluster.local

Name:      kubernetes.default
Address 1: 10.0.0.1 kubernetes.default.svc.cluster.local

如果这也失败了，请参阅本文档的 kube-proxy 部分，或者回到本文档开头重新开始，但不要调试你自己的 Service，而是调试 DNS Service。

服务是否能通过 IP 地址正常工作？

假设你已确认 DNS 工作正常，接下来要测试的是你的 Service 是否能通过其 IP 地址工作。从集群中的 Pod 访问该 Service 的 IP（来自上面的 kubectl get）。

for i in $(seq 1 3); do 
    wget -qO- 10.0.1.175:80
done

这应该会产生类似以下的结果：

hostnames-632524106-bbpiw
hostnames-632524106-ly40y
hostnames-632524106-tlaok

如果你的 Service 工作正常，你应该会得到正确的响应。如果不是，可能会出很多问题。请继续阅读。

服务定义是否正确？

这听起来可能有点傻，但你确实应该反复检查你的 Service 是否正确，是否与 Pod 的端口相匹配。重新读取你的 Service 并进行验证：

kubectl get service hostnames -o json

{
    "kind": "Service",
    "apiVersion": "v1",
    "metadata": {
        "name": "hostnames",
        "namespace": "default",
        "uid": "428c8b6c-24bc-11e5-936d-42010af0a9bc",
        "resourceVersion": "347189",
        "creationTimestamp": "2015-07-07T15:24:29Z",
        "labels": {
            "app": "hostnames"
        }
    },
    "spec": {
        "ports": [
            {
                "name": "default",
                "protocol": "TCP",
                "port": 80,
                "targetPort": 9376,
                "nodePort": 0
            }
        ],
        "selector": {
            "app": "hostnames"
        },
        "clusterIP": "10.0.1.175",
        "type": "ClusterIP",
        "sessionAffinity": "None"
    },
    "status": {
        "loadBalancer": {}
    }
}

你尝试访问的 Service 端口是否在 spec.ports[] 中列出？
targetPort 对于你的 Pod 是否正确（有些 Pod 使用的端口与 Service 不同）？
如果你打算使用数字端口，它是数字 9376 还是字符串 "9376"？
如果你打算使用命名端口，你的 Pod 是否暴露了具有相同名称的端口？
该端口的 protocol 对于你的 Pod 是否正确？

服务是否有任何 EndpointSlice？

如果你走到了这一步，你已经确认你的 Service 定义正确且 DNS 解析无误。现在让我们检查一下你运行的 Pod 是否确实被 Service 选中。

之前你已经看到 Pod 正在运行。你可以再次检查：

kubectl get pods -l app=hostnames

NAME                        READY     STATUS    RESTARTS   AGE
hostnames-632524106-bbpiw   1/1       Running   0          1h
hostnames-632524106-ly40y   1/1       Running   0          1h
hostnames-632524106-tlaok   1/1       Running   0          1h

-l app=hostnames 参数是 Service 上配置的标签选择器。

"AGE" 列显示这些 Pod 大约运行了一小时，这意味着它们运行良好且没有崩溃。

"RESTARTS" 列显示这些 Pod 没有频繁崩溃或重启。频繁重启可能导致间歇性的连接问题。如果重启计数很高，请阅读更多关于如何调试 Pod 的内容。

Kubernetes 系统内部有一个控制循环，它评估每个 Service 的选择器并将结果保存到一个或多个 EndpointSlice 对象中。

kubectl get endpointslices -l k8s.io/service-name=hostnames

NAME              ADDRESSTYPE   PORTS   ENDPOINTS
hostnames-ytpni   IPv4          9376    10.244.0.5,10.244.0.6,10.244.0.7

这证实了 EndpointSlice 控制器已为你的 Service 找到正确的 Pod。如果 ENDPOINTS 列为 <none>，你应该检查你的 Service 的 spec.selector 字段是否确实选择了 Pod 上的 metadata.labels 值。一个常见的错误是存在拼写错误或其他失误，例如 Service 选择 app=hostnames，但 Deployment 指定了 run=hostnames（在 1.18 之前的版本中，kubectl run 命令也可用于创建 Deployment）。

Pod 是否正常工作？

此时，你知道你的 Service 存在且已选中了你的 Pod。在演练开始时，你验证了 Pod 本身。让我们再次检查 Pod 是否确实在工作——你可以跳过 Service 机制，直接访问上述 Endpoints 列出的 Pod。

说明

这些命令使用的是 Pod 端口 (9376)，而不是 Service 端口 (80)。

从 Pod 内部：

for ep in 10.244.0.5:9376 10.244.0.6:9376 10.244.0.7:9376; do
    wget -qO- $ep
done

这应该会产生类似以下的结果：

hostnames-632524106-bbpiw
hostnames-632524106-ly40y
hostnames-632524106-tlaok

你预计 endpoints 列表中的每个 Pod 都会返回其自己的主机名。如果情况并非如此（或者你的 Pod 应该表现出其他正确的行为），你应该调查那里发生了什么。

kube-proxy 是否正常工作？

如果你走到了这一步，说明你的 Service 正在运行，有 EndpointSlices，并且你的 Pod 确实在提供服务。此时，整个 Service 代理机制都值得怀疑。让我们逐一确认一下。

Services 的默认实现（也是大多数集群上使用的实现）是 kube-proxy。这是一个在每个节点上运行并配置一组小型机制以提供 Service 抽象的程序。如果你的集群不使用 kube-proxy，以下章节将不适用，你需要调查你正在使用的任何 Service 实现。

kube-proxy 是否在运行？

确认 kube-proxy 正在你的节点上运行。直接在节点上运行，你应该得到类似下面的输出：

ps auxw | grep kube-proxy

root  4194  0.4  0.1 101864 17696 ?    Sl Jul04  25:43 /usr/local/bin/kube-proxy --master=https://kubernetes-master --kubeconfig=/var/lib/kube-proxy/kubeconfig --v=2

接下来，确认它没有出现明显的故障，比如联系不上主控节点（master）。为此，你必须查看日志。访问日志取决于你的节点操作系统。在某些操作系统上它是一个文件，例如 /var/log/kube-proxy.log，而其他操作系统则使用 journalctl 来访问日志。你应该看到类似以下内容：

I1027 22:14:53.995134    5063 server.go:200] Running in resource-only container "/kube-proxy"
I1027 22:14:53.998163    5063 server.go:247] Using iptables Proxier.
I1027 22:14:54.038140    5063 proxier.go:352] Setting endpoints for "kube-system/kube-dns:dns-tcp" to [10.244.1.3:53]
I1027 22:14:54.038164    5063 proxier.go:352] Setting endpoints for "kube-system/kube-dns:dns" to [10.244.1.3:53]
I1027 22:14:54.038209    5063 proxier.go:352] Setting endpoints for "default/kubernetes:https" to [10.240.0.2:443]
I1027 22:14:54.038238    5063 proxier.go:429] Not syncing iptables until Services and Endpoints have been received from master
I1027 22:14:54.040048    5063 proxier.go:294] Adding new service "default/kubernetes:https" at 10.0.0.1:443/TCP
I1027 22:14:54.040154    5063 proxier.go:294] Adding new service "kube-system/kube-dns:dns" at 10.0.0.10:53/UDP
I1027 22:14:54.040223    5063 proxier.go:294] Adding new service "kube-system/kube-dns:dns-tcp" at 10.0.0.10:53/TCP

如果你看到关于无法联系主控节点的错误消息，你应该仔细检查你的节点配置和安装步骤。

Kube-proxy 可以运行在几种模式之一。在上面列出的日志中，Using iptables Proxier 一行表示 kube-proxy 正在 "iptables" 模式下运行。最常见的另一种模式是 "ipvs"。

Iptables 模式

在 "iptables" 模式下，你应该在节点上看到类似以下内容：

iptables-save | grep hostnames

-A KUBE-SEP-57KPRZ3JQVENLNBR -s 10.244.3.6/32 -m comment --comment "default/hostnames:" -j MARK --set-xmark 0x00004000/0x00004000
-A KUBE-SEP-57KPRZ3JQVENLNBR -p tcp -m comment --comment "default/hostnames:" -m tcp -j DNAT --to-destination 10.244.3.6:9376
-A KUBE-SEP-WNBA2IHDGP2BOBGZ -s 10.244.1.7/32 -m comment --comment "default/hostnames:" -j MARK --set-xmark 0x00004000/0x00004000
-A KUBE-SEP-WNBA2IHDGP2BOBGZ -p tcp -m comment --comment "default/hostnames:" -m tcp -j DNAT --to-destination 10.244.1.7:9376
-A KUBE-SEP-X3P2623AGDH6CDF3 -s 10.244.2.3/32 -m comment --comment "default/hostnames:" -j MARK --set-xmark 0x00004000/0x00004000
-A KUBE-SEP-X3P2623AGDH6CDF3 -p tcp -m comment --comment "default/hostnames:" -m tcp -j DNAT --to-destination 10.244.2.3:9376
-A KUBE-SERVICES -d 10.0.1.175/32 -p tcp -m comment --comment "default/hostnames: cluster IP" -m tcp --dport 80 -j KUBE-SVC-NWV5X2332I4OT4T3
-A KUBE-SVC-NWV5X2332I4OT4T3 -m comment --comment "default/hostnames:" -m statistic --mode random --probability 0.33332999982 -j KUBE-SEP-WNBA2IHDGP2BOBGZ
-A KUBE-SVC-NWV5X2332I4OT4T3 -m comment --comment "default/hostnames:" -m statistic --mode random --probability 0.50000000000 -j KUBE-SEP-X3P2623AGDH6CDF3
-A KUBE-SVC-NWV5X2332I4OT4T3 -m comment --comment "default/hostnames:" -j KUBE-SEP-57KPRZ3JQVENLNBR

对于每个 Service 的每个端口，KUBE-SERVICES 中应该有 1 条规则和 1 个 KUBE-SVC-<hash> 链。对于每个 Pod 端点，在该 KUBE-SVC-<hash> 链中应该有少量规则，并且有一个 KUBE-SEP-<hash> 链，其中包含少量规则。确切的规则将根据你的具体配置（包括节点端口和负载均衡器）而有所不同。

IPVS 模式

在 "ipvs" 模式下，你应该在节点上看到类似以下内容：

ipvsadm -ln

Prot LocalAddress:Port Scheduler Flags
  -> RemoteAddress:Port           Forward Weight ActiveConn InActConn
...
TCP  10.0.1.175:80 rr
  -> 10.244.0.5:9376               Masq    1      0          0
  -> 10.244.0.6:9376               Masq    1      0          0
  -> 10.244.0.7:9376               Masq    1      0          0
...

对于每个 Service 的每个端口，加上任何 NodePort、外部 IP 和负载均衡器 IP，kube-proxy 都会创建一个虚拟服务器。对于每个 Pod 端点，它会创建相应的真实服务器。在此示例中，服务 hostnames (10.0.1.175:80) 有 3 个端点 (10.244.0.5:9376, 10.244.0.6:9376, 10.244.0.7:9376)。

kube-proxy 是否在进行代理转发？

假设你确实看到了上述情况之一，请再次尝试从你的某个节点通过 IP 访问你的 Service：

curl 10.0.1.175:80

hostnames-632524106-bbpiw

如果这仍然失败，请查看 kube-proxy 日志中是否有特定的行，例如：

Setting endpoints for default/hostnames:default to [10.244.0.5:9376 10.244.0.6:9376 10.244.0.7:9376]

如果你没有看到这些，请尝试以 -v 标志设置为 4 的方式重启 kube-proxy，然后再次查看日志。

边缘情况：Pod 无法通过服务 IP 访问自身

这听起来可能不太可能，但确实会发生，而且它应该能够工作。

当网络没有为“发夹”（hairpin）流量正确配置时，通常会发生这种情况，即当 kube-proxy 运行在 iptables 模式下且 Pod 使用网桥网络连接时。Kubelet 暴露了一个 hairpin-mode 标志，它允许 Service 的端点在它们尝试访问自己的 Service VIP 时将其负载均衡回自身。hairpin-mode 标志必须设置为 hairpin-veth 或 promiscuous-bridge。

排查此问题的常见步骤如下：

确认 hairpin-mode 已设置为 hairpin-veth 或 promiscuous-bridge。你应该看到类似下面的内容。在以下示例中，hairpin-mode 被设置为 promiscuous-bridge。

ps auxw | grep kubelet

root      3392  1.1  0.8 186804 65208 ?        Sl   00:51  11:11 /usr/local/bin/kubelet --enable-debugging-handlers=true --config=/etc/kubernetes/manifests --allow-privileged=True --v=4 --cluster-dns=10.0.0.10 --cluster-domain=cluster.local --configure-cbr0=true --cgroup-root=/ --system-cgroups=/system --hairpin-mode=promiscuous-bridge --runtime-cgroups=/docker-daemon --kubelet-cgroups=/kubelet --babysit-daemons=true --max-pods=110 --serialize-image-pulls=false --outofdisk-transition-frequency=0

确认有效的 hairpin-mode。为此，你必须查看 kubelet 日志。访问日志取决于你的节点操作系统。在某些操作系统上它是一个文件，例如 /var/log/kubelet.log，而其他操作系统则使用 journalctl 来访问日志。请注意，由于兼容性原因，有效的 hairpin 模式可能与 --hairpin-mode 标志不匹配。检查 kubelet.log 中是否有任何带有关键字 hairpin 的日志行。应该有指示有效 hairpin 模式的日志行，如下所示。

I0629 00:51:43.648698    3252 kubelet.go:380] Hairpin mode set to "promiscuous-bridge"

如果有效的 hairpin 模式是 hairpin-veth，请确保 Kubelet 有权在节点上操作 /sys。如果一切正常工作，你应该看到类似以下内容：

for intf in /sys/devices/virtual/net/cbr0/brif/*; do cat $intf/hairpin_mode; done

如果有效的 hairpin 模式是 promiscuous-bridge，请确保 Kubelet 有权操作节点上的 Linux 网桥。如果使用了 cbr0 网桥且配置正确，你应该看到：

ifconfig cbr0 |grep PROMISC

UP BROADCAST RUNNING PROMISC MULTICAST  MTU:1460  Metric:1

如果以上都不起作用，请寻求帮助。

寻求帮助

如果你走到了这一步，说明发生了非常奇怪的事情。你的 Service 正在运行，有 EndpointSlices，并且你的 Pod 确实在提供服务。DNS 工作正常，且 kube-proxy 看起来没有出现异常。然而，你的 Service 仍然无法工作。请让我们知道发生了什么，以便我们协助调查！

在 Slack 或论坛或 GitHub 上联系我们。

接下来

访问故障排除概览文档获取更多信息。

最后修改时间：2025 年 4 月 9 日上午 5:08 PST：更新文档以弃用 Endpoints API (#49831) (649bda2cbd)

调试服务

在 Pod 中运行命令

说明

设置

服务是否存在？

是否有任何网络策略（Network Policy）入站规则影响目标 Pod？

服务是否能通过 DNS 名称正常工作？

说明

是否有任何服务能通过 DNS 名称正常工作？

服务是否能通过 IP 地址正常工作？

服务定义是否正确？

服务是否有任何 EndpointSlice？

Pod 是否正常工作？

说明

kube-proxy 是否正常工作？

kube-proxy 是否在运行？

Iptables 模式

IPVS 模式

kube-proxy 是否在进行代理转发？

边缘情况：Pod 无法通过服务 IP 访问自身

寻求帮助

接下来

反馈