Bitnami JupyterHub 包

JupyterHub为用户组带来笔记本的强大功能。它为用户提供计算环境和资源访问，无需用户承担安装和维护任务。

JupyterHub 概述

商标声明：本软件列表由Bitnami打包。产品中提及的 respective 商标归各自公司所有，使用这些商标并不意味着任何关联或认可。

快速开始

helm install my-release oci://registry-1.docker.io/bitnamicharts/jupyterhub

希望在生产环境中使用JupyterHub？试试VMware Tanzu Application Catalog，Bitnami目录的商业版。

⚠️ 重要通知：Bitnami目录即将变更

自2025年8月28日起，Bitnami将升级其公共目录，在新的Bitnami Secure Images计划下提供精选的强化、安全聚焦镜像集。作为此次转型的一部分：

• 首次向社区用户提供热门容器镜像的安全优化版本访问权限。
• Bitnami将开始在免费层中弃用对非强化、基于Debian的软件镜像的支持，并将逐步从公共目录中移除非最新标签。因此，社区用户将只能访问数量减少的强化镜像，这些镜像仅以“latest”标签发布，适用于开发目的。
• 从8月28日开始，在两周内，所有现有容器镜像（包括旧版本或特定版本标签，如2.50.0、10.6）将从公共目录（docker.io/bitnami）迁移到“Bitnami Legacy”仓库（docker.io/bitnamilegacy），且不再接收更新。
• 对于生产工作负载和长期支持，建议用户采用Bitnami Secure Images，包括强化容器、更小的攻击面、CVE透明度（通过VEX/KEV）、SBOM以及企业支持。

这些变更旨在通过推广软件供应链完整性和最新部署的最佳实践，提升所有Bitnami用户的安全态势。更多详情，请访问Bitnami Secure Images公告。

介绍

Bitnami的Helm Chart经过精心设计、积极维护，是在Kubernetes集群上部署容器的最快、最简单方式，可直接用于生产工作负载。

本Chart使用Helm包管理器在Kubernetes集群中引导JupyterHub部署。

架构

JupyterHub Chart部署三个基本组件：

• JupyterHub：Chart的核心组件。管理认证，负责创建Jupyter Notebook实例（称为单用户实例）。因此，Hub需要特殊的RBAC权限以访问Kubernetes API来创建和管理部署。
• Proxy：用户的外部端点。管理与Hub和单用户实例的通信。
• Image Puller：为提高单用户实例启动时间，部署一个DaemonSet对象，预拉取运行单用户笔记本所需的所有镜像。

以下图表显示Chart的部署架构：

                                                         |
                                                         |
                                                         |
                                                         |
             ------------------                          |
             |                |                          |
             |  Image Puller  |<------Pull images to------
             |                |         all nodes
             ------------------

    -------------           ---------------
    |           |           |             |
    |   Proxy   |---------->|     Hub     |
    |           |           |             |
    -------------           ---------------

访问Hub并创建单用户实例后，部署架构如下：

                                                         |
                                                         |
                                                         |
                                                         |
              ----------------                           |
             |                |                          |
             |  Image Puller  |<------Pull images to-----
             |                |         all nodes
              ----------------
    -----------             -------------
   |           |           |             |
   |   Proxy   |---------->|     Hub     |
   |           |           |             |
    -----------             -------------
        |                          |
        |                          |
        |                          |
        |     ---------------      |
        |     | Single User |      |
         ---->|  Instance   |<-----
              ---------------

更多信息，请查看官方JupyterHub文档。

前提条件

• Kubernetes 1.23+
• Helm 3.8.0+
• 底层基础设施支持PV供应

安装Chart

使用发布名称my-release安装Chart：

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/jupyterhub

注意：需将占位符REGISTRY_NAME和REPOSITORY_NAME替换为Helm Chart仓库和存储库的引用。例如，Bitnami的情况下，使用REGISTRY_NAME=registry-1.docker.io和REPOSITORY_NAME=bitnamicharts。

这些命令使用默认配置在Kubernetes集群上部署JupyterHub。参数部分列出了安装期间可配置的参数。

提示：使用helm list列出所有发布。

配置和安装详情

资源请求和限制

Bitnami Chart允许为Chart部署内的所有容器设置资源请求和限制，这些配置位于resources值中（参见参数表）。设置请求对于生产工作负载至关重要，应根据具体用例调整。

