对 kubeadm 进行故障排查

与任何程序一样，你可能会在安装或者运行 kubeadm 时遇到错误。 本文列举了一些常见的故障场景，并提供可帮助你理解和解决这些问题的步骤。

如果你的问题未在下面列出，请执行以下步骤：

  • 如果你认为问题是 kubeadm 的错误：

  • 如果你对 kubeadm 的工作方式有疑问，可以在 Slack 上的 #kubeadm 频道提问， 或者在 StackOverflow 上提问。 请加入相关标签，例如 #kubernetes 和 #kubeadm，这样其他人可以帮助你。

由于缺少 RBAC，无法将 v1.18 Node 加入 v1.17 集群

自从 v1.18 后，如果集群中已存在同名 Node，kubeadm 将禁止 Node 加入集群。 这需要为 bootstrap-token 用户添加 RBAC 才能 GET Node 对象。

但这会导致一个问题，v1.18 的 kubeadm join 无法加入由 kubeadm v1.17 创建的集群。

要解决此问题，你有两种选择：

使用 kubeadm v1.18 在控制平面节点上执行 kubeadm init phase bootstrap-token。 请注意，这也会启用 bootstrap-token 的其余权限。

或者，也可以使用 kubectl apply -f ... 手动应用以下 RBAC：

  1. apiVersion: rbac.authorization.k8s.io/v1
  2. kind: ClusterRole
  3. metadata:
  4.   name: kubeadm:get-nodes
  5. rules:
  6. - apiGroups:
  7.   - ""
  8.   resources:
  9.   - nodes
  10.   verbs:
  11.   - get
  12. ---
  13. apiVersion: rbac.authorization.k8s.io/v1
  14. kind: ClusterRoleBinding
  15. metadata:
  16.   name: kubeadm:get-nodes
  17. roleRef:
  18.   apiGroup: rbac.authorization.k8s.io
  19.   kind: ClusterRole
  20.   name: kubeadm:get-nodes
  21. subjects:
  22. - apiGroup: rbac.authorization.k8s.io
  23.   kind: Group
  24.   name: system:bootstrappers:kubeadm:default-node-token

在安装过程中没有找到 ebtables 或者其他类似的可执行文件

如果在运行 kubeadm init 命令时，遇到以下的警告

  1. [preflight] WARNING: ebtables not found in system path
  2. [preflight] WARNING: ethtool not found in system path

那么或许在你的节点上缺失 ebtables、ethtool 或者类似的可执行文件。 你可以使用以下命令安装它们：

  • 对于 Ubuntu/Debian 用户，运行 apt install ebtables ethtool 命令。
  • 对于 CentOS/Fedora 用户，运行 yum install ebtables ethtool 命令。

在安装过程中，kubeadm 一直等待控制平面就绪

如果你注意到 kubeadm init 在打印以下行后挂起：

  1. [apiclient] Created API client, waiting for the control plane to become ready

这可能是由许多问题引起的。最常见的是：

  • 网络连接问题。在继续之前，请检查你的计算机是否具有全部联通的网络连接。
  • 容器运行时的 cgroup 驱动不同于 kubelet 使用的 cgroup 驱动。要了解如何正确配置 cgroup 驱动， 请参阅配置 cgroup 驱动。
  • 控制平面上的 Docker 容器持续进入崩溃状态或（因其他原因）挂起。你可以运行 docker ps 命令来检查以及 docker logs 命令来检视每个容器的运行日志。 对于其他容器运行时，请参阅使用 crictl 对 Kubernetes 节点进行调试。

当删除托管容器时 kubeadm 阻塞

如果容器运行时停止并且未删除 Kubernetes 所管理的容器，可能发生以下情况：

  1. sudo kubeadm reset
  1. [preflight] Running pre-flight checks
  2. [reset] Stopping the kubelet service
  3. [reset] Unmounting mounted directories in "/var/lib/kubelet"
  4. [reset] Removing kubernetes-managed containers
  5. (block)

