这篇文章已经一年多了，较旧的文章可能包含过时的内容。请检查从发表以来，页面中的信息是否变得不正确。

kubeadm：使用 etcd Learner 安全地接入控制平面节点

2023.09.25

作者: Paco Xu (DaoCloud)

译者: Michael Yao (DaoCloud)

kubeadm 工具现在支持 etcd learner 模式，借助 etcd 3.4 版本引入的 learner 模式特性，可以提高 Kubernetes 集群的弹性和稳定性。本文将介绍如何在 kubeadm 中使用 etcd learner 模式。默认情况下，kubeadm 在每个控制平面节点上运行一个本地 etcd 实例。

在 v1.27 中，kubeadm 引入了一个新的特性门控 EtcdLearnerMode。启用此特性门控后，在加入新的控制平面节点时，一个新的 etcd 成员将被创建为 learner，只有在 etcd 数据被完全对齐后此成员才会晋升为投票成员。

使用 etcd learner 模式的优势是什么？

在 Kubernetes 集群中采用 etcd learner 模式具有以下几个优点：

增强了弹性：etcd learner 节点是非投票成员，在完全进入角色之前会追随领导者的日志。这样可以防止新的集群成员干扰投票结果或引起领导者选举，从而使集群在成员变更期间更具弹性。
减少了集群不可用时间：传统的添加新成员的方法通常会造成一段时间集群不可用，特别是在基础设施迟缓或误配的情况下更为明显。而 etcd learner 模式可以最大程度地减少此类干扰。
简化了维护：learner 节点提供了一种更安全、可逆的方式来添加或替换集群成员。这降低了由于误配或在成员添加过程中出错而导致集群意外失效的风险。
改进了网络容错性：在涉及网络分区的场景中，learner 模式允许更优雅的处理。根据新成员所落入的分区，它可以无缝地与现有集群集成，而不会造成中断。

总之，etcd learner 模式可以在成员添加和变更期间提高 Kubernetes 集群的可靠性和可管理性，这个特性对集群运营人员很有价值。

节点如何接入使用这种新模式的集群

创建以 etcd learner 模式支撑的 Kubernetes 集群

关于使用 kubeadm 创建高可用集群的通用说明，请参阅使用 kubeadm 创建高可用集群。

要使用 kubeadm 创建一个后台是 learner 模式的 etcd 的 Kubernetes 集群，按照以下步骤操作：

# kubeadm init --feature-gates=EtcdLearnerMode=true ...
kubeadm init --config=kubeadm-config.yaml

kubeadm 配置文件如下：

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
featureGates:
  EtcdLearnerMode: true

这里，kubeadm 工具部署单节点 Kubernetes 集群，其中的 etcd 被设置为 learner 模式。

将节点接入 Kubernetes 集群

在将控制平面节点接入新的 Kubernetes 集群之前，确保现有的控制平面节点和所有 etcd 成员都健康。

使用 etcdctl 检查集群的健康状况。如果 etcdctl 不可用，你可以运行在容器镜像内的这个工具。你可以直接使用 crictl run 这类容器运行时工具而不是通过 Kubernetes 来执行此操作。

以下是一个使用安全通信来检查 etcd 集群健康状况的客户端命令示例：

ETCDCTL_API=3 etcdctl --endpoints 127.0.0.1:2379 \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  member list
...
dc543c4d307fadb9, started, node1, https://10.6.177.40:2380, https://10.6.177.40:2379, false

要检查 Kubernetes 控制平面是否健康，运行 kubectl get node -l node-role.kubernetes.io/control-plane= 并检查节点是否就绪。

说明：

建议在 etcd 集群中的成员个数为奇数。

在将工作节点接入新的 Kubernetes 集群之前，确保控制平面节点健康。

接下来的步骤

特性门控 EtcdLearnerMode 在 v1.27 中为 Alpha，预计会在 Kubernetes 的下一个小版本发布（v1.29）中进阶至 Beta。
etcd 社区有一个开放问题，目的是使这个过程更加自动化：支持自动将 learner 成员晋升为投票成员。
更多细节参阅 kubeadm 配置格式。

反馈

本文对你有帮助吗？如果你有任何反馈或遇到任何问题，请告诉我们。非常欢迎你提出反馈！你可以参加 SIG Cluster Lifecycle 双周例会或 kubeadm 每周讨论会。你还可以通过 Slack（频道 #kubeadm）或 SIG 邮件列表联系我们。

最后修改 March 05, 2026 at 10:44 AM PST: [zh-cn] sync 2023 blog files structure (c852a12c4b)