你正在查看的文档所针对的是 Kubernetes 版本： v1.29

Kubernetes v1.29 版本的文档已不再维护。你现在看到的版本来自于一份静态的快照。如需查阅最新文档，请点击最新版本。

kubectl 故障排查

本文讲述研判和诊断 kubectl 相关的问题。如果你在访问 kubectl 或连接到集群时遇到问题，本文概述了各种常见的情况和可能的解决方案，以帮助确定和解决可能的原因。

准备开始

你需要有一个 Kubernetes 集群。
你还需要安装好 kubectl，参见安装工具。

验证 kubectl 设置

确保你已在本机上正确安装和配置了 kubectl。检查 kubectl 版本以确保其是最新的，并与你的集群兼容。

检查 kubectl 版本：

kubectl version

你将看到类似的输出：

Client Version: version.Info{Major:"1", Minor:"27", GitVersion:"v1.27.4",GitCommit:"fa3d7990104d7c1f16943a67f11b154b71f6a132", GitTreeState:"clean",BuildDate:"2023-07-19T12:20:54Z", GoVersion:"go1.20.6", Compiler:"gc", Platform:"linux/amd64"}
Kustomize Version: v5.0.1
Server Version: version.Info{Major:"1", Minor:"27", GitVersion:"v1.27.3",GitCommit:"25b4e43193bcda6c7328a6d147b1fb73a33f1598", GitTreeState:"clean",BuildDate:"2023-06-14T09:47:40Z", GoVersion:"go1.20.5", Compiler:"gc", Platform:"linux/amd64"}

如果你看到 Unable to connect to the server: dial tcp <server-ip>:8443: i/o timeout，而不是 Server Version，则需要解决 kubectl 与你集群的连接问题。

确保按照 kubectl 官方安装文档安装了 kubectl，并正确配置了 $PATH 环境变量。

检查 kubeconfig

kubectl 需要一个 kubeconfig 文件来连接到 Kubernetes 集群。 kubeconfig 文件通常位于 ~/.kube/config 目录下。确保你有一个有效的 kubeconfig 文件。如果你没有 kubeconfig 文件，可以从 Kubernetes 管理员那里获取，或者可以从 Kubernetes 控制平面的 /etc/kubernetes/admin.conf 目录复制这个文件。如果你在云平台上部署了 Kubernetes 集群并且丢失了你的 kubeconfig 文件，则可以使用云厂商的工具重新生成它。参考云厂商的文档以重新生成 kubeconfig 文件。

检查 $KUBECONFIG 环境变量是否配置正确。你可以设置 $KUBECONFIG 环境变量，或者在 kubectl 中使用 --kubeconfig 参数来指定 kubeconfig 文件的目录。

检查 VPN 连接

如果你正在使用虚拟专用网络（VPN）访问 Kubernetes 集群，请确保你的 VPN 连接是可用且稳定的。有时，VPN 断开连接可能会导致与集群的连接问题。重新连接到 VPN，并尝试再次访问集群。

身份认证和鉴权

如果你正在使用基于令牌的身份认证，并且 kubectl 返回有关身份认证令牌或身份认证服务器地址的错误，校验 Kubernetes 身份认证令牌和身份认证服务器地址是否被配置正确。

如果 kubectl 返回有关鉴权的错误，确保你正在使用有效的用户凭据，并且你具有访问所请求资源的权限。

验证上下文

Kubernetes 支持多个集群和上下文。确保你正在使用正确的上下文与集群进行交互。

列出可用的上下文：

kubectl config get-contexts

切换到合适的上下文：

kubectl config use-context <context-name>

API 服务器和负载均衡器

kube-apiserver 服务器是 Kubernetes 集群的核心组件。如果 API 服务器或运行在 API 服务器前面的负载均衡器不可达或没有响应，你将无法与集群进行交互。

通过使用 ping 命令检查 API 服务器的主机是否可达。检查集群的网络连接和防火墙。如果你使用云厂商部署集群，请检查云厂商对集群的 API 服务器的健康检查状态。

验证负载均衡器（如果使用）的状态，确保其健康且转发流量到 API 服务器。

TLS 问题

Kubernetes API 服务器默认只为 HTTPS 请求提供服务。在这种情况下， TLS 问题可能会因各种原因而出现，例如证书过期或信任链有效性。

你可以在 kubeconfig 文件中找到 TLS 证书，此文件位于 ~/.kube/config 目录下。 certificate-authority 属性包含 CA 证书，而 client-certificate 属性则包含客户端证书。

验证这些证书的到期时间：

openssl x509 -noout -dates -in $(kubectl config view --minify --output 'jsonpath={.clusters[0].cluster.certificate-authority}')

输出为：

notBefore=Sep  2 08:34:12 2023 GMT
notAfter=Aug 31 08:34:12 2033 GMT

openssl x509 -noout -dates -in $(kubectl config view --minify --output 'jsonpath={.users[0].user.client-certificate}')