openEuler 24.03 (LTS-SP1) 下安装 K8s 集群 + KubeSphere 遇到 etcd 报错的解决方案

[openEuler 24.03 (LTS-SP1) 下安装 K8s 集群 + KubeSphere 遇到 etcd 报错的解决方案](#openEuler 24.03 (LTS-SP1) 下安装 K8s 集群 + KubeSphere 遇到 etcd 报错的解决方案)

[🔍 问题背景](#🔍 问题背景)

[🧯 报错成因分析](#🧯 报错成因分析)

[✅ 解决方案](#✅ 解决方案)

[🔧 修改 etcd 启动配置](#🔧 修改 etcd 启动配置)

[🚀 重新部署](#🚀 重新部署)

[📌 建议补充操作](#📌 建议补充操作)

[📘 总结](#📘 总结)

openEuler 24.03 (LTS-SP1) 下安装 K8s 集群 + KubeSphere 遇到 etcd 报错的解决方案

🔍 问题背景

在基于 openEuler 24.03 (LTS-SP1) 安装 Kubernetes + KubeSphere 的过程中，如果目标节点存在残留的 etcd 配置或旧数据目录，kubeadm 会默认尝试以 existing 模式连接 etcd，这会导致如下报错：

复制代码

[ERROR ExternalEtcdVersion]: Get "https://<etcd-ip>:2379/version": dial tcp <etcd-ip>:2379: connect: connection refused

或者出现 kubeadm 初始化失败，并提示：

复制代码

error execution phase preflight: [preflight] Some fatal errors occurred:
[ERROR ExternalEtcdVersion]: ...

这是因为 etcd 默认使用了已有集群模式 (ETCD_INITIAL_CLUSTER_STATE=existing)，但实际并没有运行中或连接成功的 etcd 实例。

🧯 报错成因分析

默认配置下，etcd 会尝试以已有集群成员身份启动：

复制代码

ETCD_INITIAL_CLUSTER_STATE=existing

这在节点是首次部署或此前部署已重置的情况下将导致连接失败。etcd 无法完成启动，进而导致整个 kubeadm init 流程失败。

✅ 解决方案

🔧 修改 etcd 启动配置

手动修改 etcd 环境变量配置，指定以"新集群"方式启动：

复制代码

vi /etc/etcd.env

将原有内容：

复制代码

ETCD_INITIAL_CLUSTER_STATE=existing

修改为：

复制代码

ETCD_INITIAL_CLUSTER_STATE=new

保存后退出。

🚀 重新部署

修改完后，重新执行部署流程（如使用 KubeKey 安装）即可正常初始化：

复制代码

kk create cluster -f config-sample.yaml

或直接使用 kubeadm init 命令，确保 etcd 以新集群身份运行，避免连接失败。

📌 建议补充操作

若此前已使用 kubeadm reset，建议清理以下目录与配置：
复制代码
```
rm -rf /etc/kubernetes /var/lib/etcd /etc/cni/net.d
iptables -F
```
检查 etcd 日志：
复制代码
```
journalctl -u etcd -f
```
推荐使用 kubeadm config migrate 将旧版配置升级为新版本规范：
复制代码
```
kubeadm config migrate --old-config kubeadm-config.yaml --new-config kubeadm-new.yaml
```

📘 总结

在 openEuler 24.03 (LTS-SP1) 上部署 K8s 集群 + KubeSphere 时，若 etcd 报 connection refused，很可能是集群状态未正确设置。只需将 ETCD_INITIAL_CLUSTER_STATE 修改为 new，即可解决初始化失败问题。

此操作在自定义安装或重装场景下尤为关键。

如需该文章的 Markdown 或 HTML 格式版本，也可提供。是否需要？