15.版本管理与升级迁移

在生产环境中运行 etcd 集群时，版本管理是一项至关重要的任务。etcd 遵循语义化版本控制（Semantic Versioning），版本号格式为 x.y.z（例如 3.5.0），其中 x 是主版本，y 是次版本，z 是补丁版本。

etcd 项目通常维护两个主要版本分支：当前版本和上一个版本。例如，当 3.5 是当前主流版本时，3.4 仍会接收安全更新和关键修复。一旦新的次版本（如 3.6）发布，最老的版本（如 3.4）可能会进入维护末期或停止支持。这种策略确保了社区可以集中精力维护最相关的版本，同时也为用户提供了升级缓冲期。

理解版本策略有助于我们制定合理的升级计划。通常，补丁版本（z）的升级是平滑的，主要包含 Bug 修复和性能改进，不包含破坏性变更。而次版本（y）的升级则可能引入新功能，需要我们特别关注变更日志（Change Log）和兼容性说明。主版本（x）的升级则意味着重大的架构调整或 API 不兼容，通常需要复杂的迁移过程。

在进行任何版本操作前，我们应始终检查当前集群的健康状态。可以使用 etcdctl endpoint health 命令来确认集群是否处于良好的运行状态，这是执行所有维护操作的前提。

滚动升级流程

滚动升级（Rolling Upgrade）是指在不停止服务的情况下，逐个替换集群中的节点，最终完成整个集群的版本升级。这是在生产环境中最推荐的升级方式，因为它能保证服务的高可用性。

根据 etcd 版本的不同，升级流程主要分为两种模式：旧版本（如 3.4 升级到 3.5）和新版本（如 3.5 升级到 3.6）。新版本引入了更完善的 etcdctl 命令来管理升级过程，使得流程更加自动化和安全。

旧版本升级流程（以 3.4 升级到 3.5 为例）

在旧版本的升级流程中，主要依赖于逐个替换二进制文件并重启服务。集群会自动协商并提升集群版本。

升级前准备：

1. 检查健康：确保集群所有节点健康。
2. 备份数据：使用 etcdctl snapshot save 命令创建快照备份，以防万一。
3. 下载新版本：下载目标版本（如 3.5.x）的二进制文件。

升级步骤：

1. 选择非 Leader 节点：首先升级非 Leader 节点可以减少对集群的影响。可以通过 etcdctl endpoint status 查看当前的 Leader。
2. 停止节点：停止选定节点的 etcd 服务。
3. 替换二进制文件：将旧的 etcd 二进制文件替换为新版本的文件。通常，我们会将新文件放在不同的目录，然后修改 systemd 或启动脚本的路径。
4. 启动节点：使用完全相同的配置启动新版本的 etcd 进程。注意，配置参数不需要改变，etcd 会自动处理兼容性。
5. 验证健康：启动后，使用 etcdctl endpoint health 检查该节点是否成功加入集群并正常工作。
6. 重复操作：对其他非 Leader 节点重复上述步骤。
7. 升级 Leader：最后升级 Leader 节点。为了避免 Leader 切换带来的短暂不可用，可以先使用 etcdctl move-leader <new_leader_id> 将领导权转移到一个已经升级的节点上，然后再升级原 Leader 节点。

当所有节点都升级完成后，集群的版本号会自动提升到 3.5。你可以通过 curl http://localhost:2379/version 或 etcdctl endpoint status 来验证。

新版本升级流程（以 3.5 升级到 3.6 为例）

从 3.5 升级到 3.6 引入了 etcdctl upgrade 命令，这是一个两阶段过程，提供了更强的控制和回滚能力。

升级前准备： 同旧版本流程，确保健康并备份数据。

升级步骤：

1. 验证升级：在执行升级前，先验证目标版本是否兼容。

   etcdctl upgrade validate 3.6
   

2. 启动升级：执行升级命令。这一步会将集群元数据标记为正在升级，并将集群版本提升到 3.6，但此时节点仍在运行 3.5 的二进制文件。

   etcdctl upgrade enable 3.6
   

   执行后，集群会开始以 3.6 的协议运行，但节点本身还是 3.5。此时，新版本的特性可能还无法使用，但兼容性已经切换。