一个可行的解决方案是重新启动 Docker 服务，然后重新运行 kubeadm reset： 你也可以使用 crictl 来调试容器运行时的状态。 参见使用 CRICTL 调试 Kubernetes 节点。

Pod 处于 RunContainerError、CrashLoopBackOff 或者 Error 状态

在 kubeadm init 命令运行后，系统中不应该有 Pod 处于这类状态。

  • 在 kubeadm init 命令执行完后，如果有 Pod 处于这些状态之一，请在 kubeadm 仓库提起一个 issue。coredns (或者 kube-dns) 应该处于 Pending 状态， 直到你部署了网络插件为止。

  • 如果在部署完网络插件之后，有 Pod 处于 RunContainerError、CrashLoopBackOff 或 Error 状态之一，并且 coredns （或者 kube-dns）仍处于 Pending 状态， 那很可能是你安装的网络插件由于某种原因无法工作。你或许需要授予它更多的 RBAC 特权或使用较新的版本。请在 Pod Network 提供商的问题跟踪器中提交问题， 然后在此处分类问题。

coredns 停滞在 Pending 状态

这一行为是预期之中的，因为系统就是这么设计的。kubeadm 的网络供应商是中立的， 因此管理员应该选择安装 Pod 的网络插件。 你必须完成 Pod 的网络配置，然后才能完全部署 CoreDNS。 在网络被配置好之前，DNS 组件会一直处于 Pending 状态。

HostPort 服务无法工作

此 HostPort 和 HostIP 功能是否可用取决于你的 Pod 网络配置。请联系 Pod 网络插件的作者， 以确认 HostPort 和 HostIP 功能是否可用。

已验证 Calico、Canal 和 Flannel CNI 驱动程序支持 HostPort。

有关更多信息，请参考 CNI portmap 文档.

如果你的网络提供商不支持 portmap CNI 插件，你或许需要使用 NodePort 服务的功能或者使用 HostNetwork=true。

无法通过其服务 IP 访问 Pod

  • 许多网络附加组件尚未启用 hairpin 模式 该模式允许 Pod 通过其服务 IP 进行访问。这是与 CNI 有关的问题。 请与网络附加组件提供商联系，以获取他们所提供的 hairpin 模式的最新状态。

  • 如果你正在使用 VirtualBox (直接使用或者通过 Vagrant 使用)，你需要 确保 hostname -i 返回一个可路由的 IP 地址。默认情况下，第一个接口连接不能路由的仅主机网络。 解决方法是修改 /etc/hosts，请参考示例 Vagrantfile。

TLS 证书错误

以下错误说明证书可能不匹配。

  1. # kubectl get pods
  2. Unable to connect to the server: x509: certificate signed by unknown authority (possibly because of "crypto/rsa: verification error" while trying to verify candidate authority certificate "kubernetes")

  • 验证 $HOME/.kube/config 文件是否包含有效证书， 并在必要时重新生成证书。在 kubeconfig 文件中的证书是 base64 编码的。 该 base64 --decode 命令可以用来解码证书，openssl x509 -text -noout 命令可以用于查看证书信息。

  • 使用如下方法取消设置 KUBECONFIG 环境变量的值：

    1. unset KUBECONFIG

    或者将其设置为默认的 KUBECONFIG 位置：

    1. export KUBECONFIG=/etc/kubernetes/admin.conf

  • 另一个方法是覆盖 kubeconfig 的现有用户 “管理员”：

    1. mv $HOME/.kube $HOME/.kube.bak
    2. mkdir $HOME/.kube
    3. sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
    4. sudo chown $(id -u):$(id -g) $HOME/.kube/config

Kubelet 客户端证书轮换失败

