将 etcd 从 3.0 升级到 3.1

在一般情况下，从 etcd 3.0 升级到 3.1 可以实现零停机、滚动升级：

• 逐个停止 etcd v3.0 进程，并将其替换为 etcd v3.1 进程
• 在所有 v3.1 进程运行后，v3.1 中的新功能即可供集群使用

在开始升级之前，请通读本指南其余部分以做好准备。

升级检查清单

注意： 当从 v2 迁移且没有 v3 数据时，如果 etcd 从现有快照恢复但不存在 v3 的 ETCD_DATA_DIR/member/snap/db 文件，etcd 服务器 v3.2+ 将会 panic。这种情况发生在服务器已从 v2 迁移但之前没有 v3 数据时。这也防止了意外的 v3 数据丢失（例如 db 文件可能已被移动）。etcd 要求只有在存在 v3 数据的情况下才能进行后续的 v3 版本迁移。在 v3.0 服务器包含 v3 数据之前，请勿升级到更新的 v3 版本。

监控

以下来自 v3.0.x 的指标已被弃用，取而代之的是 go-grpc-prometheus：

• etcd_grpc_requests_total
• etcd_grpc_requests_failed_total
• etcd_grpc_active_streams
• etcd_grpc_unary_requests_duration_seconds

升级要求

要将现有的 etcd 部署升级到 3.1 版本，运行中的集群版本必须为 3.0 或更高。如果低于 3.0，请先升级到 3.0，然后再升级到 3.1。

此外，为确保平滑的滚动升级，运行中的集群必须处于健康状态。在继续操作前，请使用 etcdctl endpoint health 命令检查集群健康状况。

准备工作

在升级 etcd 之前，务必先在预演环境中测试依赖 etcd 的服务，然后再将升级部署到生产环境。

开始之前，请先备份 etcd 数据。如果升级过程中出现问题，可以使用此备份回滚到现有的 etcd 版本。请注意，snapshot 命令仅备份 v3 数据。对于 v2 数据，请参见 v2 数据存储的备份方法。

混合版本

升级过程中，etcd 集群支持不同版本的 etcd 节点共存，并以最低公共版本的协议运行。只有当所有成员都升级到 3.1 版本后，集群才被视为完成升级。内部机制上，etcd 成员之间会相互协商以确定整体集群版本，该版本控制着报告的版本号和所支持的功能。

限制

注意：如果集群仅有 v3 数据而无 v2 数据，则不受此限制影响。

如果集群提供的 v2 数据集大于 50MB，则每个新升级的成员可能需要最多两分钟才能追上现有集群的进度。可通过检查最近快照的大小来估算总数据量。换句话说， safest 的做法是在每次升级成员之间等待 2 分钟。

对于更大的总数据量（100MB 或以上），这个一次性过程可能需要更长时间。对于如此大规模的大型 etcd 集群的管理员，可以在升级前联系etcd 团队，我们将很乐意提供升级流程建议。

Downgrade

如果所有成员均已升级到 v3.1，集群将升级至 v3.1，且从此完成状态无法再降级。然而，只要有任何一个成员仍处于 v3.0，集群及其操作就仍保持为“v3.0”状态，此时可以从这种混合状态回退到所有成员都使用 v3.0 etcd 二进制文件。

请备份所有 etcd 成员的数据目录，以便即使集群已完成升级后仍能进行降级。

升级流程

本示例演示如何升级本地机器上运行的三成员 v3.0 etcd 集群。

1. 检查升级要求

集群是否健康并运行在 v3.0.x？

$ ETCDCTL_API=3 etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:2379 is healthy: successfully committed proposal: took = 6.600684ms
localhost:22379 is healthy: successfully committed proposal: took = 8.540064ms
localhost:32379 is healthy: successfully committed proposal: took = 8.763432ms

$ curl http://localhost:2379/version
{"etcdserver":"3.0.16","etcdcluster":"3.0.0"}

2. 停止现有的 etcd 进程

每当一个 etcd 进程停止时，集群中的其他成员会记录预期的错误日志。这是正常现象，因为集群成员之间的连接已（临时）中断。

2017-01-17 09:34:18.352662 I | raft: raft.node: 1640829d9eea5cfb elected leader 1640829d9eea5cfb at term 5
2017-01-17 09:34:18.359630 W | etcdserver: failed to reach the peerURL(http://localhost:2380) of member fd32987dcd0511e0 (Get http://localhost:2380/version: dial tcp 127.0.0.1:2380: getsockopt: connection refused)
2017-01-17 09:34:18.359679 W | etcdserver: cannot get the version of member fd32987dcd0511e0 (Get http://localhost:2380/version: dial tcp 127.0.0.1:2380: getsockopt: connection refused)
2017-01-17 09:34:18.548116 W | rafthttp: lost the TCP streaming connection with peer fd32987dcd0511e0 (stream Message writer)
2017-01-17 09:34:19.147816 W | rafthttp: lost the TCP streaming connection with peer fd32987dcd0511e0 (stream MsgApp v2 writer)
2017-01-17 09:34:34.364907 W | etcdserver: failed to reach the peerURL(http://localhost:2380) of member fd32987dcd0511e0 (Get http://localhost:2380/version: dial tcp 127.0.0.1:2380: getsockopt: connection refused)

此时最好备份 etcd 数据，以便在出现问题时提供降级路径：

$ etcdctl snapshot save backup.db

3. 替换为 etcd v3.1 二进制文件并启动新的 etcd 进程

新的 v3.1 etcd 将向集群发布其信息：

2017-01-17 09:36:00.996590 I | etcdserver: published {Name:my-etcd-1 ClientURLs:[http://localhost:2379]} to cluster 46bc3ce73049e678

验证每个成员以及整个集群是否使用新的 v3.1 etcd 二进制文件恢复健康：

$ ETCDCTL_API=3 /etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:22379 is healthy: successfully committed proposal: took = 5.540129ms
localhost:32379 is healthy: successfully committed proposal: took = 7.321671ms
localhost:2379 is healthy: successfully committed proposal: took = 10.629901ms

在集群全部升级完成前，已升级的成员会记录如下警告日志。这是正常现象，当所有 etcd 集群成员都升级到 v3.1 后，警告将消失：

2017-01-17 09:36:38.406268 W | etcdserver: the local etcd version 3.0.16 is not up-to-date
2017-01-17 09:36:38.406295 W | etcdserver: member fd32987dcd0511e0 has a higher version 3.1.0
2017-01-17 09:36:42.407695 W | etcdserver: the local etcd version 3.0.16 is not up-to-date
2017-01-17 09:36:42.407730 W | etcdserver: member fd32987dcd0511e0 has a higher version 3.1.0

4. 对所有其他成员重复步骤 2 到步骤 3

5. 完成

当所有成员都升级完成后，集群将报告成功升级到 3.1：

2017-01-17 09:37:03.100015 I | etcdserver: updating the cluster version from 3.0 to 3.1
2017-01-17 09:37:03.104263 N | etcdserver/membership: updated the cluster version from 3.0 to 3.1
2017-01-17 09:37:03.104374 I | etcdserver/api: enabled capabilities for version 3.1

$ ETCDCTL_API=3 /etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379
localhost:2379 is healthy: successfully committed proposal: took = 2.312897ms
localhost:22379 is healthy: successfully committed proposal: took = 2.553476ms
localhost:32379 is healthy: successfully committed proposal: took = 2.516902ms