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

  • 需要额外的工具 - base64openssl v3.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),确保它仍然安装和配置正确。