--- title: 将 etcd 从 3.5 降级到 3.4 weight: 6650 description: 降级 etcd 3.5 至 3.4 的流程、检查清单与注意事项 categories: [任务] upstream_link: "https://github.com/etcd-io/website/blob/824597935df6e95992ef61c07e3222f4f796ca6c/content/en/docs/v3.7/downgrades/downgrade_3_5.md" aliases: [/etcd/downgrades/downgrade_3_5/] --- 在一般情况下，从 etcd 3.5 降级到 3.4 可以实现零停机、滚动降级： - 逐一停止 etcd 3.5 进程，并替换为 etcd 3.4 进程 - 启动任意 3.4 进程后，集群将不再支持 3.5 中的新特性 开始 [降级](#downgrade-procedure)前，请阅读本指南其余内容并做好准备。 ### 降级检查列表 {#downgrade-checklists} content/enhttps://etcd.io/docs/v3.5/op-guide/authentication/rbac.md > [!WARNING] > 如果集群启用了身份认证，将无法回滚降级至 3.5 版本，因为 3.5 [更改了与身份认证相关的 WAL 条目格式](https://github.com/etcd-io/etcd/pull/11943)。可以参考 [身份认证操作指南](/zh/docs/etcd/op-guide/authentication/rbac/)禁用身份认证，并先删除所有用户。 3.5 版本到 3.4 版本的突出变更： #### 不同标志 {#difference-in-flags} 如果在 3.5 版本的配置中使用了以下任意标志，请在降级至 3.4 版本时确保移除、重命名或更改其默认值。 > [!NOTE] > 本文的差异对比基于版本 3.5.14 和 v.3.4.33。实际差异取决于所用补丁版本，请先与 `diff <(etcd-3.5/bin/etcd -h | grep \\-\\-) <(etcd-3.4/bin/etcd -h | grep \\-\\-)` 核对。 ```diff # flags not available in 3.4 -etcd --socket-reuse-port -etcd --socket-reuse-address -etcd --raft-read-timeout -etcd --raft-write-timeout -etcd --v2-deprecation -etcd --client-cert-file -etcd --client-key-file -etcd --peer-client-cert-file -etcd --peer-client-key-file -etcd --self-signed-cert-validity -etcd --enable-log-rotation --log-rotation-config-json=some.json -etcd --experimental-enable-distributed-tracing --experimental-distributed-tracing-address='localhost:4317' --experimental-distributed-tracing-service-name='etcd' --experimental-distributed-tracing-instance-id='' --experimental-distributed-tracing-sampling-rate='0' -etcd --experimental-compact-hash-check-enabled --experimental-compact-hash-check-time='1m' -etcd --experimental-downgrade-check-time -etcd --experimental-memory-mlock -etcd --experimental-txn-mode-write-with-shared-buffer -etcd --experimental-bootstrap-defrag-threshold-megabytes -etcd --experimental-stop-grpc-service-on-defrag # same flag with different names -etcd --backend-bbolt-freelist-type=map +etcd --experimental-backend-bbolt-freelist-type=array # same flag different defaults -etcd --pre-vote=true +etcd --pre-vote=false -etcd --logger=zap +etcd --logger=capnslog ``` #### `etcd --logger zap` {#etcd---logger-zap} 3.4 默认值为 `--logger=capnslog`，而 3.5 默认值为 `--logger=zap`。 如果要继续使用 `zap`，必须显式指定。 ```diff +etcd --logger=zap --log-outputs=stderr +# to write logs to stderr and a.log file at the same time +etcd --logger=zap --log-outputs=stderr,a.log ``` #### Prometheus 指标差异 {#difference-in-prometheus-metrics} ```diff # metrics not available in 3.4 -etcd_debugging_mvcc_db_compaction_last ``` ### 服务器降级检查清单 {#server-downgrade-checklists} #### 降级要求 {#downgrade-requirements} 为确保平滑的滚动降级，运行中的集群必须处于健康状态。在继续操作前，请使用 `etcdctl endpoint health` 命令检查集群健康状况。 必须降级至的 3.4 版本应大于等于 3.4.32。 #### 准备 {#preparation} 在将 etcd 降级之前，务必在预发环境中测试依赖 etcd 的服务，确认无误后再将降级操作部署到生产环境。 在开始之前，[下载快照备份](/zh/docs/etcd/op-guide/maintenance/#snapshot-backup)。若降级过程中出现异常，可使用此备份执行[回滚](#rollback)至当前 etcd 版本。请注意，`snapshot`命令仅备份 v3 数据。如需备份 v2 数据，请参见[备份 v2 数据存储](https://etcd.io/docs/v2.3/admin_guide#backing-up-the-datastore)。 开始之前，请下载 etcd 3.4 的最新版本，并确保其版本号 ≥ 3.4.32。 #### 混合版本 {#mixed-versions} 在降级过程中，etcd 集群支持不同版本的 etcd 成员共存，并以最低公共版本的协议运行。一旦集群中的任意成员降级至 3.4 版本，即认为集群已完成降级。内部机制上，etcd 成员之间会相互协商以确定集群的整体版本，该版本控制报告的版本以及所支持的功能。 #### 限制 {#limitations} 请注意：如果集群仅包含 v3 数据且无 v2 数据，则不受此限制影响。 如果集群正在服务的数据集大小超过 50MB，每个新降级的成员可能需要长达两分钟才能追上现有集群。请检查最近快照的大小，以估算总数据量。换句话说，为确保安全，应在降级每个成员之间等待两分钟。 对于数据量更大的情况，总数据大小达到 100MB 或更多时，此一次性操作可能需要更长时间。对于规模达到此类程度的大型 etcd 集群，系统管理员可在降级前自由联系 [etcd 团队][etcd-contact]，我们将乐意提供相关操作建议。 #### 回滚 {#rollback} 如果任一成员降级至 3.4 版本，集群版本将降级至 3.4，操作将保持 "3.4" 兼容。如需回滚，请遵循 [升级 etcd 从 3.4 到 3.5](/zh/docs/etcd/upgrades/upgrade_3_5/) 的说明。 请 [下载快照备份](/zh/docs/etcd/op-guide/maintenance/#snapshot-backup)，以便在集群完全降级后仍可进行回滚。 ### 降级操作 {#downgrade-procedure} 本示例演示如何将运行在本地机器上的 3 成员 3.5 版 etcd 集群降级。 #### 步骤 1: 检查降级要求 {#step-1-check-downgrade-requirements} 集群是否健康且运行 3.5.x 版本？ ```bash etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint health < `{"level":"info","ts":"2024-05-13T21:05:43.981445Z","caller":"membership/cluster.go:561","msg":"set initial cluster version","cluster-id":"ef37ad9dc622a7c4","local-member-id":"8211f1d0f64f3269","cluster-version":"3.0"}` > `{"level":"info","ts":"2024-05-13T21:05:43.982188Z","caller":"api/capability.go:77","msg":"enabled capabilities for version","cluster-version":"3.0"}` > `{"level":"info","ts":"2024-05-13T21:05:43.982312Z","caller":"membership/cluster.go:549","msg":"updated cluster version","cluster-id":"ef37ad9dc622a7c4","local-member-id":"8211f1d0f64f3269","from":"3.0","from":"3.5"}` > `{"level":"info","ts":"2024-05-13T21:05:43.982376Z","caller":"api/capability.go:77","msg":"enabled capabilities for version","cluster-version":"3.5"}` > `{"level":"info","ts":"2024-05-13T21:05:44.000672Z","caller":"etcdserver/server.go:2152","msg":"published local member to cluster through raft","local-member-id":"8211f1d0f64f3269","local-member-attributes":"{Name:infra1 ClientURLs:[http://127.0.0.1:2379]}","request-path":"/0/members/8211f1d0f64f3269/attributes","cluster-id":"ef37ad9dc622a7c4","publish-timeout":"7s"}` > `{"level":"info","ts":"2024-05-13T21:05:46.452631Z","caller":"membership/cluster.go:549","msg":"updated cluster version","cluster-id":"ef37ad9dc622a7c4","local-member-id":"8211f1d0f64f3269","from":"3.5","from":"3.4"}` ``` 验证每个成员以及整个集群在使用新的 3.4 etcd 二进制文件后是否恢复正常健康状态： ```bash etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379 <