文档 v2.7.0 版本已不再积极维护，你当前浏览的是一份归档快照。最新文档请参阅最新版本。

模块：ETCD

Pigsty 内置了 etcd 支持，这是一个可靠的分布式配置存储数据库，作为 DCS 为 PostgreSQL 高可用提供支持。

ETCD

ETCD 是一个分布式的、可靠的键-值存储，用于存放系统中最为关键的数据。配置 | 管理 | 剧本 | 监控 | 参数

Pigsty 使用 etcd 作为 DCS：分布式配置存储（或称为分布式共识服务）。这对于 PostgreSQL 的高可用性与自动故障转移至关重要。

在安装任何 PGSQL 模块之前，你必须先安装 ETCD 模块，因为 patroni 和 vip-manager 会依赖 etcd 模块，除非你决定使用外部的现有 etcd 集群。

在安装 ETCD 模块前，你无需安装 NODE 模块，但应当确保本地 CA 是可用的（INFRA.CA）：因为 etcd 需要可信任的 CA 才能签发证书。

配置

在执行实际部署之前，你必须先定义一个 etcd 集群。关于 etcd 的一些参数。

建议在正式的生产环境使用至少三节点，这样可以容忍一个实例失效

单节点

在配置清单中定义一个 etcd 组，它将创建一个单例 etcd 实例。

# 单实例 etcd ‘集群’，供 PostgreSQL 高可用使用
etcd: { hosts: { 10.10.10.10: { etcd_seq: 1 } }, vars: { etcd_cluster: etcd } }

对于开发、测试和演示，一个实例足够了，但在正式的生产环境中最好不要这样做。

三节点

你可以在多个节点上部署 etcd 集群，避免单点失效。

etcd:
  hosts:
    10.10.10.10: { etcd_seq: 1 }  # etcd_seq （etcd实例号）是必须指定的身份参数
    10.10.10.11: { etcd_seq: 2 }  # 实例号是正整数，一般从 0 或 1 开始依次分配
    10.10.10.12: { etcd_seq: 3 }  # 实例号应当终生不可变，一旦分配就不再回收使用。
  vars: # 集群层面的参数
    etcd_cluster: etcd    # 默认情况下，etcd集群名就叫 etcd， 除非您想要部署多套 etcd 集群，否则不要改这个名字
    etcd_safeguard: false # 是否打开 etcd 的防误删安全保险？ 在生产环境初始化完成后，可以考虑打开这个选项，避免误删。
    etcd_clean: true      # 在初始化过程中，是否强制移除现有的 etcd 实例？测试的时候可以打开，这样剧本就是真正幂等的。

五节点或更多实例的配置依此类推，请使用奇数个实例数量，避免出现裁决失效的情况。

管理

以下是一些 etcd 管理的常见任务说明，更多问题请参考 FAQ：ETCD。

创建集群：如何初始化 etcd 集群？
销毁集群：如何销毁 etcd 集群？
环境变量：如何配置 etcd 客户端，以访问 etcd 服务器集群？
重载配置：如何更新客户端使用的 etcd 服务器成员列表？
添加成员：如何向现有 etcd 集群添加新成员？
移除成员：如何从 etcd 集群移除老成员？

创建集群

要创建一个集群，在配置清单中定义好后，执行 etcd.yml 剧本即可。

etcd:
  hosts:
    10.10.10.10: { etcd_seq: 1 }
    10.10.10.11: { etcd_seq: 2 }
    10.10.10.12: { etcd_seq: 3 }
  vars: { etcd_cluster: etcd }

./etcd.yml  # 初始化 etcd 集群

注意，Pigsty 的 etcd 模块提供了防误删保护机制。在默认配置下， etcd_clean 配置打开，且 etcd_safeguard 配置关闭，那么执行此剧本的过程中即使遇到存活的etcd实例，也会强制移除，在这种情况下 etcd.yml 剧本是真正幂等的。这种配置对于开发，测试，以及生产环境紧急强制重建 etcd 集群来说是有用的。

