将 etcd 从 3.4 升级到 3.5
在一般情况下,从 etcd 3.4 升级到 3.5 可以实现零停机滚动升级:
- 逐一停止 etcd v3.4 进程,并替换为 etcd v3.5 进程
- 在所有 v3.5 进程运行后,集群即可使用 v3.5 的新特性
在 开始升级 之前,请通读本指南其余部分以做好准备。
升级检查列表
从 没有 v3 数据的 v2 迁移
时,如果 etcd 从现有快照恢复,但不存在 v3 ETCD_DATA_DIR/member/snap/db 文件,etcd v3.2+ 服务器会发生崩溃。这种情况出现在服务器由 v2 迁移且此前没有 v3 数据时。此限制也可防止意外丢失 v3 数据(例如 db 文件可能已被移动)。etcd 要求 v3 迁移后的操作必须有 v3 数据。v3.0 服务器包含 v3 数据之前,请勿升级到更新的 v3 版本。
如果集群启用了认证,将无法执行从 3.4 或更早版本的滚动升级,因为 3.5 更改了与认证相关的 WAL 条目格式 。
3.5 版本中的重点变更。
已弃用 etcd_debugging_mvcc_db_total_size_in_bytes Prometheus 指标
v3.5 将 etcd_debugging_mvcc_db_total_size_in_bytes 的 Prometheus 指标提升至 etcd_mvcc_db_total_size_in_bytes,以鼓励对 etcd 存储进行监控。v3.5 完全弃用了 etcd_debugging_mvcc_db_total_size_in_bytes。
请注意,etcd_debugging_* 命名空间指标已被标记为实验性。随着监控指南的完善,我们可能会将更多指标升级为正式支持。
已弃用 etcd_debugging_mvcc_put_total Prometheus 指标
v3.5 将 etcd_debugging_mvcc_put_total 的 Prometheus 指标提升至 etcd_mvcc_put_total,以鼓励对 etcd 存储进行监控。v3.5 完全弃用了 etcd_debugging_mvcc_put_total。
请注意,etcd_debugging_* 命名空间指标已被标记为实验性。随着监控指南的完善,我们可能会将更多指标升级为正式支持。
已弃用 etcd_debugging_mvcc_delete_total Prometheus 指标
v3.5 将 etcd_debugging_mvcc_delete_total 的 Prometheus 指标提升至 etcd_mvcc_delete_total,以鼓励对 etcd 存储进行监控。v3.5 完全弃用了 etcd_debugging_mvcc_delete_total。
请注意,etcd_debugging_* 命名空间指标已被标记为实验性。随着监控指南的完善,我们可能会将更多指标升级为正式支持。
已弃用 etcd_debugging_mvcc_txn_total Prometheus 指标
v3.5 将 etcd_debugging_mvcc_txn_total 的 Prometheus 指标提升至 etcd_mvcc_txn_total,以鼓励对 etcd 存储进行监控。v3.5 完全弃用了 etcd_debugging_mvcc_txn_total。
请注意,etcd_debugging_* 命名空间指标已被标记为实验性。随着监控指南的完善,我们可能会将更多指标升级为正式支持。
已弃用 etcd_debugging_mvcc_range_total Prometheus 指标
v3.5 将 etcd_debugging_mvcc_range_total Prometheus 指标提升至 etcd_mvcc_range_total 级别,以鼓励对 etcd 存储进行监控。v3.5 完全弃用了 etcd_debugging_mvcc_range_total。
请注意,etcd_debugging_* 命名空间指标已被标记为实验性。随着监控指南的完善,我们可能会将更多指标升级为正式支持。
已弃用 etcd --logger capnslog
v3.4 默认使用 --logger=zap,以支持多日志输出和结构化日志。
etcd --logger=capnslog 在 v3.5 中已被弃用,现在 --logger=zap 为默认值。
v3.4 增加 etcd --logger=zap 对结构化日志和多日志输出的支持。主要动机是推动 etcd 的自动化监控,而非在服务出现异常时回溯服务器日志。未来开发将尽量减少 etcd 的日志输出,并通过指标和告警使 etcd 更易于监控。etcd --logger=capnslog 将在 v3.5 中弃用。
已弃用 etcd --log-output
v3.4 将 etcd --log-output 重命名为 --log-outputs
,以支持多日志输出。
etcd --log-output 已在 v3.5 中弃用.
已弃用 etcd --debug 标志(现已 --log-level=debug)
etcd --debug 标志已弃用.
已弃用 etcd --log-package-levels
etcd --log-package-levels 标志在 capnslog 中已弃用.
现在,etcd --logger=zap 为默认值。
已弃用 [CLIENT-URL]/config/local/log
/config/local/log 端点在 v3.5 中正在被弃用,同时 etcd --log-package-levels 标志也将被弃用.
变更 gRPC 网关 HTTP 端点(已弃用 /v3beta)
本文未提供内容。
之后
/v3beta 已在 3.5 版本中移除。
服务器升级检查清单
升级要求
要将现有 etcd 部署升级至 3.5 版本,运行中的集群版本必须为 3.4 或更高。若版本低于 3.4,请先 升级至 3.4 ,再升级至 3.5。
此外,为确保滚动升级顺利进行,运行中的集群必须处于健康状态。在继续操作前,请使用 etcdctl endpoint health 命令检查集群健康状况。
准备
在升级 etcd 之前,请务必在预发环境中测试依赖 etcd 的服务,再将升级部署到生产环境。
在开始之前,下载快照备份
。若升级过程中出现异常,可使用此备份将 etcd 版本 回退
至当前版本。请注意,snapshot命令仅备份 v3 数据。如需备份 v2 数据,请参见备份 v2 数据存储
。
混合版本
升级期间,etcd 集群支持不同版本的 etcd 成员共存,并以最低公共版本的协议运行。只有当集群中所有成员均升级至 3.5 版本后,才认为集群已完成升级。内部机制上,etcd 成员之间会相互协商以确定集群的整体版本,该版本控制报告的版本及支持的功能。
限制
请注意:如果集群仅包含 v3 数据且无 v2 数据,则不受此限制影响。
如果集群正在服务的数据集大小超过 50MB,每个新升级的成员可能需要最多 2 分钟才能追上现有集群。请检查最近快照的大小以估算总数据量。换句话说,升级每个成员之间应至少等待 2 分钟。
对于数据总量更大(例如 100MB 或更多)的情况,此一次性操作可能需要更长时间。对于规模达到此类程度的大型 etcd 集群,系统管理员可在升级前自由联系 etcd 团队 ,我们将乐意提供升级流程方面的建议。
降级
如果所有成员均已升级至 v3.5,则集群将升级至 v3.5,从该完成状态回退不可行。然而,若任一成员仍为 v3.4,则集群及其操作仍保持 “v3.4”,在此混合集群状态下,可将所有成员恢复为使用 v3.4 etcd 二进制文件。
请 下载快照备份 ,以便在集群完成升级后仍可执行降级操作。
升级流程
本示例演示如何升级在本地计算机上运行的 3 个成员的 v3.4 etcd 集群。
步骤 1: 检查升级要求
集群是否健康且运行 v3.4.x 版本?
Step 2: 从领导者下载快照备份
下载快照备份 ,以便在出现任何问题时提供回退路径。
etcd 领导者保证拥有最新的应用数据,因此应从领导者获取快照:
第 3 步:停止一个现有的 etcd 服务器
当每个 etcd 进程停止时,集群中的其他成员会记录预期的错误。这是正常的,因为集群成员之间的连接已(暂时)中断:
第 4 步:使用相同配置重启 etcd 服务器
使用相同配置但采用新 etcd 二进制文件重启 etcd 服务器。
新的 v3.5 etcd 将向集群发布其信息。此时,集群仍以 v3.4 协议运行,该版本为最低公共版本。
{"level":"info","ts":1526586617.1647713,"caller":"membership/cluster.go:485","msg":"set initial cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"7339c4e5e833c029","cluster-version":"3.0"}
{"level":"info","ts":1526586617.1648536,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.0"}
{"level":"info","ts":1526586617.1649303,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"7339c4e5e833c029","from":"3.0","from":"3.4"}
{"level":"info","ts":1526586617.1649797,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.4"}
{"level":"info","ts":1526586617.2107732,"caller":"etcdserver/server.go:1770","msg":"published local member to cluster through raft","local-member-id":"7339c4e5e833c029","local-member-attributes":"{Name:s1 ClientURLs:[http://localhost:2379]}","request-path":"/0/members/7339c4e5e833c029/attributes","cluster-id":"7dee9ba76d59ed53","publish-timeout":7}
验证每个成员以及整个集群在使用新的 v3.5 etcd 二进制文件后是否恢复正常健康状态:
未升级的成员将持续记录如下警告,直至整个集群完成升级。
这是预期行为,当所有 etcd 集群成员都升级到 v3.5 后,该现象将停止。
第 5 步:重复第 3 步和第 4 步,对剩余的成员进行操作
所有成员升级完成后,集群将成功报告升级至 3.5:
成员 1:
{"level":"info","ts":1526586949.0920913,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.5"}{"level":"info","ts":1526586949.0921566,"caller":"etcdserver/server.go:2272","msg":"cluster version is updated","cluster-version":"3.5"}
成员 2:
{"level":"info","ts":1526586949.092117,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"729934363faa4a24","from":"3.4","from":"3.5"}{"level":"info","ts":1526586949.0923078,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.5"}
成员 3:
{"level":"info","ts":1526586949.0921423,"caller":"membership/cluster.go:473","msg":"updated cluster version","cluster-id":"7dee9ba76d59ed53","local-member-id":"b548c2511513015","from":"3.4","from":"3.5"}{"level":"info","ts":1526586949.0922918,"caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.5"}