etcdctl与etcd Prometheus指标监控

本文主要记录如何在已启用 TLS 的 etcd 集群（以 Kubernetes 控制面 etcd 为例）上配置 etcdctl，以及如何通过 Prometheus 抓取 etcd metrics。Grafana 大盘可在指标稳定后再叠加，本文以采集链路为主。

此前的文章介绍了 TLS 高可用 etcd 的手动部署，这里不再重复搭建过程。下面以 kubeadm 风格的 static pod etcd 为例说明监控相关参数与操作。

背景说明

生产环境中的 etcd 通常具备：

客户端与 peer 均使用 TLS
独立的 metrics 监听地址（默认常见为 127.0.0.1:2381）
需要通过证书才能执行 etcdctl 集群查询

要把监控做起来，需要同时弄清：启动参数含义、etcdctl 与证书的对应关系、metrics 是否对 Prometheus 可达。

环境信息

项目	说明
etcd 版本（示例）	镜像 `registry.k8s.io/etcd:3.5.9-0`；工具可用 3.5.x 系列
部署方式	Kubernetes static pod，清单常见路径 `/etc/kubernetes/manifests/etcd.yaml`
证书目录	`/etc/kubernetes/pki/etcd/`
客户端端口	`2379`
peer 端口	`2380`
metrics 端口	`2381`（以实际 `listen-metrics-urls` 为准）

下文 IP、主机名均使用占位符，请替换为实际节点信息。

etcd 启动参数（与监控相关）

从控制面节点查看 static pod 清单或进程参数，可以还原关键配置。示例结构如下（已脱敏）：

apiVersion: v1
kind: Pod
metadata:
  name: etcd
  namespace: kube-system
spec:
  containers:
  - name: etcd
    image: registry.k8s.io/etcd:3.5.9-0
    command:
    - etcd
    - --name=<etcd-member-name>
    - --data-dir=/var/lib/etcd
    - --advertise-client-urls=https://<node-ip>:2379
    - --listen-client-urls=https://127.0.0.1:2379,https://<node-ip>:2379
    - --initial-advertise-peer-urls=https://<node-ip>:2380
    - --listen-peer-urls=https://<node-ip>:2380
    - --initial-cluster=<member>=https://<node-ip>:2380
    - --cert-file=/etc/kubernetes/pki/etcd/server.crt
    - --key-file=/etc/kubernetes/pki/etcd/server.key
    - --trusted-ca-file=/etc/kubernetes/pki/etcd/ca.crt
    - --client-cert-auth=true
    - --peer-cert-file=/etc/kubernetes/pki/etcd/peer.crt
    - --peer-key-file=/etc/kubernetes/pki/etcd/peer.key
    - --peer-trusted-ca-file=/etc/kubernetes/pki/etcd/ca.crt
    - --peer-client-cert-auth=true
    - --listen-metrics-urls=http://0.0.0.0:2381
    - --snapshot-count=10000

网络与集群

参数	作用
`--advertise-client-urls`	向客户端公布的访问地址
`--listen-client-urls`	实际监听的客户端地址列表
`--initial-advertise-peer-urls` / `--listen-peer-urls`	节点间 peer 通信
`--initial-cluster`	初始成员列表，`名称=peer-url`
`--name`	本节点成员名

安全

参数	作用
`--cert-file` / `--key-file`	服务端证书
`--trusted-ca-file` + `--client-cert-auth`	校验客户端证书
`--peer-*` 一组	peer 通道 TLS 与双向认证

生产环境建议保持 TLS 与客户端证书认证开启。

监控与数据

参数	作用
`--listen-metrics-urls`	Prometheus 抓取地址；默认常为仅本机
`--data-dir`	数据目录
`--snapshot-count`	触发快照的事务数阈值，需按写入量调整

需要注意的是：若 etcd 以 static pod 运行，修改 listen-metrics-urls 时要同步检查 livenessProbe / startupProbe 的 host 与端口是否仍指向可达的 metrics 地址。

安装并配置 etcdctl

从 etcd Releases 下载与集群接近的版本，例如：

wget https://github.com/etcd-io/etcd/releases/download/v3.5.14/etcd-v3.5.14-linux-amd64.tar.gz
tar -zxvf etcd-v3.5.14-linux-amd64.tar.gz
cd etcd-v3.5.14-linux-amd64
./etcdctl version

