调试#

有时您的 JupyterHub 部署可能不会按预期运行。本节提供了一些关于调试和修复常见问题的技巧。

详细日志记录#

通过将以下内容添加到您的配置中,您可以增加各种 Pod(hub、proxy、autohttps 和用户 Pod)输出日志的详细程度。

debug:
  enabled: true

如果 JupyterHub 已启动,但您在身份验证、单用户服务器或服务方面遇到问题,这会特别有用。启用此功能的缺点是,输出的日志量会使概览日志更难阅读,并且会增加用于收集和存储日志的系统的成本。

调试命令#

为了调试您的 JupyterHub 部署,您需要能够检查正在使用的资源的状态。以下是一些用于调试的常用命令。

真实场景: 假设您部署了一个 JupyterHub,并且一个用户告诉您他们遇到了奇怪的行为。让我们看看我们的部署,找出问题所在。

kubectl get pod#

列出您 Kubernetes 部署中的所有 Pod。

kubectl get pod --namespace <k8s-namespace>

这将输出部署中正在使用的所有 Pod 的列表。

真实场景: 在我们的案例中,我们看到两个用于 JupyterHub 基础设施的 Pod(hubproxy),以及一个用户 Pod,该 Pod 是在有人登录到 JupyterHub 时创建的。

以下是输出示例:

$ kubectl get pod --namespace <k8s-namespace>
NAME                                READY     STATUS         RESTARTS   AGE
hub-3311438805-xnfvp     1/1       Running        0          2m
jupyter-choldgraf                   0/1       ErrImagePull   0          25s
proxy-1227971824-mn2wd   1/1       Running        0          5h

在这里我们可以看到两个 JupyterHub Pod,以及一个单用户 Pod。请注意,所有用户 Pod 都将以 jupyter- 开头。

请特别留意 STATUS 列。如果某个 Pod 的状态不是 Running,那么可能出了问题。

在这种情况下,我们可以看到我们用户的 Pod 处于 ErrImagePull 状态。这通常意味着在我们的 helm chart 配置中,singleuser 中定义的 Docker 镜像有问题。让我们进一步探究……

kubectl describe pod#

要查看特定 Pod 状态的更多详细信息,请使用以下命令:

kubectl describe pod <pod-name> --namespace <k8s-namespace>

这将输出多条信息,包括 Pod 的配置和设置。您将看到的最后一部分是最近事件的列表。这些信息尤其有用,因为错误通常会出现在此部分。

kubectl logs#

如果您只想查看 Pod 的最新日志,请使用以下命令:

kubectl logs <POD_NAME> --namespace <k8s-namespace>

这将显示 Pod 的日志,其中通常包含有关问题所在的有用信息。解析这些日志以查看是否有任何内容正在产生错误。

当您确定错误后,如有必要,请编辑您的 config.yaml 文件,然后运行 helm 升级:

helm upgrade --cleanup-on-fail jhub jupyterhub/jupyterhub --version=<chart-version> -f config.yaml

其中 jhub 是 helm 的发布名称(请替换为您在设置期间选择的发布名称)。

注意

根据 Docker 镜像的大小,这可能需要一些时间才能完成。

在运行此命令后,让我们再次列出我们部署中的 Pod:

$ kubectl get pod --namespace=<k8s-namespace>
NAME                                READY     STATUS              RESTARTS   AGE
hub-2653507799-r7wf8     0/1       ContainerCreating   0          31s
hub-3311438805-xnfvp     1/1       Terminating         0          14m
jupyter-choldgraf                   0/1       ImagePullBackOff    0          12m
proxy-deployment-1227971824-mn2wd   1/1       Running             0          5h

在这里我们可以看到一个 hub Pod 正在被销毁,另一个(基于升级后的 helm chart)正在被创建。我们还看到我们有问题的用户 Pod,它不会被自动删除。让我们手动删除它,以便可以启动一个新的、能正常工作的 Pod。

$ kubectl delete pod jupyter-choldgraf --namespace <k8s-namespace>

最后,我们告诉用户重新登录到 JupyterHub。然后让我们再次列出正在运行的 Pod:

$ kubectl get pod --namespace <k8s-namespace>
NAME                                READY     STATUS    RESTARTS   AGE
hub-2653507799-r7wf8     1/1       Running   0          3m
jupyter-choldgraf                   1/1       Running   0          18s
proxy-deployment-1227971824-mn2wd   1/1       Running   0          5h

现在我们看到我们有一个正在运行的用户 Pod 了!

请注意,许多调试情况并不像这个这么直接。您需要一些时间才能熟悉 Kubernetes 可能抛出的错误,以及这些错误如何与您的配置文件相关联。