跳到主要内容

ONES Helm 升级说明

本文介绍如何升级通过 Helm 安装的 ONES 集群。仅适用于集群多副本、外置 MySQL 和 Namespace Scope 部署方式。

升级前，必须确认当前版本到目标版本的升级路径受 ONES 支持。非 Helm 部署的环境不要 使用本文操作。

升级流程​

  1. 生成差量镜像清单并将新镜像导入私有镜像仓。
  2. 检查是否满足升级放行标准。
  3. 准备目标 ONES 版本。
  4. 更新 CRD、RBAC，创建新增 PVC，并准备数据库升级 SQL。
  5. 执行 Helm 升级。
  6. 观察 Bootstrap 和数据库迁移。
  7. 验证升级结果。

第一步：导入目标版本差量镜像​

目标版本分别为 AMD64 和 ARM64 提供升级镜像脚本。脚本会比较当前版本与目标版本的 ONES 主体镜像清单，并根据 migration-history.yaml 计算升级区间所需的迁移镜像。根据 Kubernetes 节点架构，在 AMD64 和 ARM64 中选择一种执行。

本文以 ONES v7.25.0 升级到 v7.26.0 为例。

1.1 生成差量镜像清单​

命令模板：

curl -fL \
  "https://packages.ones.cn/release/<TARGET_ONES_VERSION>/kubernetes/images/upgrade-ones-images-<SYSTEM_ARCHITECTURE>.sh" | \
  SRC_ONES_VERSION="<CURRENT_ONES_VERSION>" \
  bash -

AMD64 示例：

curl -fL \
  "https://packages.ones.cn/release/v7.26.0/kubernetes/images/upgrade-ones-images-amd64.sh" | \
  SRC_ONES_VERSION="v7.25.0" \
  bash -

ARM64 示例：

curl -fL \
  "https://packages.ones.cn/release/v7.26.0/kubernetes/images/upgrade-ones-images-arm64.sh" | \
  SRC_ONES_VERSION="v7.25.0" \
  bash -

脚本会打印差量镜像，并在当前目录生成：

<CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-new-images-<SYSTEM_ARCHITECTURE>.yaml

例如：

v7.25.0-to-v7.26.0-new-images-amd64.yaml

文件头会分别列出应用差量镜像数 APPLICATION_NEW_IMAGE_COUNT、迁移镜像数 MIGRATION_IMAGE_COUNT 和总数 NEW_IMAGE_COUNT。总数为 0 时不需要导入镜像，可以 直接进入第二步。

1.2 导入差量镜像​

Docker 和 image-syncer 两种方式任选其一。 REGISTRY 和 REGISTRY_BASE_PATH 必须与当前环境 ones-secret-config 中的 dockerRegistryHost 和 dockerRegistryBasepathForOnesImage 保持一致。

方法一：使用 Docker 导入​

执行主机需要能够访问 ONES 镜像仓和客户私有镜像仓，并已通过 docker login 登录客户 私有镜像仓。

命令模板：

curl -fL \
  "https://packages.ones.cn/release/<TARGET_ONES_VERSION>/kubernetes/images/upgrade-ones-images-<SYSTEM_ARCHITECTURE>.sh" | \
  SRC_ONES_VERSION="<CURRENT_ONES_VERSION>" \
  MODE="docker" \
  REGISTRY="<REGISTRY>" \
  REGISTRY_BASE_PATH="<REGISTRY_BASE_PATH>" \
  bash -

以目标仓库 registry.example.com/ones/ 为例，根据节点架构选择一种执行。

AMD64：

curl -fL \
  "https://packages.ones.cn/release/v7.26.0/kubernetes/images/upgrade-ones-images-amd64.sh" | \
  SRC_ONES_VERSION="v7.25.0" \
  MODE="docker" \
  REGISTRY="registry.example.com" \
  REGISTRY_BASE_PATH="/ones/" \
  bash -

ARM64：

curl -fL \
  "https://packages.ones.cn/release/v7.26.0/kubernetes/images/upgrade-ones-images-arm64.sh" | \
  SRC_ONES_VERSION="v7.25.0" \
  MODE="docker" \
  REGISTRY="registry.example.com" \
  REGISTRY_BASE_PATH="/ones/" \
  bash -

方法二：使用 image-syncer 导入​

在线同步​