为简化此过程，Chart包含resourcesPreset值，可根据不同预设自动设置resources部分。查看bitnami/common chart中的这些预设。但在生产工作负载中，不建议使用resourcesPreset，因为它可能无法完全适应具体需求。有关容器资源管理的更多信息，请参阅官方Kubernetes文档。

了解默认配置

本Chart部署三个基本组件：

• JupyterHub：核心组件，管理认证和单用户实例创建，需RBAC权限访问Kubernetes API。
• Proxy：用户外部端点，处理与Hub和单用户实例的通信。
• Image Puller：DaemonSet对象，预拉取单用户笔记本镜像以加快启动速度。

部署架构图同上架构部分。

Prometheus指标

通过将hub和proxy部分下的*.metrics.enabled设置为true，可将Chart与Prometheus集成。这将在容器中暴露JupyterHub原生Prometheus端口，并创建metrics服务。该服务包含必要的注解，可被Prometheus自动抓取。

Prometheus要求

需安装Prometheus或Prometheus Operator才能使集成工作。安装Bitnami Prometheus Helm Chart或Bitnami Kube Prometheus Helm Chart，可在集群中轻松获得可用的Prometheus。

与Prometheus Operator集成

Chart可部署ServiceMonitor对象以与Prometheus Operator集成。为此，将hub和proxy部分下的*.metrics.serviceMonitor.enabled设置为true。确保集群中已安装Prometheus Operator的CustomResourceDefinitions，否则将失败并显示以下错误：

no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"

安装Bitnami Kube Prometheus Helm Chart以获取必要的CRD和Prometheus Operator。

滚动标签与不可变标签

在生产环境中强烈建议使用不可变标签。这确保即使相同标签更新为不同镜像，部署也不会自动更改。

如果主容器有新版本、重大变更或严重漏洞，Bitnami将发布新Chart更新其容器。

配置认证

Chart默认配置Hub的DummyAuthenticator，密码由hub.password参数设置（未设置则自动生成），管理员用户为user。要更改认证机制，修改hub.configuration值中的hub.config.JupyterHub部分。

以下示例设置NativeAuthenticator认证器，并配置名为test的管理员用户：

hub:
  configuration: |
    ...
    hub:
      config:
        JupyterHub:
          admin_access: true
          authenticator_class: nativeauthenticator.NativeAuthenticator
          Authenticator:
            admin_users:
              - test
    ...

部署时，需注册以设置test用户的密码。

有关认证器的更多信息，请查看官方JupyterHub文档。

更新凭据

Bitnami JupyterHub Chart升级时，会重用之前由Chart渲染的密钥或hub.existingSecret指定的密钥。要更新凭据，使用以下方法之一：

• 运行helm upgrade，在认证部分的hub.configuration中指定新密码。
• 运行helm upgrade，在hub.existingSecret中指定新密钥。

配置单用户实例

如了解默认配置部分所述，Hub负责部署单用户实例。这些实例的配置通过hub.configuration Chart参数传递给Hub实例。

为使Chart遵循标准并简化配置文件生成，Chart包含singleuser部分，用于生成hub.configuration值。可通过修改默认值或通过hub.existingSecret提供密钥来覆盖此值，此时singleuser部分的所有设置将被忽略。

hub.configuration值中指定的所有设置由templates/hub/configmap.yaml文件中的jupyter_config.py脚本使用。可通过hub.existingConfigmap值提供自定义ConfigMap来更改此脚本。官方JupyterHub文档提供了更多jupyter_config.py脚本示例。

备份与恢复

要在Kubernetes上备份和恢复Helm Chart部署，需使用Velero（Kubernetes备份/恢复工具）备份源部署的持久卷，并将其附加到新部署。有关使用Velero的说明，请参阅此指南。

使用网络策略限制流量

Bitnami JupyterHub Chart默认启用网络策略，限制Proxy、Hub和单用户实例三个主要组件之间的通信。有意保留两个开放点：

• Proxy实例HTTP端口的入口访问：默认对任何IP开放，因为它是JupyterHub实例的入口点。可通过调整proxy.networkPolicy.extraIngress值更改此行为。
• Hub出口访问：由于Hub需要访问Kubernetes API，默认允许Hub访问任何IP（取决于Kubernetes平台，服务IP范围可能不同，因此无法轻松检测Kubernetes API内部IP）。可通过调整hub.networkPolicy.extraEgress值更改此行为。

