高级主题#

此页面包含各种有用的主题,这些主题在其他地方没有合适的归属。

  • Ingress

  • jupyterhub_config.py 中添加任意额外代码和配置

大多数在流行的公共云上设置 JupyterHub 的人应该不需要使用这些信息,但这些主题对于更复杂的安装至关重要。

Ingress#

Helm 图表可以配置为创建一个 Kubernetes Ingress 资源,使用 Ingress 控制器 来公开 JupyterHub。

注意

并非所有 k8s 集群默认都设置了 Ingress 控制器。如果您需要手动安装一个,我们建议使用 ingress-nginx

使用 Ingress 资源公开 JupyterHub 的最小示例如下:

ingress:
  enabled: true

通常,您应该声明只接受对特定域名名的流量,以避免与其他 Ingress 资源发生冲突。

ingress:
  enabled: true
  hosts:
    - hub.example.com

使用 kube-lego 和 Let’s Encrypt 实现 Ingress 和自动 HTTPS#

警告

kube-lego 已被弃用,取而代之的是 cert-manager。请参见 cert-manager

使用 Ingress 对象时,默认的自动 HTTPS 支持不起作用。要自动获取和更新 HTTPS 证书,您必须自行设置。

以下方法使用 kube-legoLet’s Encrypt 自动获取和更新 HTTPS 证书。这种使用 kube-lego 和 Let’s Encrypt 的方法目前仅适用于两个 Ingress 控制器:社区维护的 kubernetes/ingress-nginxgoogle cloud 的 Ingress 控制器

  1. 确保 DNS 设置正确(配置取决于您使用的 Ingress 控制器以及集群的设置方式)。从浏览器访问 <hostname> 应该将流量路由到 hub。

  2. 使用 kube-lego helm-chart 安装和配置 kube-lego。请务必更改 config.LEGO_EMAILconfig.LEGO_URL 至少。

  3. 向 Ingress 添加注释 + TLS 配置,以便 kube-lego 知道要为其获取证书

    ingress:
      annotations:
        kubernetes.io/tls-acme: "true"
      tls:
        - hosts:
            - <hostname>
          secretName: kubelego-tls-jupyterhub
    

这应该会配置证书,并在证书即将过期时不断更新它!

jupyterhub_config.py 中添加任意额外的代码和配置#

有时,通过 helm 图表中的 values.yaml 公开的各种选项不足以满足需求,需要在 jupyterhub_config.py 中插入任意额外的代码/配置。这对于原型化 helm 图表中尚未提供的功能以及不适合上游的安装特定定制来说,是一个宝贵的逃生舱。

可以在 config.yaml 中设置四个属性来实现这一点。

hub.extraConfig#

hub.extraConfig 指定的值在 JupyterHub 加载的 jupyterhub_config.py 文件末尾作为 Python 代码进行评估。由于它是任意的 Python 代码,因此可以在 hub.extraConfig 中执行任何操作,而 hub.config 仅允许指定固定的配置值。

一些可以执行的操作示例

  1. 通过子类化来覆盖 Spawner/Authenticator 中的各种方法。例如,可以使用此方法将用户的身份验证凭据(例如 GitHub OAuth 令牌)传递到环境中。

  2. 指定将可调用对象作为值的 traitlets,允许动态地进行每个用户的配置。

  3. 设置当前 Helm 图表中不支持的 JupyterHub/Spawner/Authenticator 的 traitlets。

应将 hub.extraConfig 指定为字典。代码将按键的字母顺序进行评估。

hub:
  extraConfig:
    00-first-config: |
      import time
      c.KubeSpawner.environment.update(
          {
              "JUPYTERHUB_START_TIME": str(time.time())
          }
      )
    10-second-config: |
      # some other code

有关此配置的更多信息,请参阅 有关 hub.extraConfig 的配置参考条目

custom 配置#

values.yaml 的内容将传递到 Hub 镜像。可以通过 z2jh.get_config 函数访问这些值,以进一步定制 hub pod。图表版本 0.8 添加了一个顶层 custom 字段,用于传递可能使用的其他配置。它可以是任意的 YAML。可以使用此方法将代码(位于 hub.extraConfig 中)与配置(应位于 custom 中)分开。

例如,如果在 config.yaml 文件中使用以下代码段

custom:
  myString: Hello!
  myList:
    - Item1
    - Item2
  myDict:
    key: value
  myLongString: |
    Line1
    Line2

hub.extraConfig 中,

  1. z2jh.get_config('custom.myString') 将返回一个字符串 "Hello!"

  2. z2jh.get_config('custom.myList') 将返回一个列表 ["Item1", "Item2"]

  3. z2jh.get_config('custom.myDict') 将返回一个字典 {"key": "value"}

  4. z2jh.get_config('custom.myLongString') 将返回一个字符串 "Line1\nLine2"

  5. z2jh.get_config('custom.nonExistent') 将返回 None(因为没有为 nonExistent 指定任何值)

  6. z2jh.get_config('custom.myDefault', True) 将返回 True,因为它是作为第二个参数(默认值)指定的

您需要在 extraConfig 的顶部添加 import z2jh,才能使 z2jh.get_config(...) 正常工作。

hub.extraEnv#

此属性接受一个字典,该字典被设置为 hub 容器中的环境变量。您可以使用它将额外的配置传递到 hub.extraConfig 中的代码,或者设置一些无法通过其他方式设置的 hub 参数。

hub.extraContainers#

一个额外的容器列表,这些容器与 hub 容器捆绑在一起,位于同一个 pod 中。这在 kubernetes 中是一种 常见模式,具有许多酷炫的用例。一些示例用例包括

  1. 数据库代理,有时需要 hub 与其配置的数据库(例如,在 Google Cloud 中)进行通信

  2. 服务器/其他守护进程,由 hub.customConfig 中的代码使用

此列表中的项目必须是有效的 kubernetes 容器规范

指定合适的 hub 存储#

默认情况下,hub 的 sqlite-pvc 设置将动态创建一个磁盘来存储 sqlite 数据库。可以在 配置其他存储类(在 hub.db.pvc 下),但请确保选择一个 hub 可以快速安全地写入的存储类。缓慢或高延迟的存储类会导致 hub 操作滞后,最终可能导致用户环境中的 HTTP 错误。

从父 Helm 图表模板引用资源#

此 Helm 图表中的 k8s 资源不应通过硬编码名称引用,因为它们可以通过 fullnameOverridenameOverride 进行调整。因此,要可靠地引用它们,您可以使用定义的 Helm 模板。

以下是如何定义一个 RoleBinding 的示例,该 RoleBinding 绑定了一些您定义的角色以及 hub k8s ServiceAccount,如果使用了 fullnameOverridenameOverride,该 ServiceAccount 的名称可能略有不同。

kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: my-role-binding
subjects:
  - kind: ServiceAccount
    name: {{ include "jupyterhub.hub.fullname" . }}
    namespace: "{{ .Release.Namespace }}"
roleRef:
  kind: Role
  name: my-role
  apiGroup: rbac.authorization.k8s.io