3. 逐个替换节点：接下来的步骤与旧版本流程类似，逐个停止旧节点，替换为 3.6 的二进制文件，然后启动。启动时使用相同的配置。

4. 验证：每替换一个节点，都检查其健康状态和版本信息。当所有节点都替换为 3.6 后，升级完成。

这种两阶段升级的好处在于，它允许你在升级过程中随时回滚。如果在替换节点时发现问题，你可以随时将节点重新启动为旧版本，而不会破坏集群的一致性。

降级操作指南

降级比升级更危险，因为它涉及到数据格式和协议的向后兼容。etcd 提供了有限的降级支持，通常只允许降级到上一个次版本（例如从 3.5 降级到 3.4，或从 3.6 降级到 3.5），并且要求降级前的集群必须是健康的。

从 3.5 降级到 3.4

从 3.5 降级到 3.4 的过程与旧版本的升级类似，是一个逐个替换节点的过程，但没有特殊的降级命令。

降级步骤：

1. 检查健康与备份：确保集群健康，并创建快照备份。
2. 准备旧版本二进制：下载 3.4.x（必须 >= 3.4.32）的二进制文件。
3. 停止节点：停止一个 3.5 的 etcd 节点。
4. 替换并添加参数：替换为 3.4 的二进制文件，并在启动参数中添加 --next-cluster-version-compatible 标志。这个标志告诉新启动的 3.4 节点，它需要适应一个可能比它新的集群版本。

   etcd-3.4/bin --name s1 \
     --data-dir /tmp/etcd/s1 \
     --listen-client-urls http://localhost:2379 \
     --advertise-client-urls http://localhost:2379 \
     --listen-peer-urls http://localhost:2380 \
     --initial-advertise-peer-urls http://localhost:2380 \
     --initial-cluster s1=http://localhost:2380,s2=http://localhost:22380,s3=http://localhost:32380 \
     --initial-cluster-token tkn \
     --initial-cluster-state existing \
     +--next-cluster-version-compatible
   

5. 启动节点：启动 3.4 节点。它会与集群协商，将集群版本降级为 3.4。
6. 重复操作：对其他节点重复此过程。注意，如果 v2 数据集很大（超过 50MB），每个新降级的成员可能需要长达两分钟才能追上现有集群。

从 3.6 降级到 3.5

从 3.6 降级到 3.5 引入了专门的 etcdctl downgrade 命令，类似于新版本的升级流程，也是两阶段的。

降级步骤：

1. 验证降级：检查是否可以降级到目标版本。

   etcdctl downgrade validate 3.5
   

2. 启用降级：执行降级启用命令。这会将集群元数据标记为降级状态，并将集群协议切换到 3.5。同时，etcd 会自动迁移存储模式（schema）到 3.5 版本。

   etcdctl downgrade enable 3.5
   

   执行后，你可以通过 etcdctl endpoint status 看到 STORAGE VERSION 变为 3.5.0，且 DOWNGRADE ENABLED 为 true。

3. 逐个替换节点：停止一个 3.6 节点，替换为 3.5 的二进制文件，然后启动。启动时不需要任何特殊的降级参数，使用常规配置即可。

4. 验证：检查节点健康状态和版本。当所有节点都替换为 3.5 后，降级完成。

回滚机制： 如果在降级过程中（即还有节点是 3.6 时）遇到问题，可以使用 etcdctl downgrade cancel 来取消降级，然后将已降级的节点重新用 3.6 二进制启动。一旦所有节点都降级完成，就无法直接回滚，必须通过升级流程重新升级到 3.6。

数据迁移方案

数据迁移通常发生在跨大版本升级或底层存储引擎变更时。最常见的是从 etcd v2 迁移到 v3。

v2 到 v3 的迁移

etcd v2 和 v3 使用完全不同的存储后端和 API。v3 提供了更强大的键值模型、事务和租约等功能。迁移过程不是简单的版本升级，而是数据和应用逻辑的迁移。

迁移步骤：

