在运维工作中，如何查看 etcd 集群是否正常.

如何查看 etcd 集群是否正常

适用于 Kubernetes 集群中启用了 TLS 双向认证的 etcd 集群。以下示例中所有 IP 和证书路径均为占位符，请替换为实际值。

前置说明

etcd 是 Kubernetes 集群的核心数据存储，所有集群状态（Pod、Service、ConfigMap、Secret 等）都保存在 etcd 中。定期检查 etcd 集群健康状态是集群运维的重要环节。

使用 etcdctl 操作前，需设置环境变量指定 API 版本：

export ETCDCTL_API=3

本文所有命令均基于 v3 API。

---

1. 检查端点健康状态（最常用）

这是最直接的集群健康检查方式，能快速判断 etcd 是否可连接、是否能在合理时间内完成一次提案提交。

单节点检查

etcdctl \
  --endpoints=https://<etcd-node-ip>:2379 \
  --cacert=/path/to/ca.pem \
  --cert=/path/to/etcd.pem \
  --key=/path/to/etcd-key.pem \
  endpoint health

正常输出示例：

https://<etcd-node-ip>:2379 is healthy: successfully committed proposal (took 1.23ms)

集群全量检查（推荐）

将所有 etcd 节点的 endpoint 都加上，一次查看全部节点的健康状态：

etcdctl \
  --endpoints=https://<etcd-node1-ip>:2379,https://<etcd-node2-ip>:2379,https://<etcd-node3-ip>:2379 \
  --cacert=/path/to/ca.pem \
  --cert=/path/to/etcd.pem \
  --key=/path/to/etcd-key.pem \
  endpoint health --write-out=table

正常输出示例：

+---------------------------+--------+----------+-------+
|         ENDPOINT          | HEALTH |   TOOK   | ERROR |
+---------------------------+--------+----------+-------+
| https://<etcd-node1-ip>:2379 |   true  | 1.23ms |       |
| https://<etcd-node2-ip>:2379 |   true  | 1.56ms |       |
| https://<etcd-node3-ip>:2379 |   true  | 1.34ms |       |
+---------------------------+--------+----------+-------+

如果某节点 HEALTH 为 false 或超时无响应，说明该节点存在问题。

---

2. 查看集群成员列表

检查集群中各成员的注册状态，确认节点是否都已正确加入集群：

etcdctl \
  --endpoints=https://<etcd-node-ip>:2379 \
  --cacert=/path/to/ca.pem \
  --cert=/path/to/etcd.pem \
  --key=/path/to/etcd-key.pem \
  member list --write-out=table

输出示例：

+------------------+---------+------+-----------------------+-----------------------+------------+
|        ID        | STATUS  | NAME |      PEER ADDRS       |     CLIENT ADDRS      | IS LEARNER |
+------------------+---------+------+-----------------------+-----------------------+------------+
| 8e9e05c5dxxx...  | started | etcd-1 | https://<etcd-node1-ip>:2380 | https://<etcd-node1-ip>:2379 |      false |
| 91bc8cxxx...     | started | etcd-2 | https://<etcd-node2-ip>:2380 | https://<etcd-node2-ip>:2379 |      false |
| fd4a9fxxx...     | started | etcd-3 | https://<etcd-node3-ip>:2380 | https://<etcd-node3-ip>:2379 |      false |
+------------------+---------+------+-----------------------+-----------------------+------------+

关注点：

• 每个成员的 STATUS 是否都是 started
• IS LEARNER 是否都为 false（Learner 节点不参与投票，仅做数据同步）

---

3. 查看集群状态摘要（信息最全）

该命令展示了每个节点的详细运行状态，是排查集群不一致问题的关键手段：

etcdctl \
  --endpoints=https://<etcd-node-ip>:2379 \
  --cacert=/path/to/ca.pem \
  --cert=/path/to/etcd.pem \
  --key=/path/to/etcd-key.pem \
  endpoint status --write-out=table

输出示例：

+---------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
|         ENDPOINT          |        ID        | VERSION | DB SIZE | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS |
+---------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
| https://<etcd-node1-ip>:2379 | 8e9e05c5dxxx...  |  3.5.4  |  4.3 MB |     true  |      false |         2 |       1234 |               1234 |        |
| https://<etcd-node2-ip>:2379 | 91bc8cxxx...     |  3.5.4  |  4.3 MB |     false |      false |         2 |       1234 |               1234 |        |
| https://<etcd-node3-ip>:2379 | fd4a9fxxx...     |  3.5.4  |  4.3 MB |     false |      false |         2 |       1234 |               1234 |        |
+---------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+

关键字段说明：

字段	含义	健康判断标准
db size	etcd 数据大小	各节点应基本一致；持续异常增长需关注
is leader	是否为 Leader 节点	集群中只有一个 true
raft term	Raft 任期号	各节点必须一致
raft index	Raft 提交日志索引	各节点应接近
raft applied index	已应用的日志索引	各节点应接近，差距过大说明节点滞后

---

4. 检查告警状态

当 etcd 出现磁盘空间不足、后端压力过大等异常时，会触发告警。定期检查可以提前发现隐患：

etcdctl \
  --endpoints=https://<etcd-node-ip>:2379 \
  --cacert=/path/to/ca.pem \
  --cert=/path/to/etcd.pem \
  --key=/path/to/etcd-key.pem \
  alarm list

正常输出： 空（无输出），表示无告警。

常见告警：

告警类型	含义	处理方式
NOSPACE	etcd 数据目录所在磁盘空间不足	清理磁盘空间后执行 etcdctl alarm disarm 解除
CORRUPT	后端数据库损坏	需要从备份恢复该节点

---

快速判断标准

检查项	健康标准
endpoint health	所有节点返回 is healthy
member list	所有成员 STATUS 均为 started
endpoint status	各节点 raft term 一致，raft index 接近，仅一个 is leader
alarm list	无告警输出

四项全部满足即可认定集群健康。日常运维中，方法 1 + 方法 3 组合使用最实用。

---

附：快捷别名

可将常用参数写入 alias 或 shell 函数，简化日常使用：

# ~/.bashrc 或 ~/.zshrc
alias etcdctl-tls='etcdctl \
  --endpoints=https://<etcd-node-ip>:2379 \
  --cacert=/path/to/ca.pem \
  --cert=/path/to/etcd.pem \
  --key=/path/to/etcd-key.pem'

配置后可直接使用：

etcdctl-tls endpoint health --write-out=table
etcdctl-tls endpoint status --write-out=table
etcdctl-tls member list --write-out=table
etcdctl-tls alarm list