kubeadm 故障排除

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

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

如果您认为您的问题是 kubeadm 的错误
- 转到 github.com/kubernetes/kubeadm 并搜索现有问题。
- 如果不存在问题，请打开一个并遵循问题模板。
如果您不确定 kubeadm 的工作原理，您可以在 Slack 的 #kubeadm 中提问，或在 StackOverflow 上打开一个问题。请包含相关的标签，如 #kubernetes 和 #kubeadm，以便人们可以帮助您。

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

在 v1.18 中，kubeadm 添加了防止在集群中加入节点的机制，如果存在具有相同名称的节点。这需要为 bootstrap-token 用户添加 RBAC，以便能够获取节点对象。

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

要解决此问题，您有两个选择

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

或者

使用 kubectl apply -f ... 手动应用以下 RBAC

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kubeadm:get-nodes
rules:
  - apiGroups:
      - ""
    resources:
      - nodes
    verbs:
      - get
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kubeadm:get-nodes
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kubeadm:get-nodes
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: Group
    name: system:bootstrappers:kubeadm:default-node-token

在安装过程中找不到 `ebtables` 或类似的可执行文件

如果您在运行 kubeadm init 时看到以下警告

[preflight] WARNING: ebtables not found in system path
[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 在打印出以下行后挂起

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

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

网络连接问题。在继续之前，请检查您的机器是否具有完整的网络连接。
容器运行时的 cgroup 驱动程序与 kubelet 的 cgroup 驱动程序不同。要了解如何正确配置它，请参阅配置 cgroup 驱动程序。
控制平面容器正在崩溃循环或挂起。您可以通过运行 docker ps 并通过运行 docker logs 检查每个容器来检查这一点。对于其他容器运行时，请参阅使用 crictl 调试 Kubernetes 节点。

kubeadm 在删除托管容器时阻塞

如果容器运行时停止并且没有删除任何 Kubernetes 托管容器，则可能会发生以下情况

sudo kubeadm reset

[preflight] Running pre-flight checks
[reset] Stopping the kubelet service
[reset] Unmounting mounted directories in "/var/lib/kubelet"
[reset] Removing kubernetes-managed containers
(block)

可能的解决方案是重新启动容器运行时，然后重新运行 kubeadm reset。您也可以使用 crictl 调试容器运行时的状态。请参阅使用 crictl 调试 Kubernetes 节点。

Pod 处于 `RunContainerError`、`CrashLoopBackOff` 或 `Error` 状态

在 kubeadm init 之后，不应该有任何 Pod 处于这些状态。

如果在 kubeadm init 之后，Pod 处于这些状态之一，请在 kubeadm 存储库中打开一个问题。coredns（或 kube-dns）应该处于 Pending 状态，直到您部署网络附加组件。
如果您在部署网络附加组件后看到 Pod 处于 RunContainerError、CrashLoopBackOff 或 Error 状态，并且 coredns（或 kube-dns）没有任何反应，则很可能是您安装的 Pod 网络附加组件存在问题。您可能需要授予它更多 RBAC 权限或使用更新的版本。请在 Pod 网络提供商的问题跟踪器中提交一个问题，并让问题在那里得到分类。

`coredns` 停留在 `Pending` 状态

这是预期的，并且是设计的一部分。kubeadm 与网络提供商无关，因此管理员应该安装他们选择的 Pod 网络附加组件。您必须在 CoreDNS 可以完全部署之前安装 Pod 网络。因此，在设置网络之前，它处于 Pending 状态。

`HostPort` 服务不起作用

HostPort 和 HostIP 功能是否可用取决于您的 Pod 网络提供商。请联系 Pod 网络附加组件的作者，以了解 HostPort 和 HostIP 功能是否可用。

Calico、Canal 和 Flannel CNI 提供商已验证支持 HostPort。

有关更多信息，请参阅 CNI portmap 文档。

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

无法通过其服务 IP 访问 Pod

许多网络附加组件尚未启用发夹模式，该模式允许 Pod 通过其服务 IP 访问自身。这是与 CNI 相关的问题。请联系网络附加组件提供商以获取其对发夹模式支持的最新状态。
如果您使用的是 VirtualBox（直接或通过 Vagrant），您需要确保 hostname -i 返回一个可路由的 IP 地址。默认情况下，第一个接口连接到不可路由的专用网络。解决方法是修改 /etc/hosts，请参阅此 Vagrantfile 以获取示例。

TLS 证书错误

以下错误表示可能存在证书不匹配。

# kubectl get pods
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 环境变量
```
unset KUBECONFIG
```
或将其设置为默认的 KUBECONFIG 位置
```
export KUBECONFIG=/etc/kubernetes/admin.conf
```

另一种解决方法是覆盖现有 kubeconfig 以用于“admin”用户

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

Kubelet 客户端证书轮换失败

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

备份并删除 /etc/kubernetes/kubelet.conf 和 /var/lib/kubelet/pki/kubelet-client*，这些文件来自失败的节点。
从集群中具有 /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 中的嵌入式证书进行签名。
将生成的 kubelet.conf 复制到失败节点上的 /etc/kubernetes/kubelet.conf。
重新启动失败节点上的 kubelet（systemctl restart kubelet）并等待 /var/lib/kubelet/pki/kubelet-client-current.pem 被重新创建。
通过将 client-certificate-data 和 client-key-data 替换为以下内容，手动编辑 kubelet.conf 以指向已轮换的 kubelet 客户端证书
```
client-certificate: /var/lib/kubelet/pki/kubelet-client-current.pem
client-key: /var/lib/kubelet/pki/kubelet-client-current.pem
```
重新启动 kubelet。
确保节点变为 Ready。

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

以下错误可能表示 Pod 网络存在问题

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

如果您在 Vagrant 中使用 flannel 作为 Pod 网络，那么您将必须为 flannel 指定默认接口名称。
Vagrant 通常会为所有 VM 分配两个接口。第一个接口（所有主机都分配了 IP 地址 10.0.2.15）用于进行 NAT 的外部流量。
这可能会导致 flannel 出现问题，因为 flannel 默认使用主机上的第一个接口。这会导致所有主机认为它们具有相同的公网 IP 地址。为了防止这种情况，请将 --iface eth1 标志传递给 flannel，以便选择第二个接口。

用于容器的非公网 IP

在某些情况下，kubectl logs 和 kubectl run 命令可能会在功能正常的集群中返回以下错误

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 为 eth0 分配了一个公网 IP，以及一个用于内部使用的私网 IP，作为其浮动 IP 功能的锚点，但 kubelet 会选择后者作为节点的 InternalIP，而不是公网 IP。
使用 ip addr show 检查这种情况，而不是 ifconfig，因为 ifconfig 不会显示有问题的别名 IP 地址。或者，DigitalOcean 的特定 API 端点允许从 Droplet 查询锚点 IP。
```
curl http://169.254.169.254/metadata/v1/interfaces/public/0/anchor_ipv4/address
```
解决方法是使用 --node-ip 告诉 kubelet 使用哪个 IP。使用 DigitalOcean 时，它可以是公网 IP（分配给 eth0）或私网 IP（分配给 eth1），如果您想使用可选的私有网络。kubeadm NodeRegistrationOptions 结构的 kubeletExtraArgs 部分可用于此目的。
然后重启 kubelet
```
systemctl daemon-reload
systemctl restart kubelet
```

`coredns` Pod 处于 `CrashLoopBackOff` 或 `Error` 状态

如果您有运行 SELinux 的节点，并且使用的是旧版本的 Docker，您可能会遇到 coredns Pod 无法启动的情况。要解决此问题，您可以尝试以下选项之一

升级到较新版本的 Docker。
禁用 SELinux.
修改 coredns 部署，将 allowPrivilegeEscalation 设置为 true

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

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

警告

禁用 SELinux 或将 allowPrivilegeEscalation 设置为 true 会降低集群的安全性。

etcd Pod 不断重启

如果您遇到以下错误

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\""

如果您在 CentOS 7 上运行 Docker 1.13.1.84，则会出现此问题。此版本的 Docker 可能会阻止 kubelet 执行到 etcd 容器中。

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

回滚到旧版本的 Docker，例如 1.13.1-75

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

sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
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 中看到以下错误

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

已知的解决方案是修补 kube-proxy DaemonSet，允许它在控制平面节点上调度，无论其条件如何，直到其初始保护条件消失之前，才将其调度到其他节点上。

kubectl -n kube-system patch ds kube-proxy -p='{
  "spec": {
    "template": {
      "spec": {
        "tolerations": [
          {
            "key": "CriticalAddonsOnly",
            "operator": "Exists"
          },
          {
            "effect": "NoSchedule",
            "key": "node-role.kubernetes.io/control-plane"
          }
        ]
      }
    }
  }
}'

