升级 Kubernetes 上的 JupyterHub#

本节介绍通过更新 Helm Chart 来升级 JupyterHub 部署的最佳实践。

Z2JH 遵循语义化版本控制，每个版本的格式为 主版本号.次版本号.修订号（MAJOR.MINOR.PATCH）。次版本和修订版本发布应向后兼容，并且不应要求对您的部署进行更改。请查阅更新日志以了解影响您部署的新功能或错误修复，然后按照helm upgrade 命令的步骤操作。

主版本发布可能包含重大更改，并且通常需要修改您的配置。除了本页上的一般说明外，它们还有专门的部署升级指南。

如需额外帮助，请随时在 Zulip 或 Discourse 论坛上与我们联系。

Helm Chart 的主版本升级#

主版本发布指南

在执行主版本升级前，这些步骤是至关重要的。

  1. 务必备份您的数据库！

  2. 查阅相应的升级指南和/或更新日志，了解不兼容的更改和升级说明。

  3. 相应地更新您的配置。

  4. 用户服务器可能需要在升级前停止，或在升级后重启。

  5. 如果您计划对一个关键的主版本安装进行升级，我们建议您先在预发布（staging）集群上测试升级，然后再将其应用于生产环境。

helm upgrade 命令#

根据更新日志修改您的 config.yaml 文件后，您将需要 <helm-release-name> 来运行升级命令。要找到 <helm-release-name>，请运行

helm list --namespace <k8s-namespace>

在对生产系统进行升级之前，请务必在预发布（staging）环境中测试升级！

要运行升级

helm upgrade --cleanup-on-fail <helm-release-name> jupyterhub/jupyterhub --version=<chart-version> --values config.yaml --namespace <k8s-namespace>

例如，要升级到版本 1.1.1，Helm 发布名称为 jhub，位于 k8s 命名空间 jhub 中

helm upgrade --cleanup-on-fail jhub jupyterhub/jupyterhub --version=1.1.1 --values config.yaml --namespace jhub

数据库#

Z2JH 的主版本发布可能包含需要升级数据库模式（schema）的 JupyterHub 主版本。如果您使用默认的数据库提供程序（SQLite），那么在您执行 helm upgrade 时，所需的数据库升级将自动执行。旧数据库的备份会自动创建在 hub 的存储卷（volume）上。

无法自动备份其他数据库提供程序，因此升级不会自动完成。

默认（SQLite）：当您执行升级时，数据库升级将自动执行。

MySQL / PostgreSQL：您将需要执行以下步骤，其中包括手动更新您的数据库。

  1. 对您的数据库进行完整备份，以防出现问题。

  2. 确保 JupyterHub 用于连接数据库的数据库用户具有执行模式迁移的权限，例如添加新表、修改表等。

  3. 在您的 config.yaml 中，添加以下配置

    hub:
  db:
    upgrade: true

  4. 执行 helm upgrade。这应该会执行所需的数据库升级。

  5. 移除在第 3 步中添加的行，并再次执行 helm upgrade，以防止未来的 JupyterHub 升级无意中升级数据库模式。

自定义 Docker 镜像：JupyterHub 版本匹配#

如果您正在使用自定义构建的镜像，请确保其中安装的 JupyterHub 软件包版本与 JupyterHub 的主版本（当前为 2.*）匹配。

例如，如果您在自定义 Docker 镜像中使用 pip 安装 JupyterHub，您应该使用

RUN pip install --no-cache-dir jupyterhub==2.3.1

如果您使用 conda 或 mamba

RUN conda install --channel=conda-forge -y jupyterhub-base=2.3.1

更新配置以使用这个新镜像，这通常通过 singleuser.image 或作为 singleuser.profileList 的一部分来完成。

各 Helm Chart 中安装的 JupyterHub 版本#

每个 Helm Chart 都打包了特定版本的 JupyterHub（以及其他软件）。有关相关软件包版本的信息，请参阅 Helm Chart 仓库。

问题排查#

如果升级在测试系统或不为用户提供服务的系统上失败，您可以尝试使用以下命令删除 helm chart

helm delete <helm-release-name> --namespace <k8s-namespace>

可以使用 helm list --namespace <k8s-namespace> 来查找 <helm-release-name>。