默认情况下，kubeadm 使用 /etc/kubernetes/kubelet.conf 中指定的 /var/lib/kubelet/pki/kubelet-client-current.pem 符号链接来配置 kubelet 自动轮换客户端证书。如果此轮换过程失败，你可能会在 kube-apiserver 日志中看到诸如 x509: certificate has expired or is not yet valid 之类的错误。要解决此问题，你必须执行以下步骤：

  1. 从故障节点备份和删除 /etc/kubernetes/kubelet.conf 和 /var/lib/kubelet/pki/kubelet-client*。

  2. 在集群中具有 /etc/kubernetes/pki/ca.key 的、正常工作的控制平面节点上 执行 kubeadm kubeconfig user --org system:nodes --client-name system:node:$NODE > kubelet.conf。 $NODE 必须设置为集群中现有故障节点的名称。 手动修改生成的 kubelet.conf 以调整集群名称和服务器端点， 或传递 kubeconfig user --config （请参阅为其他用户生成 kubeconfig 文件）。 如果你的集群没有 ca.key，你必须在外部对 kubelet.conf 中的嵌入式证书进行签名。

  3. 将得到的 kubelet.conf 文件复制到故障节点上，作为 /etc/kubernetes/kubelet.conf。

  4. 在故障节点上重启 kubelet（systemctl restart kubelet），等待 /var/lib/kubelet/pki/kubelet-client-current.pem 重新创建。

  5. 手动编辑 kubelet.conf 指向轮换的 kubelet 客户端证书，方法是将 client-certificate-data 和 client-key-data 替换为：

    1. client-certificate: /var/lib/kubelet/pki/kubelet-client-current.pem
    2. client-key: /var/lib/kubelet/pki/kubelet-client-current.pem

  6. 重新启动 kubelet。

  7. 确保节点状况变为 Ready。

在 Vagrant 中使用 flannel 作为 Pod 网络时的默认 NIC

以下错误可能表明 Pod 网络中出现问题：

  1. Error from server (NotFound): the server could not find the requested resource

  • 如果你正在 Vagrant 中使用 flannel 作为 Pod 网络，则必须指定 flannel 的默认接口名称。

    Vagrant 通常为所有 VM 分配两个接口。第一个为所有主机分配了 IP 地址 10.0.2.15，用于获得 NATed 的外部流量。

    这可能会导致 flannel 出现问题，它默认为主机上的第一个接口。这导致所有主机认为它们具有相同的公共 IP 地址。为防止这种情况，传递 --iface eth1 标志给 flannel 以便选择第二个接口。

容器使用的非公共 IP

在某些情况下 kubectl logs 和 kubectl run 命令或许会返回以下错误，即便除此之外集群一切功能正常：

  1. Error from server: Get https://10.19.0.41:10250/containerLogs/default/mysql-ddc65b868-glc5m/mysql: dial tcp 10.19.0.41:10250: getsockopt: no route to host

  • 这或许是由于 Kubernetes 使用的 IP 无法与看似相同的子网上的其他 IP 进行通信的缘故， 可能是由机器提供商的政策所导致的。

  • DigitalOcean 既分配一个共有 IP 给 eth0，也分配一个私有 IP 在内部用作其浮动 IP 功能的锚点， 然而 kubelet 将选择后者作为节点的 InternalIP 而不是公共 IP。

    使用 ip addr show 命令代替 ifconfig 命令去检查这种情况，因为 ifconfig 命令 不会显示有问题的别名 IP 地址。或者指定的 DigitalOcean 的 API 端口允许从 droplet 中 查询 anchor IP：

    1. curl http://169.254.169.254/metadata/v1/interfaces/public/0/anchor_ipv4/address

    解决方法是通知 kubelet 使用哪个 --node-ip。当使用 DigitalOcean 时，可以是（分配给 eth0 的）公网 IP， 或者是（分配给 eth1 的）私网 IP。私网 IP 是可选的。 kubadm NodeRegistrationOptions 结构 的 KubeletExtraArgs 部分被用来处理这种情况。

    然后重启 kubelet：

    1. systemctl daemon-reload
    2. systemctl restart kubelet

coredns Pod 有 CrashLoopBackOff 或者 Error 状态