确认版本无误后安装到 PATH：

cp -a etcdctl /usr/local/bin/
etcdctl version

参数与 etcd 启动项的对应关系

etcdctl	etcd 启动参数（概念对应）
`--endpoints`	客户端 URL（advertise/listen client）
`--cacert`	`--trusted-ca-file`
`--cert`	`--cert-file`（或专用客户端证书）
`--key`	`--key-file`

在 kubeadm 集群上，可从运行中的 etcd 进程确认证书路径：

ps -ef | grep '[e]tcd '

环境变量（减少重复传参）

cat <<'EOF' >> ~/.bashrc

# etcdctl
export ETCDCTL_API=3
export ETCDCTL_ENDPOINTS="https://<node1-ip>:2379,https://<node2-ip>:2379,https://<node3-ip>:2379"
export ETCDCTL_CACERT="/etc/kubernetes/pki/etcd/ca.crt"
export ETCDCTL_CERT="/etc/kubernetes/pki/etcd/server.crt"
export ETCDCTL_KEY="/etc/kubernetes/pki/etcd/server.key"

EOF
source ~/.bashrc

生产环境更稳妥的做法是使用独立的 etcd 客户端证书，而不是长期复用 server 证书；以上仅为排障时的常见写法。

验证集群状态

etcdctl endpoint status -w=table
# 或显式指定
etcdctl --endpoints "$ETCDCTL_ENDPOINTS" \
  --cacert "$ETCDCTL_CACERT" \
  --cert "$ETCDCTL_CERT" \
  --key "$ETCDCTL_KEY" \
  endpoint status -w=table --cluster

若表格中能看到各 endpoint 的 VERSION、DB SIZE、IS LEADER、RAFT TERM/INDEX 且 ERRORS 为空，说明客户端连通与集群成员状态基本正常。

配置 Prometheus 抓取 etcd metrics

etcd 通过 Prometheus 格式暴露指标，指标不落盘，进程重启后会重置。命名空间一般为 etcd_ 或 etcd_debugging_ 前缀。说明见 etcd metrics 文档。

暴露 metrics 端口

编辑 /etc/kubernetes/manifests/etcd.yaml（路径以实际为准）。
将 --listen-metrics-urls 从仅本机改为 Prometheus 可达地址，例如：
- http://0.0.0.0:2381，或
- http://<node-ip>:2381
检查 probe 是否仍访问 127.0.0.1:2381（通常本机 probe 可保持不变）。
等待 kubelet 重建 etcd pod，确认进程参数已更新。

本地快速探活（在节点上）：

curl -sS http://127.0.0.1:2381/metrics | head

若能看到大量 etcd_ 开头的指标行，说明 metrics 端点工作正常。

scrape_configs 示例

scrape_configs:
  - job_name: "k8s_etcd"
    metrics_path: /metrics
    static_configs:
      - targets:
          - <node1-ip>:2381
          - <node2-ip>:2381
          - <node3-ip>:2381

若 metrics 也启用了 TLS，需要额外配置 scheme: https 与证书，本文示例为常见的明文 metrics + 仅内网可达部署。

重载 Prometheus 后，在查询界面验证：

etcd_cluster_version{job="k8s_etcd"}

若能查到各实例的版本标签，说明抓取链路已打通。随后可再导入 Grafana 的 etcd 大盘，关注 leader 变更、DB 大小、fdatasync、慢请求、peer 往返时延等指标。

注意事项

修改 static pod 清单会导致 etcd 短暂重建，控制面敏感操作应在维护窗口进行。
将 metrics 绑定到 0.0.0.0 时，务必用网络策略或主机防火墙限制访问来源。
etcdctl 使用的证书与 endpoints 必须与集群一致，版本尽量与服务端同主版本。
指标在进程重启后清零，告警规则应容忍短暂缺口。

背景说明#

环境信息#

etcd 启动参数（与监控相关）#

网络与集群#

安全#

监控与数据#

安装并配置 etcdctl#

参数与 etcd 启动项的对应关系#

环境变量（减少重复传参）#

验证集群状态#

配置 Prometheus 抓取 etcd metrics#

暴露 metrics 端口#

scrape_configs 示例#

注意事项#

参考资料#