脚本会自动下载 image-syncer 所需工具，并将差量镜像同步到客户私有镜像仓。

命令模板：

curl -fL \
  "https://packages.ones.cn/release/<TARGET_ONES_VERSION>/kubernetes/images/upgrade-ones-images-<SYSTEM_ARCHITECTURE>.sh" | \
  SRC_ONES_VERSION="<CURRENT_ONES_VERSION>" \
  MODE="image-syncer" \
  REGISTRY="<REGISTRY>" \
  REGISTRY_BASE_PATH="<REGISTRY_BASE_PATH>" \
  REGISTRY_USER="<REGISTRY_USER>" \
  REGISTRY_PASSWORD="<REGISTRY_PASSWORD>" \
  bash -

以目标仓库 registry.example.com/ones/ 为例，根据节点架构选择一种执行。

AMD64：

curl -fL \
  "https://packages.ones.cn/release/v7.26.0/kubernetes/images/upgrade-ones-images-amd64.sh" | \
  SRC_ONES_VERSION="v7.25.0" \
  MODE="image-syncer" \
  REGISTRY="registry.example.com" \
  REGISTRY_BASE_PATH="/ones/" \
  REGISTRY_USER="<私有镜像仓用户名>" \
  REGISTRY_PASSWORD="<私有镜像仓密码或 Token>" \
  bash -

ARM64：

curl -fL \
  "https://packages.ones.cn/release/v7.26.0/kubernetes/images/upgrade-ones-images-arm64.sh" | \
  SRC_ONES_VERSION="v7.25.0" \
  MODE="image-syncer" \
  REGISTRY="registry.example.com" \
  REGISTRY_BASE_PATH="/ones/" \
  REGISTRY_USER="<私有镜像仓用户名>" \
  REGISTRY_PASSWORD="<私有镜像仓密码或 Token>" \
  bash -

目标镜像仓不需要认证时，可以省略 REGISTRY_USER 和 REGISTRY_PASSWORD。目标镜像仓启用 TLS 时增加 REGISTRY_INSECURE=false。

制作差量离线包后导入​

目标环境无法同时访问 ONES 镜像仓和客户私有镜像仓时，可以先在联网主机制作差量离线包， 再将离线包复制到目标环境导入。

在联网主机制作离线包。

命令模板：

curl -fL \
  "https://packages.ones.cn/release/<TARGET_ONES_VERSION>/kubernetes/images/upgrade-ones-images-<SYSTEM_ARCHITECTURE>.sh" | \
  SRC_ONES_VERSION="<CURRENT_ONES_VERSION>" \
  MODE="offline-package" \
  bash -

以从 ONES v7.25.0 升级到 v7.26.0、AMD64 架构为例：

curl -fL \
  "https://packages.ones.cn/release/v7.26.0/kubernetes/images/upgrade-ones-images-amd64.sh" | \
  SRC_ONES_VERSION="v7.25.0" \
  MODE="offline-package" \
  bash -

脚本会在当前目录生成：

<CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-new-images-linux-<SYSTEM_ARCHITECTURE>.tar

将离线包复制到目标环境，解压并进入目录。

命令模板：

tar -xf <CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-new-images-linux-<SYSTEM_ARCHITECTURE>.tar
cd <CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-new-images-linux-<SYSTEM_ARCHITECTURE>

AMD64 示例：

tar -xf v7.25.0-to-v7.26.0-new-images-linux-amd64.tar
cd v7.25.0-to-v7.26.0-new-images-linux-amd64

运行包内的导入脚本。

命令模板：

REGISTRY="<REGISTRY>" \
REGISTRY_BASE_PATH="<REGISTRY_BASE_PATH>" \
REGISTRY_USER="<REGISTRY_USER>" \
REGISTRY_PASSWORD="<REGISTRY_PASSWORD>" \
bash import-images.sh

以目标仓库 registry.example.com/ones/ 为例：

REGISTRY="registry.example.com" \
REGISTRY_BASE_PATH="/ones/" \
REGISTRY_USER="<私有镜像仓用户名>" \
REGISTRY_PASSWORD="<私有镜像仓密码或 Token>" \
bash import-images.sh

离线包内已经包含目标架构的 image-syncer 及其依赖工具。目标镜像仓不需要认证时，可以省略 REGISTRY_USER 和 REGISTRY_PASSWORD；目标镜像仓启用 TLS 时增加 REGISTRY_INSECURE=false。

