升级到 API7 企业版 3.7.x
本指南介绍从旧版本升级到 API7 企业版 3.7.x 的推荐流程。为降低业务中断风险,请在升级前做好充分准备并评估影响。如果有疑问或需要升级指导,请联系 API7。
API7 企业版的版本号区分主版本、次版本和补丁版本。通常建议使用最新版本,其中包含对已知问题的修复,可降低风险。也可以考虑使用最新的长期支持(LTS)版本,目前为 3.7.x。
备注
适合的升级策略取决于部署方式、自定义插件、具体插件的使用情况、技术能力、硬件容量和 SLA 等因素。因此,升级前请与 API7 充分沟通。
概述
API7 企业版的升级分为准备、测试与验证、生产部署三个阶段。
- 在准备阶段,仔细阅读当前版本到 3.7.x 之间的发布说明,评估可能需要迁移或转换数据的破坏性变更。
- 在测试与验证阶段,搭建测试环境并部署 3.7.x,评估新功能及其适用性,并记录和验证已知问题的修复情况。
- 在生产部署阶段,可考虑滚动升级或灰度升级,并准备应急回滚方案以降低风险。
准备工作
从 3.6.X 升级
没有需要提前处理的破坏性变更。
从 3.5.X 升级
- 升级时,服务模板中现有的服务运行时配置会自动移除。
- 已发布服务的配置保持不变。
- 发布流程已简化,发布时无法设置服务运行时配置。升级后请按更新后的指南发布服务。
从 3.4.X 升级
- 升级时,服务模板中现有的服务运行时配置会自动移除。
- 已发布服务的配置保持不变。
- 发布流程已简化,发布时无法设置服务运行时配置。升级后请按更新后的指南发布服务。
- 旧版灰度规则功能已不再受支持。
从 3.3.X 升级
- 升级时,服务模板中现有的服务运行时配置会自动移除。
- 已发布服务的配置保持不变。
- 发布流程已简化,发布时无法设置服务运行时配置。升级后请按更新后的指南发布服务。
- 旧版灰度规则功能已不再受支持。
测试与验证
- 按照入门指南在测试环境中部署 3.7.x,并评估新功能。功能列表见发布说明。
- 提前演练升级流程,避免出现意外情况。
- 如果使用了自定义插件,请对照发布说明审查代码,并在测试环境中使用新版本测试自定义插件。
生产部署
升级预计耗时 80 分钟以上。为便于升级,API7 企业版的架构将控制面节点与数据面节点(网关实例)分开。因此,建议对控制面节点和数据面节点采用不同的升级策略。
为最大限度保障安全,强烈建议控制面节点和数据面节点使用相同版本。 在特定场景下或分阶段升级期间,也建议检查数据面节点的版本和兼容性。
控制面和数据面分离,使数据面节点在升级控制面期间可以继续处理 API 请求,业务无需停机。
升级控制面
注意
必须先升级控制面节点,再升级数据面节点。控制面升级过程旨在避免业务停机,但此期间禁止所有配置变更,包括通过控制台、ADC、Admin API、Ingress Controller 或直接操作数据库进行的变更。
- 备份数据库(10 分钟)。你可以按自己的备份流程备份数据库并生成相应文件,也可以使用以下流程。
# 备份整个数据库(自定义格式)
pg_dump -h <host> -U <username> -d <dbname> -F c -b -v -f /path/to/backup.dump
# 备份为 SQL 文件
pg_dump -h <host> -U <username> -d <dbname> -F p -f /path/to/backup.sql
# 如果遇到问题,需要恢复之前备份的数据
pg_restore -h <host> -U <username> -d <new_dbname> -v /path/to/backup.dump
psql -h <host> -U <username> -d <new_dbname> -f /path/to/backup.sql
- 备份配置文件(5 分钟)。如果修改过默认配置,请特别注意备份。
* api7-ee/dp_manager_conf/conf.yaml
* api7-ee/dashboard_conf/conf.yaml
* api7-ee/gateway_conf/config.yaml
- 将控制面节点升级到 3.7.x(20 分钟)。
- 部署新的控制台、DP Manager 和相关 Pod。
- 验证新的控制面节点已成功升级。
- 对现有 Pod 执行滚动更新。
更新 Helm Chart 的 values 文件中的镜像名称。
values.yaml
dashboard:
image:
repository: api7/api7-ee-3-integrated
pullPolicy: Always
# 覆盖镜像标签,默认为 Chart 的 appVersion。
tag: "v3.7.3"
运行以下 Helm 命令更新 release。
helm upgrade api7ee3 api7/api7ee3
升级数据面
备注
数据面节点在升级期间可能会生成少量错误日志。这是预期行为,可以忽略。
- 将数据面节点升级到 3.7.x(一个网关组需要 30 分钟)。
- 部署新的网关 Pod。
- 验证新的数据面节点已成功升级。
- 对现有 Pod 执行滚动更新。
- 如果有多个网关组,请对每个网关组重复上述步骤。
- 执行验收测试,确保升级没有问题(20 分钟)。
更新 Helm Chart 的 values.yaml 中的镜像名称。
values.yaml
image:
repository: api7/api7-ee-3-gateway
pullPolicy: Always
tag: 3.7.3
根据之前在控制台生成的安装命令,只修改镜像标签,再执行 Helm 命令更新。例如:
helm upgrade --install -n api7 --create-namespace api7-ee-3-gateway api7/gateway \
--set "etcd.auth.tls.enabled=true" \
--set "etcd.auth.tls.existingSecret=api7-ee-3-gateway-tls" \
--set "etcd.auth.tls.certFilename=tls.crt" \
--set "etcd.auth.tls.certKeyFilename=tls.key" \
--set "etcd.auth.tls.sni=api7ee3-dp-manager" \
--set "etcd.auth.tls.verify=true" \
--set "gateway.tls.existingCASecret=api7-ee-3-gateway-tls" \
--set "gateway.tls.certCAFilename=ca.crt" \
--set "apisix.extraEnvVars[0].name=API7_GATEWAY_GROUP_SHORT_ID" \
--set "apisix.extraEnvVars[0].value=default" \
--set "etcd.host[0]=https://192.168.10.101:7943" \
--set "apisix.replicaCount=1" \
--set "apisix.image.repository=api7/api7-ee-3-gateway" \
--set "apisix.image.tag=3.7.3"
回滚方案
- 如果验证失败或出现其他问题,滚动升级策略可帮助快速回滚到上一版本。
- 也可以从数据库备份恢复数据,再重新部署。
其他资源
- 介绍
- 升级指南