此问题的跟踪问题在这里。

`/usr` 在节点上以只读方式挂载

在 Fedora CoreOS 或 Flatcar Container Linux 等 Linux 发行版上，目录 /usr 被挂载为只读文件系统。对于 flex-volume 支持，Kubernetes 组件（如 kubelet 和 kube-controller-manager）使用默认路径 /usr/libexec/kubernetes/kubelet-plugins/volume/exec/，但 flex-volume 目录 *必须可写*，才能使该功能正常工作。

注意

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

要解决此问题，您可以使用 kubeadm 配置文件配置 flex-volume 目录。

在主控制平面节点（使用 kubeadm init 创建）上，使用 --config 传递以下文件

apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
nodeRegistration:
  kubeletExtraArgs:
    volume-plugin-dir: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
controllerManager:
  extraArgs:
    flex-volume-plugin-dir: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"

在加入节点上

apiVersion: kubeadm.k8s.io/v1beta3
kind: JoinConfiguration
nodeRegistration:
  kubeletExtraArgs:
    volume-plugin-dir: "/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 目录。

这是 kubeadm 1.15 中引入的回归。此问题在 1.20 中已修复。

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

在 kubeadm 集群中，metrics-server 可以通过向其传递 --kubelet-insecure-tls 来不安全地使用。不建议在生产集群中使用此方法。