如果有些节点运行的是旧版本的 Docker，同时启用了 SELinux，你或许会遇到 coredns Pod 无法启动的情况。 要解决此问题，你可以尝试以下选项之一：

  1. kubectl -n kube-system get deployment coredns -o yaml | \
  2.   sed 's/allowPrivilegeEscalation: false/allowPrivilegeEscalation: true/g' | \
  3.   kubectl apply -f -

CoreDNS 处于 CrashLoopBackOff 时的另一个原因是当 Kubernetes 中部署的 CoreDNS Pod 检测到环路时。 有许多解决方法 可以避免在每次 CoreDNS 监测到循环并退出时，Kubernetes 尝试重启 CoreDNS Pod 的情况。

警告：

禁用 SELinux 或设置 allowPrivilegeEscalation 为 true 可能会损害集群的安全性。

etcd Pod 持续重启

如果你遇到以下错误：

  1. rpc error: code = 2 desc = oci runtime error: exec failed: container_linux.go:247: starting container process caused "process_linux.go:110: decoding init error from pipe caused \"read parent: connection reset by peer\""

如果你使用 Docker 1.13.1.84 运行 CentOS 7 就会出现这种问题。 此版本的 Docker 会阻止 kubelet 在 etcd 容器中执行。

为解决此问题，请选择以下选项之一：

  • 回滚到早期版本的 Docker，例如 1.13.1-75

    1. yum downgrade docker-1.13.1-75.git8633870.el7.centos.x86_64 docker-client-1.13.1-75.git8633870.el7.centos.x86_64 docker-common-1.13.1-75.git8633870.el7.centos.x86_64

  • 安装较新的推荐版本之一，例如 18.06：

    1. sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
    2. yum install docker-ce-18.06.1.ce-3.el7.x86_64

无法将以逗号分隔的值列表传递给 --component-extra-args 标志内的参数

kubeadm init 标志例如 --component-extra-args 允许你将自定义参数传递给像 kube-apiserver 这样的控制平面组件。然而，由于解析 (mapStringString) 的基础类型值，此机制将受到限制。

如果你决定传递一个支持多个逗号分隔值（例如 --apiserver-extra-args "enable-admission-plugins=LimitRanger,NamespaceExists"）参数， 将出现 flag: malformed pair, expect string=string 错误。 发生这种问题是因为参数列表 --apiserver-extra-args 预期的是 key=value 形式， 而这里的 NamespacesExists 被误认为是缺少取值的键名。

一种解决方法是尝试分离 key=value 对，像这样： --apiserver-extra-args "enable-admission-plugins=LimitRanger,enable-admission-plugins=NamespaceExists" 但这将导致键 enable-admission-plugins 仅有值 NamespaceExists。

已知的解决方法是使用 kubeadm 配置文件。

在节点被云控制管理器初始化之前，kube-proxy 就被调度了

在云环境场景中，可能出现在云控制管理器完成节点地址初始化之前，kube-proxy 就被调度到新节点了。 这会导致 kube-proxy 无法正确获取节点的 IP 地址，并对管理负载平衡器的代理功能产生连锁反应。

在 kube-proxy Pod 中可以看到以下错误：

  1. server.go:610] Failed to retrieve node IP: host IP unknown; known addresses: []
  2. proxier.go:340] invalid nodeIP, initializing kube-proxy with 127.0.0.1 as nodeIP

一种已知的解决方案是修补 kube-proxy DaemonSet，以允许在控制平面节点上调度它， 而不管它们的条件如何，将其与其他节点保持隔离，直到它们的初始保护条件消除：

  1. kubectl -n kube-system patch ds kube-proxy -p='{
  2.   "spec": {
  3.     "template": {
  4.       "spec": {
  5.         "tolerations": [
  6.           {
  7.             "key": "CriticalAddonsOnly",
  8.             "operator": "Exists"
  9.           },
  10.           {
  11.             "effect": "NoSchedule",
  12.             "key": "node-role.kubernetes.io/control-plane"
  13.           }
  14.         ]
  15.       }
  16.     }
  17.   }
  18. }'