对于生产环境已经初始化好的 etcd 集群，可以打开防误删保护，避免误删现有的 etcd 实例。此时当剧本检测到存活 etcd 实例时会主动中止，避免误删现有 etcd 实例，您可以使用命令行参数来覆盖这一行为。

销毁集群

要销毁一个 etcd 集群，只需使用 etcd.yml 剧本的 etcd_clean 子任务即可。执行此命令前请务必三思！

./etcd.yml -t etcd_clean  # 移除整个集群，会检查现有实例是否存在，根据安全保险判断是否执行
./etcd.yml -t etcd_purge  # 强制移除整个集群，根本不管安全保险是否启用。

使用 etcd_clean 子任务会尊重 etcd_safeguard 防误删保险的配置，使用 etcd_purge 子任务则会无视一切清理现有 etcd 集群。

环境变量

Pigsty 默认使用 etcd v3 API，以下是etcd客户端配置环境变量的示例。

alias e="etcdctl"
alias em="etcdctl member"
export ETCDCTL_API=3
export ETCDCTL_ENDPOINTS=https://10.10.10.10:2379
export ETCDCTL_CACERT=/etc/pki/ca.crt
export ETCDCTL_CERT=/etc/etcd/server.crt
export ETCDCTL_KEY=/etc/etcd/server.key

配置好客户端环境变量后，你可以使用以下命令进行 etcd CRUD 操作：

e put a 10 ; e get a; e del a ; # V3 API

重载配置

如果 etcd 集群的成员发生变化，我们需要刷新对 etcd 服务端点的引用，目前 Pigsty 中有四处 etcd 引用：

现有 etcd 实例成员的配置文件
etcdctl 客户端环境变量（infra节点上）
patroni DCS 端点配置（pgsql节点上）
vip-manager DCS 端点配置（可选）

要在现有etcd成员上刷新 etcd 配置文件 /etc/etcd/etcd.conf：

./etcd.yml -t etcd_conf                           # 使用最新状态刷新 /etc/etcd/etcd.conf
ansible etcd -f 1 -b -a 'systemctl restart etcd'  # 可选操作：重启 etcd

刷新 etcdctl 客户端环境变量：

$ ./etcd.yml -t etcd_env                          # 刷新 /etc/profile.d/etcdctl.sh （管理节点）

在 patroni 上更新 etcd 端点引用：

./pgsql.yml -t pg_conf                            # 重新生成 patroni 配置
ansible all -f 1 -b -a 'systemctl reload patroni' # 重新加载 patroni 配置

在 vip-manager 上更新 etcd 端点引用（如果你正在使用 PGSQL L2 VIP 才需要执行此操作）：

./pgsql.yml -t pg_vip_config                           # 重新生成 vip-manager 配置
ansible all -f 1 -b -a 'systemctl restart vip-manager' # 重启 vip-manager 以使用新配置

添加成员

ETCD 参考: 添加成员

向现有的 etcd 集群添加新成员通常需要五个步骤：

简短版本

执行 etcdctl member add 命令，通知现有集群即将有新成员加入（使用学习者模式）
更新配置清单，将新实例写入配置文件 etcd 组中。
使用 etcd_init=existing 的方式初始化新的 etcd 实例，使其加入现有集群而不是创建一个新集群（非常重要）
将新成员从学习者提升为追随者，正式成为集群中具有投票权的一员。
重载配置以更新客户端使用的 etcd 服务端点。

etcdctl member add <etcd-?> --learner=true --peer-urls=https://<new_ins_ip>:2380  # 通知集群
./etcd.yml -l <new_ins_ip> -e etcd_init=existing                                  # 初始化新实例
etcdctl member promote <new_ins_server_id>                                        # 提升实例为追随者

详细步骤：向etcd集群添加成员

下面是具体操作的详细细节，让我们从一个单实例 etcd 集群开始：

