高级主题#

此页面包含一系列在其他地方不易归类的有用主题。

  • Ingress

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

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

Ingress#

可以配置 Helm chart 来创建一个 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-lego 从 Let’s Encrypt 自动获取和续订 HTTPS 证书。这种结合 kube-lego 和 Let’s Encrypt 的方法目前仅适用于两个 Ingress 控制器：社区维护的 kubernetes/ingress-nginx 和 Google Cloud 的 Ingress 控制器。

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

  2. 使用 kube-lego helm-chart 安装和配置 kube-lego。请至少记得更改 config.LEGO_EMAIL 和 config.LEGO_URL。

  3. 向 Ingress 添加一个注解（annotation）和 TLS 配置，以便 kube-lego 知道要为其获取证书

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

这样应该能提供一个证书，并在接近过期时自动续订！

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

有时，helm-chart 的 values.yaml 文件中暴露的各种选项不足以满足需求，您需要向 jupyterhub_config.py 中插入任意额外的代码或配置。这是一种很有价值的“应急出口”，既可以用于原型化 helm-chart 中尚未存在的新功能，也可以用于不适合向上游提交的特定于安装的定制化。

您可以在 config.yaml 中设置四个属性来实现此目的。

hub.extraConfig#

为 hub.extraConfig 指定的值会在 JupyterHub 加载的 jupyterhub_config.py 文件末尾作为 Python 代码执行。您可以在 hub.extraConfig 中执行任何操作，因为它是任意的 Python 代码，而 hub.config 只允许您指定固定的配置值。

您可以做的一些示例：

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

  2. 指定接受可调用对象（callable）作为值的 traitlet，从而允许按用户进行动态配置。

  3. 为 Helm chart 当前不支持的 JupyterHub / Spawner / Authenticator 设置 traitlet。

您应该将 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。chart 的 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 chart 的模板中引用资源#

此 Helm chart 中的 k8s 资源不应通过硬编码名称引用，因为它们可以通过 fullnameOverride 或 nameOverride 进行调整。因此，为了可靠地引用它们，您可以使用已定义的 Helm 模板。

下面是一个示例，展示了如何定义一个 RoleBinding，它将您定义的某个 Role 与 hub k8s ServiceAccount 绑定在一起。如果使用了 fullnameOverride 或 nameOverride，这个 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