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

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

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

本部分重点内容：

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

一、ETCD 集群架构说明

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

节点角色IP 示例
etcd-1member192.168.10.11
etcd-2member192.168.10.12
etcd-3member192.168.10.13

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

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

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

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

证书包括：

  1. CA 证书（ca.pem）
  2. Server 证书（server.pem）
  3. Peer 证书（peer.pem）
  4. 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 链接

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

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

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