【运维】K8S 集群部署系列之 ETCD 集群搭建（二）

lichongyang

6 月前

下面为你提供一套 全面、工程化、可直接用于生产环境的 K8S ETCD 集群搭建（第二部分）讲解，包括架构、部署方式、证书、systemd 配置、健康检查及常见错误排查，适用于二进制部署方式。

如果你需要，我还可以为你生成对应的 Shell 脚本、Ansible Playbook 或完整部署文档。

【运维】K8S 集群部署系列之 ETCD 集群搭建（二）

本部分重点内容：

ETCD 集群架构与组件说明
证书（CA/Server/Peer）创建
ETCD 三节点集群安装与 systemd 配置
集群初始化与启动
健康检查与数据验证
常见错误排查（高频生产事故）

一、ETCD 集群架构说明

高可用生产环境通常部署 三节点 ETCD 集群（保持奇数节点）：

节点	角色	IP 示例
etcd-1	member	192.168.10.11
etcd-2	member	192.168.10.12
etcd-3	member	192.168.10.13

每个 ETCD 节点有两个监听端口：

端口	用途
2379	客户端访问（如 kube-apiserver）
2380	集群内部 peer 通信

二、准备工作（证书创建）

ETCD 集群必须使用 TLS 证书，否则无法与 K8S apiserver 集成。

证书包括：

CA 证书（ca.pem）
Server 证书（server.pem）
Peer 证书（peer.pem）
Client 证书（客户端使用）

你可以用 cfssl 生成：

2.1 下载 cfssl

wget https://pkg.cfssl.org/R1.2/cfssl_linux-amd64
wget https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64
chmod +x cfssl_linux-amd64 cfssljson_linux-amd64
mv cfssl_linux-amd64 /usr/local/bin/cfssl
mv cfssljson_linux-amd64 /usr/local/bin/cfssljson

2.2 生成 CA 配置

创建 ca-config.json：

{
  "signing": {
    "default": {
      "expiry": "87600h"
    },
    "profiles": {
      "server": {
        "expiry": "87600h",
        "usages": ["signing", "key encipherment", "server auth"]
      },
      "peer": {
        "expiry": "87600h",
        "usages": ["signing", "key encipherment", "server auth", "client auth"]
      }
    }
  }
}

创建 ca-csr.json：

{
  "CN": "kubernetes",
  "key": { "algo": "rsa", "size": 2048 },
  "names": [{ "C": "CN", "L": "Beijing", "O": "Kubernetes", "OU": "CA", "ST": "Beijing" }]
}

生成 CA：

cfssl gencert -initca ca-csr.json | cfssljson -bare ca

2.3 生成 ETCD Server 与 Peer 证书

以 etcd-1 为例：

创建 etcd1-csr.json：

{
  "CN": "etcd",
  "hosts": [
    "127.0.0.1",
    "192.168.10.11",
    "etcd-1"
  ],
  "key": { "algo": "rsa", "size": 2048 }
}

生成证书：

cfssl gencert \
  -ca=ca.pem \
  -ca-key=ca-key.pem \
  -config=ca-config.json \
  -profile=peer \
  etcd1-csr.json | cfssljson -bare etcd1

三个节点分别生成即可。

三、ETCD 集群安装与 systemd 配置

3.1 下载二进制包

wget https://github.com/etcd-io/etcd/releases/download/v3.5.12/etcd-v3.5.12-linux-amd64.tar.gz
tar -xvf etcd-v3.5.12-linux-amd64.tar.gz
mv etcd-v3.5.12-linux-amd64/etcd* /usr/local/bin/

3.2 配置目录

mkdir -p /etc/etcd /var/lib/etcd
cp ca.pem etcd1.pem etcd1-key.pem /etc/etcd/

3.3 创建 systemd 配置（etcd-1）

创建 /usr/lib/systemd/system/etcd.service：

[Unit]
Description=etcd
After=network.target

[Service]
User=root
Type=notify
ExecStart=/usr/local/bin/etcd \
  --name etcd-1 \
  --data-dir=/var/lib/etcd \
  --listen-client-urls=https://192.168.10.11:2379 \
  --advertise-client-urls=https://192.168.10.11:2379 \
  --listen-peer-urls=https://192.168.10.11:2380 \
  --initial-advertise-peer-urls=https://192.168.10.11:2380 \
  --initial-cluster=etcd-1=https://192.168.10.11:2380,etcd-2=https://192.168.10.12:2380,etcd-3=https://192.168.10.13:2380 \
  --initial-cluster-token=etcd-cluster \
  --initial-cluster-state=new \
  --client-cert-auth \
  --trusted-ca-file=/etc/etcd/ca.pem \
  --cert-file=/etc/etcd/etcd1.pem \
  --key-file=/etc/etcd/etcd1-key.pem \
  --peer-cert-file=/etc/etcd/etcd1.pem \
  --peer-key-file=/etc/etcd/etcd1-key.pem \
  --peer-trusted-ca-file=/etc/etcd/ca.pem \
  --peer-client-cert-auth

Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

在 etcd-2 / etcd-3 修改 name、IP、证书名称即可。

四、启动集群

systemctl daemon-reload
systemctl enable etcd
systemctl start etcd
systemctl status etcd

三个节点依次启动。

五、健康检查与集群状态验证

5.1 查看集群成员

ETCDCTL_API=3 etcdctl \
  --endpoints=https://192.168.10.11:2379 \
  --cacert=/etc/etcd/ca.pem \
  --cert=/etc/etcd/etcd1.pem \
  --key=/etc/etcd/etcd1-key.pem \
  member list

5.2 健康检查

ETCDCTL_API=3 etcdctl \
  --endpoints=https://192.168.10.11:2379 \
  --cacert=/etc/etcd/ca.pem \
  --cert=/etc/etcd/etcd1.pem \
  --key=/etc/etcd/etcd1-key.pem \
  endpoint health

六、生产环境常见错误排查

1. 集群无法启动（leader 选举失败）

原因：

时间不同步
证书 CN 与 IP 不匹配
peer URL 写错

解决：

统一使用 chrony/NTP
重新生成 hosts 中正确包含 IP 的证书

2. “certificate is not valid for any names”

说明证书里没有对应 IP 或 hostname。
需要重新生成 peer/server 证书。

3. “connection refused” 或 “EOF”

通常是：

防火墙未开放 2379/2380
服务未启动
证书权限（600）错误

4. 启动后状态正常但 apiserver 无法访问 etcd

解决：

apiserver 使用的 client 证书必须来自 CA
apiserver 指定的 etcd endpoint 必须是 https 链接

如果你需要，我可以进一步为你生成：

三节点自动化安装脚本（bash）
Ansible Playbook 版本
Kubernetes 完整二进制部署系列文档
高可用模式（Keepalived + Nginx）接入方案

随时告诉我你需要哪一种。