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 问题

• 需要额外工具：base64 和 openssl 版本 3.0 或更高版本。

Kubernetes API 服务器默认只提供 HTTPS 请求。在这种情况下，TLS 问题可能由于各种原因而发生，例如证书过期或信任链无效。

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

验证这些证书的过期时间

kubectl config view --flatten --output 'jsonpath={.clusters[0].cluster.certificate-authority-data}' | base64 -d | openssl x509 -noout -dates

输出

notBefore=Feb 13 05:57:47 2024 GMT
notAfter=Feb 10 06:02:47 2034 GMT

kubectl config view --flatten --output 'jsonpath={.users[0].user.client-certificate-data}'| base64 -d | openssl x509 -noout -dates

输出

notBefore=Feb 13 05:57:47 2024 GMT
notAfter=Feb 12 06:02:50 2025 GMT

验证 kubectl 助手

一些 kubectl 身份验证助手提供了便捷的 Kubernetes 集群访问方式。如果你曾使用这些助手并面临连接问题，请确保必要的配置仍然存在。

检查 kubectl 身份验证配置详情

kubectl config view

如果你以前使用过辅助工具（例如，kubectl-oidc-login），请确保它仍然安装并配置正确。