etcd:
  hosts:
    10.10.10.10: { etcd_seq: 1 } # <--- 集群中原本存在的唯一实例
    10.10.10.11: { etcd_seq: 2 } # <--- 将此新成员定义添加到清单中
  vars: { etcd_cluster: etcd }

使用 etcd member add 向现有 etcd 集群宣告新的学习者实例 etcd-2 即将到来：

$ etcdctl member add etcd-2 --learner=true --peer-urls=https://10.10.10.11:2380
Member 33631ba6ced84cf8 added to cluster 6646fbcf5debc68f

ETCD_NAME="etcd-2"
ETCD_INITIAL_CLUSTER="etcd-2=https://10.10.10.11:2380,etcd-1=https://10.10.10.10:2380"
ETCD_INITIAL_ADVERTISE_PEER_URLS="https://10.10.10.11:2380"
ETCD_INITIAL_CLUSTER_STATE="existing"

使用 etcdctl member list（或 em list）检查成员列表，我们可以看到一个 unstarted 新成员：

33631ba6ced84cf8, unstarted, , https://10.10.10.11:2380, , true       # 这里有一个未启动的新成员
429ee12c7fbab5c1, started, etcd-1, https://10.10.10.10:2380, https://10.10.10.10:2379, false

接下来使用 etcd.yml 剧本初始化新的 etcd 实例 etcd-2，完成后，我们可以看到新成员已经启动：

$ ./etcd.yml -l 10.10.10.11 -e etcd_init=existing    # 一定要添加 existing 参数，命令行或配置文件均可
...
33631ba6ced84cf8, started, etcd-2, https://10.10.10.11:2380, https://10.10.10.11:2379, true
429ee12c7fbab5c1, started, etcd-1, https://10.10.10.10:2380, https://10.10.10.10:2379, false

新成员初始化完成并稳定运行后，可以将新成员从学习者提升为追随者：

$ etcdctl member promote 33631ba6ced84cf8   # 将学习者提升为追随者，这里需要使用 etcd 实例的 ID
Member 33631ba6ced84cf8 promoted in cluster 6646fbcf5debc68f

$ em list                # check again, the new member is started
33631ba6ced84cf8, started, etcd-2, https://10.10.10.11:2380, https://10.10.10.11:2379, false
429ee12c7fbab5c1, started, etcd-1, https://10.10.10.10:2380, https://10.10.10.10:2379, fals

新成员添加完成，请不要忘记重载配置，让所有客户端也知道新成员的存在。

重复以上步骤，可以添加更多成员。记住，生产环境中至少要使用 3 个成员。

移除成员

要从 etcd 集群中删除一个成员实例，通常需要以下三个步骤：

从配置清单中注释/屏蔽/删除该实例，并重载配置，让客户端不再使用该实例。
使用 etcdctl member remove <server_id> 命令将它从集群中踢除
将该实例临时添加回配置清单，使用剧本彻底移除下线该实例，然后永久从配置中删除

详细步骤：从etcd集群移除成员

让我们以一个 3 节点的 etcd 集群为例，从中移除 3 号实例。

为了刷新配置，您需要注释要待删除的成员，然后重载配置，让所有客户端都不要再使用此实例。

etcd:
  hosts:
    10.10.10.10: { etcd_seq: 1 }
    10.10.10.11: { etcd_seq: 2 }
    10.10.10.12: { etcd_seq: 3 }   # <---- 首先注释掉这个成员，然后重载配置
  vars: { etcd_cluster: etcd }

然后，您需要使用 etcdctl member remove 命令，将它从集群中踢出去：

$ etcdctl member list
429ee12c7fbab5c1, started, etcd-1, https://10.10.10.10:2380, https://10.10.10.10:2379, false
33631ba6ced84cf8, started, etcd-2, https://10.10.10.11:2380, https://10.10.10.11:2379, false
93fcf23b220473fb, started, etcd-3, https://10.10.10.12:2380, https://10.10.10.12:2379, false  # <--- remove this