第二步：检查是否满足升级放行标准​

满足以下条件后，方可进入 Helm 升级操作：

  1. 当前环境服务状态正常，不存在持续异常的 Pod。
  2. 磁盘空间、磁盘 I/O、CPU 和内存满足升级要求。
  3. 生产环境的备份资源与业务数据盘相互隔离。
  4. 外置 MySQL 已完成一次全量备份，或已取得客户对外置数据库备份的确认。
  5. 附件、Wiki、插件和审计日志等数据的备份责任已经确认。
  6. Kubernetes 集群状态正常，证书以及 Pod、Node、Namespace 容量不存在升级阻断风险。
  7. private.yaml 不存在重复配置项。
  8. 外置组件的版本兼容性和连通性已经确认。
  9. 升级窗口、回退方案、客户确认人和 ONES 支持接口人已经明确。

如果任一条件不满足，应先完成整改，或通过升级评审确认风险后再继续。

记录当前 Helm Release 和 ONES 版本。

命令模板：

helm -n <NAMESPACE> status <RELEASE_NAME>
helm -n <NAMESPACE> get values <RELEASE_NAME> -o yaml > ones-helm-values-backup.yaml
kubectl -n <NAMESPACE> get configmap ones-current-version -o yaml

以 Namespace ones、Release ones 为例：

helm -n ones status ones
helm -n ones get values ones -o yaml > ones-helm-values-backup.yaml
kubectl -n ones get configmap ones-current-version -o yaml

不要将包含密码或 Token 的文件提交到 Git 仓库或发送到不受控的日志系统。

ResourceQuota 场景​

启用了 Namespace ResourceQuota 时，升级过程中滚动更新和运维任务会临时增加 Pod 和资源 上限。升级前检查剩余配额。

命令模板：

kubectl -n <NAMESPACE> describe resourcequota

以 Namespace ones 为例：

kubectl -n ones describe resourcequota

当 ResourceQuota 要求每个容器必须配置 CPU、内存的 request 和 limit 时，确认 private.yaml 包含数据库迁移主容器和 initContainer 的资源配置：

migrationContainerCPURequest: "0"
migrationContainerCPULimit: "4000m"
migrationContainerMemoryRequest: "0"
migrationContainerMemoryLimit: "10Gi"
migrationInitContainerCPURequest: "0"
migrationInitContainerCPULimit: "500m"
migrationInitContainerMemoryRequest: "0"
migrationInitContainerMemoryLimit: "128Mi"

如果缺少这些配置，Migration Job 会因不满足 ResourceQuota 要求而无法创建 Pod。此时 Job 事件会显示 FailedCreate，并提示迁移主容器或 initContainer 缺少 requests、limits。

如果 CPU、内存或 Pod 配额接近上限，应先提高 ResourceQuota。ResourceQuota 部署方式的 目标 ONES 版本必须高于 v7.26.0。

第三步：准备目标 ONES 版本​

本文的命令示例使用以下版本：

  • 当前版本：v7.25.0
  • 目标版本：v7.26.0

更新 Helm 仓库并确认目标版本存在：

helm repo update
helm search repo ones/ones-cluster --versions

确认列表中存在目标 ONES 版本，并确认本地 private.yaml 是当前环境使用的客户 配置。升级时继续使用该文件，不要导出和复用旧 Chart 的完整默认 values。

第四步：更新 CRD、RBAC、PVC 和数据库​

4.1 更新 CRD​

命令模板：

kubectl apply --server-side \
  -f "https://packages.ones.cn/release/kubernetes-mainfest/<TARGET_ONES_VERSION>/ones/common/ones-cluster-crd.yaml"

以升级到 ONES v7.26.0 为例：

kubectl apply --server-side \
  -f "https://packages.ones.cn/release/kubernetes-mainfest/v7.26.0/ones/common/ones-cluster-crd.yaml"

4.2 更新 Namespace Scope RBAC​

命令模板：

kubectl -n <NAMESPACE> apply \
  -f "https://packages.ones.cn/release/kubernetes-mainfest/<TARGET_ONES_VERSION>/ones/common/ones-cluster-rbac-mini.yaml"

以升级到 ONES v7.26.0、Namespace ones 为例：

