From 9afca0c5bfaaa20f2ff91eff33d2080b23749e1d Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Sat, 20 Feb 2021 06:44:36 +0100 Subject: [PATCH] docs: helm3 compliance, avoid specification of chart versions --- doc/source/administrator/debug.md | 25 +++++------ doc/source/administrator/upgrading.md | 16 +++---- .../customizing/extending-jupyterhub.md | 9 ++-- doc/source/jupyterhub/installation.md | 45 ++++++++----------- 4 files changed, 40 insertions(+), 55 deletions(-) diff --git a/doc/source/administrator/debug.md b/doc/source/administrator/debug.md index 3af03de75d..a856d320cf 100644 --- a/doc/source/administrator/debug.md +++ b/doc/source/administrator/debug.md @@ -15,17 +15,12 @@ for debugging. tells you that they are experiencing strange behavior. Let's take a look at our deployment to figure out what is going on. -```{note} -For our real world scenario, we'll assume that our Kubernetes namespace -is called `jhub`. Your namespace may be called something different -``` - ### `kubectl get pod` To list all pods in your Kubernetes deployment: ``` -kubectl --namespace=jhub get pod +kubectl get pod --namespace ``` This will output a list of all pods being used in the deployment. @@ -37,7 +32,7 @@ pod that was created when somebody logged in to the JupyterHub. Here's an example of the output: ``` -$ kubectl --namespace=jhub get pod +$ kubectl get pod --namespace NAME READY STATUS RESTARTS AGE hub-3311438805-xnfvp 1/1 Running 0 2m jupyter-choldgraf 0/1 ErrImagePull 0 25s @@ -60,7 +55,7 @@ To see more detail about the state of a specific pod, use the following command: ``` -kubectl --namespace=jhub describe pod +kubectl describe pod --namespace ``` This will output several pieces of information, including configuration and @@ -72,7 +67,7 @@ show up in this section. displays an error: ``` -$ kubectl --namespace=jhub describe pod jupyter-choldgraf +$ kubectl describe pod jupyter-choldgraf --namespace ... 2m 52s 4 kubelet, gke-jhubtest-default-pool-52c36683-jv6r spec.containers{notebook} Warning Failed Failed to pull image "jupyter/scipy-notebook:v0.4": rpc error: code = 2 desc = Error response from daemon: {"message":"manifest for jupyter/scipy-notebook:v0.4 not found"} ... @@ -86,7 +81,7 @@ this by getting another view on the events that have transpired in the pod. If you only want to see the latest logs for a pod, use the following command: ``` -kubectl --namespace=jhub logs +kubectl logs --namespace ``` This will show you the logs from the pod, which often contain useful @@ -96,7 +91,7 @@ to see if something is generating an error. **Real world scenario:** In our case, we get this line back: ``` -$ kubectl --namespace=jhub logs jupyter-choldgraf +$ kubectl logs jupyter-choldgraf --namespace Error from server (BadRequest): container "notebook" in pod "jupyter-choldgraf" is waiting to start: trying and failing to pull image ``` @@ -126,7 +121,7 @@ singleuser: Then run a helm upgrade: ``` -helm upgrade --cleanup-on-fail jhub jupyterhub/jupyterhub --version=v0.6 -f config.yaml +helm upgrade --cleanup-on-fail jhub jupyterhub/jupyterhub --version= -f config.yaml ``` where `jhub` is the helm release name (substitute the release name that you @@ -140,7 +135,7 @@ Right after you run this command, let's once again list the pods in our deployment: ``` -$ kubectl --namespace=jhub get pod +$ kubectl get pod --namespace= NAME READY STATUS RESTARTS AGE hub-2653507799-r7wf8 0/1 ContainerCreating 0 31s hub-3311438805-xnfvp 1/1 Terminating 0 14m @@ -154,14 +149,14 @@ which will not be deleted automatically. Let's manually delete it so a newer working pod can be started.: ``` -$ kubectl --namespace=jhub delete pod jupyter-choldgraf +$ kubectl delete pod jupyter-choldgraf --namespace ``` Finally, we'll tell our user to log back in to the JupyterHub. Then let's list our running pods once again: ``` -$ kubectl --namespace=jhub get pod +$ kubectl get pod --namespace NAME READY STATUS RESTARTS AGE hub-2653507799-r7wf8 1/1 Running 0 3m jupyter-choldgraf 1/1 Running 0 18s diff --git a/doc/source/administrator/upgrading.md b/doc/source/administrator/upgrading.md index 01bd385bad..2ad696b015 100644 --- a/doc/source/administrator/upgrading.md +++ b/doc/source/administrator/upgrading.md @@ -51,10 +51,10 @@ This section covers upgrade information specific to the following: ### `helm upgrade` command After modifying your `config.yaml` file according to the CHANGELOG, you will need -`` to run the upgrade commands. To find ``, run: +`` to run the upgrade commands. To find ``, run: ``` -helm list +helm list --namespace ``` Make sure to test the upgrade on a staging environment before doing the upgrade on @@ -63,13 +63,13 @@ a production system! To run the upgrade: ``` -helm upgrade --cleanup-on-fail jupyterhub/jupyterhub --version= -f config.yaml +helm upgrade --cleanup-on-fail jupyterhub/jupyterhub --version= --values config.yaml --namespace ``` -For example, to upgrade to v0.6, enter and substituting `` and version v0.6: +For example, to upgrade to v0.6, enter and substituting `` and version v0.6: ``` -helm upgrade --cleanup-on-fail jupyterhub/jupyterhub --version=v0.6 -f config.yaml +helm upgrade --cleanup-on-fail jupyterhub/jupyterhub --version= --values config.yaml --namespace ``` ### Database @@ -113,7 +113,7 @@ RUN pip install --no-cache-dir jupyterhub==0.8.1 ## JupyterHub versions installed in each Helm Chart Each Helm Chart is packaged with a specific version of JupyterHub (and -other software as well). See the [Helm Chart repository](https://github.com/jupyterhub/helm-chart#release-notes>) for +other software as well). See the [Helm Chart repository](https://jupyterhub.github.io/helm-chart/) for information about the versions of relevant software packages. ## Troubleshooting @@ -122,7 +122,7 @@ If the upgrade is failing on a test system or a system that does not serve users deleting the helm chart using: ``` -helm delete +helm delete --namespace ``` -`helm list` may be used to find . +`helm list --namespace ` may be used to find . diff --git a/doc/source/jupyterhub/customizing/extending-jupyterhub.md b/doc/source/jupyterhub/customizing/extending-jupyterhub.md index 4a9658e8d1..9c1a698836 100644 --- a/doc/source/jupyterhub/customizing/extending-jupyterhub.md +++ b/doc/source/jupyterhub/customizing/extending-jupyterhub.md @@ -16,13 +16,10 @@ The general method to modify your Kubernetes deployment is to: 2. Run a `helm upgrade`: ``` - RELEASE=jhub - NAMESPACE=jhub - helm upgrade --cleanup-on-fail \ - $RELEASE jupyterhub/jupyterhub \ - --namespace $NAMESPACE \ - --version=0.10.6 \ + jupyterhub/jupyterhub \ + --namespace \ + --version= \ --values config.yaml ``` diff --git a/doc/source/jupyterhub/installation.md b/doc/source/jupyterhub/installation.md index e47a7d5c4f..2ffa74b1ff 100644 --- a/doc/source/jupyterhub/installation.md +++ b/doc/source/jupyterhub/installation.md @@ -66,49 +66,42 @@ can try with `nano config.yaml`. command from the directory that contains your `config.yaml`: ``` - # Suggested values: advanced users of Kubernetes and Helm should feel - # free to use different values. - RELEASE=jhub - NAMESPACE=jhub - helm upgrade --cleanup-on-fail \ - --install $RELEASE jupyterhub/jupyterhub \ - --namespace $NAMESPACE \ + --install jupyterhub/jupyterhub \ + --namespace \ --create-namespace \ - --version=0.11.1 \ + --version= \ --values config.yaml ``` where: - - `RELEASE` refers to a [Helm release name](https://helm.sh/docs/glossary/#release), an identifier used to + - `` refers to a [Helm release name](https://helm.sh/docs/glossary/#release), an identifier used to differentiate chart installations. You need it when you are changing or deleting the configuration of this chart installation. If your Kubernetes cluster will contain multiple JupyterHubs make sure to differentiate them. You can list your Helm releases with `helm list`. - - `NAMESPACE` refers to a [Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), + - `` refers to a [Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), an identifier used to group Kubernetes resources, in this case all Kubernetes resources associated with the JupyterHub chart. You'll need the namespace identifier for performing any commands with `kubectl`. - - * This step may take a moment, during which time there will be no output + - This step may take a moment, during which time there will be no output to your terminal. JupyterHub is being installed in the background. - * If you get a `release named already exists` error, - then you should delete the release by running `helm delete `. Then reinstall by repeating this step. If it - persists, also do `kubectl delete namespace ` and try - again. - * In general, if something goes _wrong_ with the install step, delete the - Helm release by running `helm delete ` + - If you get a `release named already exists` error, then + you should delete the release by running `helm delete `. + Then reinstall by repeating this step. If it persists, also do `kubectl delete namespace ` and try again. + - In general, if something goes _wrong_ with the install step, delete the + Helm release by running `helm delete ` before re-running the install command. - * If you're pulling from a large Docker image you may get a + - If you're pulling from a large Docker image you may get a `Error: timed out waiting for the condition` error, add a - `--timeout=ms` parameter to the `helm install` command. - * The `--version` parameter corresponds to the _version of the Helm + `--timeout=m` parameter to the `helm` command. + - The `--version` parameter corresponds to the _version of the Helm chart_, not the version of JupyterHub. Each version of the JupyterHub Helm chart is paired with a specific version of JupyterHub. E.g., - `0.7.0` of the Helm chart runs JupyterHub `0.9.2`. + `0.11.1` of the Helm chart runs JupyterHub `1.3.0`. For a list of which JupyterHub version is installed in each version - of the Z2JH Helm Chart, see the [Helm Chart repository](https://github.com/jupyterhub/helm-chart#release-notes). + of the JupyterHub Helm Chart, see the [Helm Chart repository](https://jupyterhub.github.io/helm-chart/). 3. While Step 2 is running, you can see the pods being created by entering in a different terminal: @@ -121,7 +114,7 @@ can try with `nano config.yaml`. and set a default value for the `--namespace` flag: ``` - kubectl config set-context $(kubectl config current-context) --namespace ${NAMESPACE:-jhub} + kubectl config set-context $(kubectl config current-context) --namespace ``` 4. Wait for the _hub_ and _proxy_ pod to enter the `Running` state. @@ -137,7 +130,7 @@ can try with `nano config.yaml`. available like in the example output. ``` - kubectl get service --namespace jhub + kubectl get service --namespace ``` ``` @@ -151,7 +144,7 @@ can try with `nano config.yaml`. can find the longer version by calling: ``` - kubectl describe service proxy-public --namespace jhub + kubectl describe service proxy-public --namespace ``` 6. To use JupyterHub, enter the external IP for the `proxy-public` service in