$ etcdctl member remove 93fcf23b220473fb  # kick it from cluster
Member 93fcf23b220473fb removed from cluster 6646fbcf5debc68f

最后，您要将该成员临时添加回配置清单中以便运行下线任务，将实例彻底关停移除。

./etcd.yml -t etcd_purge -l 10.10.10.12   # 下线该实例（注意：执行这个命令要求这个实例的定义还在配置清单里）

执行完毕后，您可以将其从配置清单中永久删除，移除成员至此完成。

重复以上步骤，可以移除更多成员，与添加成员配合使用，可以对 etcd 集群进行滚动升级搬迁。

剧本

ETCD 模块提供了一个内置的 playbook： etcd.yml，用于安装 etcd 集群。但首先你需要定义它。

`etcd.yml`

在 etcd.yml 中，提供了以下是可用的任务子集：

etcd_assert ：生成 etcd 身份
etcd_install ：安装 etcd rpm 包
etcd_clean ：清理现有的 etcd 实例
- etcd_check ：检查 etcd 实例是否在运行
- etcd_purge ：删除正在运行的 etcd 实例和数据
etcd_dir ：创建 etcd 数据和配置目录
etcd_config ：生成 etcd 配置
- etcd_conf ：生成 etcd 主配置
- etcd_cert ：生成 etcd ssl 证书
etcd_launch ：启动 etcd 服务
etcd_register ：将 etcd 注册到 prometheus

监控

ETCD 模块提供了一个监控面板：Etcd Overview。

ETCD Overview Dashboard

ETCD Overview：ETCD 集群概览

这个监控面板提供了 ETCD 状态的关键信息：最值得关注的是 ETCD Aliveness，它显示了 ETCD 集群整体的服务状态。

红色的条带标识着实例不可用的时间段，而底下蓝灰色的条带标识着整个集群处于不可用的时间段。

参数

ETCD 模块有 10 个相关参数：

参数	类型	级别	注释
`etcd_seq`	int	I	etcd 实例标识符，必填
`etcd_cluster`	string	C	etcd 集群名，默认固定为 etcd
`etcd_safeguard`	bool	G/C/A	etcd 防误删保险，阻止清除正在运行的 etcd 实例？
`etcd_clean`	bool	G/C/A	etcd 清除指令：在初始化时清除现有的 etcd 实例？
`etcd_data`	path	C	etcd 数据目录，默认为 /data/etcd
`etcd_port`	port	C	etcd 客户端端口，默认为 2379
`etcd_peer_port`	port	C	etcd 同伴端口，默认为 2380
`etcd_init`	enum	C	etcd 初始集群状态，新建或已存在
`etcd_election_timeout`	int	C	etcd 选举超时，默认为 1000ms
`etcd_heartbeat_interval`	int	C	etcd 心跳间隔，默认为 100ms

#etcd_seq: 1                      # etcd 实例标识符，必填
#etcd_cluster: etcd               # etcd 集群名，默认固定为 etcd
etcd_safeguard: false             # etcd 防误删保险，阻止清除正在运行的 etcd 实例？
etcd_clean: true                  # etcd 清除指令：在初始化时清除现有的 etcd 实例？
etcd_data: /data/etcd             # etcd 数据目录，默认为 /data/etcd
etcd_port: 2379                   # etcd 客户端端口，默认为 2379
etcd_peer_port: 2380              # etcd 同伴端口，默认为 2380
etcd_init: new                    # etcd 初始集群状态，新建或已存在
etcd_election_timeout: 1000       # etcd 选举超时，默认为 1000ms
etcd_heartbeat_interval: 100      # etcd 心跳间隔，默认为 100ms

指标列表

Pigsty ETCD 模块提供的完整监控指标列表与释义

常见问题

Pigsty ETCD DCS 模块常见问题答疑