kubectl -n ones apply \
  -f "https://packages.ones.cn/release/kubernetes-mainfest/v7.26.0/ones/common/ones-cluster-rbac-mini.yaml"

4.3 生成新增 PVC 清单​

执行目标版本提供的脚本。脚本会比较当前版本和目标版本的 PVC 清单，只输出目标版本新增的 PVC：

命令模板：

curl -sfL \
  "https://packages.ones.cn/release/<TARGET_ONES_VERSION>/kubernetes/generate-new-pvcs.sh" | \
  SRC_ONES_VERSION="<CURRENT_ONES_VERSION>" \
  bash -

以从 ONES v7.25.0 升级到 v7.26.0 为例：

curl -sfL \
  "https://packages.ones.cn/release/v7.26.0/kubernetes/generate-new-pvcs.sh" | \
  SRC_ONES_VERSION="v7.25.0" \
  bash -

脚本会在当前目录生成 <CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-new-pvcs.yaml。文件头会列出源版本、目标 版本和新增 PVC 名称：

命令模板：

cat <CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-new-pvcs.yaml

以从 ONES v7.25.0 升级到 v7.26.0 为例：

cat v7.25.0-to-v7.26.0-new-pvcs.yaml

当 NEW_PVC_COUNT 大于 0 时，将生成文件中的 StorageClass 占位符替换为 private.yaml 中对应配置项的值：

PVC 清单占位符private.yaml 配置项
__storageClassNameForReadWriteMany__storageClassNameForReadWriteMany
__storageClassNameForReadWriteManyWithRetain__storageClassNameForReadWriteManyWithRetain
__storageClassNameForReadWriteOnce__storageClassNameForReadWriteOnce
__storageClassNameForReadWriteOnceWithRetain__storageClassNameForReadWriteOnceWithRetain

确认占位符已全部替换，再创建新增 PVC。

命令模板：

grep -n '__storageClassName' \
  <CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-new-pvcs.yaml
kubectl apply -f \
  <CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-new-pvcs.yaml
kubectl -n <NAMESPACE> get pvc

以从 ONES v7.25.0 升级到 v7.26.0、Namespace ones 为例：

grep -n '__storageClassName' \
  v7.25.0-to-v7.26.0-new-pvcs.yaml
kubectl apply -f \
  v7.25.0-to-v7.26.0-new-pvcs.yaml
kubectl -n ones get pvc

grep 无输出表示占位符已全部替换。NEW_PVC_COUNT 为 0 时，不需要执行 kubectl apply。该脚本不会修改或删除已有 PVC。

4.4 生成数据库升级包​

执行目标版本提供的脚本。

命令模板：

curl -sfL \
  "https://packages.ones.cn/release/<TARGET_ONES_VERSION>/database/generate-database-upgrade.sh" | \
  SRC_ONES_VERSION="<CURRENT_ONES_VERSION>" \
  bash -

以从 ONES v7.25.0 升级到 v7.26.0 为例：

curl -sfL \
  "https://packages.ones.cn/release/v7.26.0/database/generate-database-upgrade.sh" | \
  SRC_ONES_VERSION="v7.25.0" \
  bash -

脚本会在当前目录生成 <CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-database-upgrade.tar.gz。

脚本比较当前版本和目标版本的数据库制品，生成的压缩包包含：

  • sql/account/create-users.sql：新增或发生变化的数据库账号语句。
  • sql/databases/<database>/：新增数据库的建库和完整初始化 SQL。
  • sql/grant/grant-users.sql：新增或发生变化的授权语句。
  • metadata.yaml：SQL 文件清单和执行顺序。
  • database-upgrade.md：英文数据库升级操作说明。

差异 SQL 的范围为：

  • 新增或发生变化的数据库账号语句。
  • 新增或发生变化的授权语句。
  • 新增数据库及其完整初始化 SQL。

已有数据库不会重复输出，即使其初始化 SQL 在目标版本中发生变化。已有数据库的表结构变化由 ONES 数据库迁移处理。

解压后按照说明完成 SQL 审核、密码占位符替换和数据库操作。

命令模板：

tar -xzf \
  <CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-database-upgrade.tar.gz
cd <CURRENT_ONES_VERSION>-to-<TARGET_ONES_VERSION>-database-upgrade
cat database-upgrade.md