如果您想在 metrics-server 和 kubelet 之间使用 TLS，则会遇到问题，因为 kubeadm 为 kubelet 部署了自签名服务证书。这会导致 metrics-server 端出现以下错误

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

请参阅启用签名的 kubelet 服务证书，了解如何在 kubeadm 集群中配置 kubelet 以拥有正确签名的服务证书。

另请参阅如何安全地运行 metrics-server。

升级失败，因为 etcd 哈希未更改

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

您可能会遇到以下错误消息

[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
[upgrade/etcd] Waiting for previous etcd to become available
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
[upgrade/etcd] Etcd was rolled back and is now available
static Pod hash for component etcd on Node kinder-upgrade-control-plane-1 did not change after 5m0s: timed out waiting for the condition
couldn't upgrade control plane. kubeadm has tried to recover everything into the earlier state. Errors faced
k8s.io/kubernetes/cmd/kubeadm/app/phases/upgrade.rollbackOldManifests
	cmd/kubeadm/app/phases/upgrade/staticpods.go:525
k8s.io/kubernetes/cmd/kubeadm/app/phases/upgrade.upgradeComponent
	cmd/kubeadm/app/phases/upgrade/staticpods.go:254
k8s.io/kubernetes/cmd/kubeadm/app/phases/upgrade.performEtcdStaticPodUpgrade
	cmd/kubeadm/app/phases/upgrade/staticpods.go:338
...

此失败的原因是受影响的版本会生成一个 etcd 清单文件，其中包含 PodSpec 中不需要的默认值。这会导致清单比较产生差异，kubeadm 会期望 Pod 哈希发生变化，但 kubelet 永远不会更新哈希。

如果您在集群中看到此问题，有两种方法可以解决此问题

可以使用以下方法跳过受影响版本和 v1.28.3（或更高版本）之间的 etcd 升级
```
kubeadm upgrade {apply|node} [version] --etcd-upgrade=false
```
如果在后面的 v1.28 修补版本中引入了新的 etcd 版本，则不建议这样做。

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

diff --git a/etc/kubernetes/manifests/etcd_defaults.yaml b/etc/kubernetes/manifests/etcd_origin.yaml
index d807ccbe0aa..46b35f00e15 100644
--- a/etc/kubernetes/manifests/etcd_defaults.yaml
+++ b/etc/kubernetes/manifests/etcd_origin.yaml
@@ -43,7 +43,6 @@ spec:
        scheme: HTTP
      initialDelaySeconds: 10
      periodSeconds: 10
-      successThreshold: 1
      timeoutSeconds: 15
    name: etcd
    resources:
@@ -59,26 +58,18 @@ spec:
        scheme: HTTP
      initialDelaySeconds: 10
      periodSeconds: 10
-      successThreshold: 1
      timeoutSeconds: 15
-    terminationMessagePath: /dev/termination-log
-    terminationMessagePolicy: File
    volumeMounts:
    - mountPath: /var/lib/etcd
      name: etcd-data
    - mountPath: /etc/kubernetes/pki/etcd
      name: etcd-certs
-  dnsPolicy: ClusterFirst
-  enableServiceLinks: true
  hostNetwork: true
  priority: 2000001000
  priorityClassName: system-node-critical
-  restartPolicy: Always
-  schedulerName: default-scheduler
  securityContext:
    seccompProfile:
      type: RuntimeDefault
-  terminationGracePeriodSeconds: 30
  volumes:
  - hostPath:
      path: /etc/kubernetes/pki/etcd

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

上次修改时间：2024 年 2 月 16 日下午 5:50 PST：更新 kubeconfig 用户 --config (3ab10b2b94)