此问题的跟踪在这里。

节点上的 /usr 被以只读方式挂载

在类似 Fedora CoreOS 或者 Flatcar Container Linux 这类 Linux 发行版本中， 目录 /usr 是以只读文件系统的形式挂载的。 在支持 FlexVolume 时， 类似 kubelet 和 kube-controller-manager 这类 Kubernetes 组件使用默认路径 /usr/libexec/kubernetes/kubelet-plugins/volume/exec/， 而 FlexVolume 的目录必须是可写入的，该功能特性才能正常工作。

说明：

FlexVolume 在 Kubernetes v1.23 版本中已被弃用。

为了解决这个问题，你可以使用 kubeadm 的配置文件来配置 FlexVolume 的目录。

在（使用 kubeadm init 创建的）主控制节点上，使用 --config 参数传入如下文件：

  1. apiVersion: kubeadm.k8s.io/v1beta4
  2. kind: InitConfiguration
  3. nodeRegistration:
  4.   kubeletExtraArgs:
  5.   - name: "volume-plugin-dir"
  6.     value: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"
  7. ---
  8. apiVersion: kubeadm.k8s.io/v1beta4
  9. kind: ClusterConfiguration
  10. controllerManager:
  11.   extraArgs:
  12.   - name: "flex-volume-plugin-dir"
  13.     value: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"

在加入到集群中的节点上，使用下面的文件：

  1. apiVersion: kubeadm.k8s.io/v1beta4
  2. kind: JoinConfiguration
  3. nodeRegistration:
  4.   kubeletExtraArgs:
  5.   - name: "volume-plugin-dir"
  6.     value: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"

或者，你可以更改 /etc/fstab 使得 /usr 目录能够以可写入的方式挂载， 不过请注意这样做本质上是在更改 Linux 发行版的某种设计原则。

kubeadm upgrade plan 输出错误信息 context deadline exceeded

在使用 kubeadm 来升级某运行外部 etcd 的 Kubernetes 集群时可能显示这一错误信息。 这并不是一个非常严重的一个缺陷，之所以出现此错误信息，原因是老的 kubeadm 版本会对外部 etcd 集群执行版本检查。你可以继续执行 kubeadm upgrade apply ...。

这一问题已经在 1.19 版本中得到修复。

kubeadm reset 会卸载 /var/lib/kubelet

如果已经挂载了 /var/lib/kubelet 目录，执行 kubeadm reset 操作的时候会将其卸载。

要解决这一问题，可以在执行了 kubeadm reset 操作之后重新挂载 /var/lib/kubelet 目录。

这是一个在 1.15 中引入的故障，已经在 1.20 版本中修复。

无法在 kubeadm 集群中安全地使用 metrics-server

在 kubeadm 集群中可以通过为 metrics-server 设置 --kubelet-insecure-tls 来以不安全的形式使用该服务。 建议不要在生产环境集群中这样使用。

如果你需要在 metrics-server 和 kubelet 之间使用 TLS，会有一个问题， kubeadm 为 kubelet 部署的是自签名的服务证书。这可能会导致 metrics-server 端报告下面的错误信息：

  1. x509: certificate signed by unknown authority
  2. x509: certificate is valid for IP-foo not IP-bar

参见为 kubelet 启用签名的服务证书 以进一步了解如何在 kubeadm 集群中配置 kubelet 使用正确签名了的服务证书。

另请参阅 How to run the metrics-server securely。

因 etcd 哈希值无变化而升级失败

仅适用于通过 kubeadm 二进制文件 v1.28.3 或更高版本升级控制平面节点的情况， 其中此节点当前由 kubeadm v1.28.0、v1.28.1 或 v1.28.2 管理。