以从 ONES v7.25.0 升级到 v7.26.0 为例：

tar -xzf \
  v7.25.0-to-v7.26.0-database-upgrade.tar.gz
cd v7.25.0-to-v7.26.0-database-upgrade
cat database-upgrade.md

database-upgrade.md 会在 Review the SQL files 中列出需要数据库管理员审核的全部 SQL， 并提供密码替换说明和 SQL 执行顺序。账号、授权和新增数据库三类差异数量均为 0 时，不需要 执行数据库升级 SQL。

第五步：执行 Helm 升级​

命令模板：

helm upgrade <RELEASE_NAME> ones/ones-cluster \
  --version "<TARGET_ONES_VERSION>" \
  --namespace <NAMESPACE> \
  -f private.yaml \
  --atomic \
  --timeout 30m

以升级到 ONES v7.26.0、Namespace ones、Release ones 为例：

helm upgrade ones ones/ones-cluster \
  --version "v7.26.0" \
  --namespace ones \
  -f private.yaml \
  --atomic \
  --timeout 30m

不要添加 --reuse-values。Chart 的新版本可能增加或调整默认值；升级命令只需继续传入客户 维护的稀疏 private.yaml，新 Chart 默认值会自动生效。

Helm 命令完成只表示 Chart 资源已更新，不表示 ONES 业务升级已经完成。后续 Bootstrap、 数据库迁移和应用更新由 installer-operator 继续执行。

第六步：观察 Bootstrap 和数据库迁移​

持续观察升级进度。

命令模板：

kubectl -n <NAMESPACE> logs -f deployment/installer-operator

以 Namespace ones 为例：

kubectl -n ones logs -f deployment/installer-operator

installer-operator 会识别当前版本和目标版本，并自动执行目标版本需要的数据库迁移。 迁移完成后继续更新 ONES 工作负载，并记录当前版本。

如果升级失败，会生成 installer-operator-error Pod。查看已完成步骤和有效错误。

命令模板：

kubectl -n <NAMESPACE> logs installer-operator-error

以 Namespace ones 为例：

kubectl -n ones logs installer-operator-error

修复外部依赖、配额或配置问题后，installer-operator 会自动重试。不要在错误原因未确认时 反复执行 helm upgrade。

可以通过以下命令查看版本和迁移记录。

命令模板：

kubectl -n <NAMESPACE> get configmap ones-current-version -o yaml
kubectl -n <NAMESPACE> get configmap ones-latest-successful-migration -o yaml
kubectl -n <NAMESPACE> get migrations.ones.ai

以 Namespace ones 为例：

kubectl -n ones get configmap ones-current-version -o yaml
kubectl -n ones get configmap ones-latest-successful-migration -o yaml
kubectl -n ones get migrations.ones.ai

第七步：验证升级结果​

命令模板：

helm -n <NAMESPACE> status <RELEASE_NAME>
kubectl -n <NAMESPACE> get pods
kubectl -n <NAMESPACE> get configmap ones-current-version \
  -o jsonpath='{.data.onesVersion}{"\n"}'

以 Namespace ones、Release ones 为例：

helm -n ones status ones
kubectl -n ones get pods
kubectl -n ones get configmap ones-current-version \
  -o jsonpath='{.data.onesVersion}{"\n"}'

确认以下结果：

  • ones-current-version 已更新为目标 ONES 版本。
  • installer-operator 日志显示 Bootstrap 全部步骤完成。
  • ONES 工作负载 Pod 均已就绪，不存在持续的 Pending、CrashLoopBackOff 或 ImagePullBackOff。
  • 登录 ONES 后，核心业务和外置 MySQL 访问正常。

升级完成后，再按照ONES 升级后调整完成目标版本要求的检查。

升级失败和版本回退​

helm rollback 只能回退 Helm 管理的资源，不能撤销已经执行的数据库迁移。不要使用 helm rollback 作为 ONES 业务版本回退方案。

版本回退时，installer-operator 会检查目标区间是否包含已执行的数据迁移：

  • 存在数据迁移时，自动回退会被拒绝。
  • 不存在数据迁移时，仍需确认目标版本的镜像、配置和外部依赖均可用。

升级失败或需要回退时，请保留 installer-operator-error、迁移 ConfigMap 和相关 Pod 日志， 联系 ONES 技术支持确认处理方案。