1. 应用改造：首先，需要修改依赖 etcd 的应用程序，使其使用 etcd v3 的客户端库和 API。这是最关键的一步。
2. 数据迁移：使用 etcd 提供的迁移工具（如 etcdctl 的相关命令或官方提供的迁移指南）将 v2 的数据导出并导入到 v3 的存储中。这个过程需要仔细规划，以避免数据丢失或服务中断。
3. 集群升级：在应用和数据都准备好后，将 etcd 集群从 v2.x 升级到 v3.0。注意，v3.0 是一个过渡版本，同时支持 v2 和 v3 API。

存储版本迁移

在较新的 etcd 版本（如 3.6 到 3.5 的降级）中，引入了存储版本（Storage Version）的概念。当执行降级操作时，etcdctl downgrade enable 会触发一个自动的存储模式迁移过程。这个过程会将底层 BoltDB 数据库的 schema 调整为目标版本的格式。

这个迁移通常是快速的，但在大规模集群上可能需要一些时间。在迁移完成前，不建议进行其他破坏性操作。可以通过 etcdctl endpoint status 观察 STORAGE VERSION 字段的变化来监控迁移进度。

版本兼容性检查

在执行任何升级或降级操作之前，进行彻底的兼容性检查是避免灾难的关键。

检查清单：

1. 阅读官方文档：仔细阅读源代码仓库中 CHANGELOG 或 upgrades 目录下的文档。这些文档会列出每个版本的破坏性变更（Breaking Changes）、废弃的功能（Deprecations）和新增特性。
2. 检查配置参数：对比新旧版本的启动参数。例如，从 3.6 降级到 3.5 时，许多 --experimental-* 参数在 3.5 中可能不存在或名称不同。如果使用了这些参数，必须在降级前移除或修改。

   # 3.6 中的参数
   -etcd --experimental-compaction-batch-limit=1000
   # 3.5 中对应的参数
   +etcd --compaction-batch-limit=1000
   

3. 检查监控指标：版本变更可能导致 Prometheus 指标名称的改变或移除。例如，etcd_debugging_mvcc_db_compaction_last 在 3.4 中不可用。需要更新监控告警规则。
4. 客户端兼容性：确保客户端使用的库版本与服务器端兼容。虽然 v3 API 设计上是稳定的，但新版本的服务器可能不支持旧版本的某些非标准行为。
5. 测试环境验证：永远不要直接在生产环境执行大版本升级或降级。必须在与生产环境尽可能一致的测试环境中完整演练整个流程，验证应用功能、性能和数据完整性。

升级最佳实践

为了确保 etcd 集群的升级过程平稳可靠，以下是一些经过实践检验的最佳实践：

1. 备份优先：在执行任何升级操作前，务必使用 etcdctl snapshot save 创建完整的数据快照。这是你最后的救命稻草。
2. 按顺序升级：始终遵循“先非 Leader，后 Leader”的原则。如果可能，先升级 Follower 节点，最后升级 Leader。在升级 Leader 前，可以使用 etcdctl move-leader 将领导权平稳转移。
3. 监控与观察：在升级过程中，密切监控集群的健康指标、延迟和错误率。每完成一个节点的升级，都留出足够的时间观察集群的稳定性。
4. 分批进行：对于大型集群，不要一次性升级所有节点。可以分批进行，例如每次升级 1-2 个节点，观察后再继续。
5. 保持配置一致：在替换二进制文件时，确保启动配置参数保持不变（除非文档明确要求修改）。不要在升级的同时修改其他配置。
6. 理解回滚路径：在升级前，就想好如果失败如何回滚。对于支持降级的版本，了解降级流程。对于不支持降级的版本，确保有快照备份可以用于恢复。
7. 关注客户端：升级服务器后，检查客户端应用是否工作正常。虽然 v3 API 是稳定的，但某些客户端库的特定行为可能会与新版本服务器产生交互。

通过遵循这些步骤和最佳实践，你可以最大限度地降低版本管理过程中的风险，确保 etcd 集群的稳定运行。

本章我们详细探讨了 etcd 的版本管理与升级迁移策略，涵盖了从版本策略、滚动升级与降级的具体操作，到数据迁移和兼容性检查的方方面面。掌握这些技能是维护生产级 etcd 集群的必备条件。下一章，我们将进入性能基准测试与调优，学习如何评估和提升 etcd 的运行效率。