以下是你可能遇到的错误消息：

  1. [upgrade/etcd] Failed to upgrade etcd: couldn't upgrade control plane. kubeadm has tried to recover everything into the earlier state. Errors faced: static Pod hash for component etcd on Node kinder-upgrade-control-plane-1 did not change after 5m0s: timed out waiting for the condition
  2. [upgrade/etcd] Waiting for previous etcd to become available
  3. I0907 10:10:09.109104    3704 etcd.go:588] [etcd] attempting to see if all cluster endpoints ([https://172.17.0.6:2379/ https://172.17.0.4:2379/ https://172.17.0.3:2379/]) are available 1/10
  4. [upgrade/etcd] Etcd was rolled back and is now available
  5. static Pod hash for component etcd on Node kinder-upgrade-control-plane-1 did not change after 5m0s: timed out waiting for the condition
  6. couldn't upgrade control plane. kubeadm has tried to recover everything into the earlier state. Errors faced
  7. k8s.io/kubernetes/cmd/kubeadm/app/phases/upgrade.rollbackOldManifests
  8.     cmd/kubeadm/app/phases/upgrade/staticpods.go:525
  9. k8s.io/kubernetes/cmd/kubeadm/app/phases/upgrade.upgradeComponent
  10.     cmd/kubeadm/app/phases/upgrade/staticpods.go:254
  11. k8s.io/kubernetes/cmd/kubeadm/app/phases/upgrade.performEtcdStaticPodUpgrade
  12.     cmd/kubeadm/app/phases/upgrade/staticpods.go:338
  13. ...

本次失败的原因是受影响的版本在 PodSpec 中生成的 etcd 清单文件带有不需要的默认值。 这将导致与清单比较的差异，并且 kubeadm 预期 Pod 哈希值将发生变化，但 kubelet 永远不会更新哈希值。

如果你在集群中遇到此问题，有两种解决方法：

  • 可以运行以下命令跳过 etcd 的版本升级，即受影响版本和 v1.28.3（或更高版本）之间的版本升级:

    1. kubeadm upgrade {apply|node} [version] --etcd-upgrade=false

    但不推荐这种方法，因为后续的 v1.28 补丁版本可能引入新的 etcd 版本。

  • 在升级之前，对 etcd 静态 Pod 的清单进行修补，以删除有问题的默认属性:

    1. diff --git a/etc/kubernetes/manifests/etcd_defaults.yaml b/etc/kubernetes/manifests/etcd_origin.yaml
    2. index d807ccbe0aa..46b35f00e15 100644
    3. --- a/etc/kubernetes/manifests/etcd_defaults.yaml
    4. +++ b/etc/kubernetes/manifests/etcd_origin.yaml
    5. @@ -43,7 +43,6 @@ spec:
    6.         scheme: HTTP
    7.       initialDelaySeconds: 10
    8.       periodSeconds: 10
    9. -      successThreshold: 1
    10.       timeoutSeconds: 15
    11.     name: etcd
    12.     resources:
    13. @@ -59,26 +58,18 @@ spec:
    14.         scheme: HTTP
    15.       initialDelaySeconds: 10
    16.       periodSeconds: 10
    17. -      successThreshold: 1
    18.       timeoutSeconds: 15
    19. -    terminationMessagePath: /dev/termination-log
    20. -    terminationMessagePolicy: File
    21.     volumeMounts:
    22.     - mountPath: /var/lib/etcd
    23.       name: etcd-data
    24.     - mountPath: /etc/kubernetes/pki/etcd
    25.       name: etcd-certs
    26. -  dnsPolicy: ClusterFirst
    27. -  enableServiceLinks: true
    28.   hostNetwork: true
    29.   priority: 2000001000
    30.   priorityClassName: system-node-critical
    31. -  restartPolicy: Always
    32. -  schedulerName: default-scheduler
    33.   securityContext:
    34.     seccompProfile:
    35.       type: RuntimeDefault
    36. -  terminationGracePeriodSeconds: 30
    37.   volumes:
    38.   - hostPath:
    39.       path: /etc/kubernetes/pki/etcd

有关此错误的更多信息，请查阅此问题的跟踪页面。