使用边车容器和初始化容器

如需在同一Pod中添加额外容器（如额外指标或日志导出器），可使用proxy.sidecars、hub.sidecars或singleuser.sidecars配置参数定义：

sidecars:
- name: your-image-name
  image: your-image
  imagePullPolicy: Always
  ports:
  - name: portname
    containerPort: 1234

如果这些边车容器导出额外端口，可使用service.extraPorts参数（如可用）添加端口定义：

service:
  extraPorts:
  - name: extraPort
    port: 11311
    targetPort: 11311

注意：此Helm Chart已包含Prometheus导出器的边车容器（如适用）。可在部署时添加--enable-metrics=true参数激活。因此，sidecars参数应仅用于额外的边车容器。

类似地，可使用hub.initContainers、proxy.initContainers和singleuser.initContainers参数添加额外初始化容器：

initContainers:
  - name: your-image-name
    image: your-image
    imagePullPolicy: Always
    ports:
      - name: portname
        containerPort: 1234

了解更多关于边车容器和初始化容器的信息。

配置Ingress

本Chart支持Ingress资源。如果集群中安装了Ingress控制器（如nginx-ingress-controller或contour），可使用Ingress控制器提供应用服务。要启用Ingress集成，设置proxy.ingress.enabled为true。

最常见的场景是将一个主机名映射到部署，此时可使用proxy.ingress.hostname属性设置主机名。proxy.ingress.tls参数可用于为此主机添加TLS配置。

也可设置多个主机。为此，可将proxy.ingress.extraHosts参数（如可用）设置为包含主机名的数组。proxy.ingress.extraTLS参数（如可用）可用于为额外主机添加TLS配置。

注意：对于proxy.ingress.extraHosts参数中指定的每个主机，需设置名称、路径以及Ingress控制器应了解的任何注解。并非所有Ingress控制器都支持所有注解，但此注解参考文档列出了许多流行Ingress控制器支持的注解。

添加TLS参数（如可用）将使Chart生成HTTPS URL，应用将在443端口可用。TLS密钥不必由本Chart生成，但如果启用TLS，Ingress记录在TLS密钥存在之前将无法工作。

了解更多关于Ingress控制器。

配置TLS密钥

本Chart便于创建用于Ingress控制器的TLS密钥（尽管非必需）。常见用例包括：

• 基于Chart参数生成证书密钥。
• 启用外部生成的证书。
• 通过外部服务（如cert-manager）管理应用证书。
• 在Chart内创建自签名证书（如支持）。

在前两种情况下，需要证书和密钥，文件应为.pem格式。

证书文件示例：

注意：如果存在证书链，可能有多个证书。

-----BEGIN CERTIFICATE-----
MIID6TCCAtGgAwIBAgIJAIaCwivkeB5EMA0GCSqGSIb3DQEBCwUAMFYxCzAJBgNV
...
jScrvkiBO65F46KioCL9h5tDvomdU1aqpI/CBzhvZn1c0ZTf87tGQR8NK7v7
-----END CERTIFICATE-----

证书密钥示例：

-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAvLYcyu8f3skuRyUgeeNpeDvYBCDcgq+LsWap6zbX5f8oLqp4
...
wrj2wDbCDCFmfqnSJ+dKI3vFLlEz44sAV8jX/kd4Y6ZTQhlLbYc=
-----END RSA PRIVATE KEY-----

• 如果使用Helm基于参数管理证书，将这些值复制到给定*.ingress.secrets条目的certificate和key值中。
• 如果单独管理TLS密钥，需创建名称为INGRESS_HOSTNAME-tls的TLS密钥（其中INGRESS_HOSTNAME替换为*.ingress.hostname参数设置的主机名）。 = 如果集群有cert-manager附加组件用于自动管理和颁发TLS证书，在*.ingress.annotations中添加相应注解。
• 如果使用Helm创建自签名证书，将*.ingress.tls和*.ingress.selfSigned都设置为true。

设置Pod亲和性

本Chart允许使用*.affinity参数设置自定义亲和性。

作为替代，可使用bitnami/common Chart中可用的Pod亲和性、Pod反亲和性和节点亲和性预设配置。为此，设置*.podAffinityPreset、*.podAntiAffinityPreset或*.nodeAffinityPreset参数。