jupyterhub · minrk · Jan 27, 2021 · Jan 16, 2021 · Jan 21, 2021 · Jan 21, 2021
diff --git a/.github/workflows/test-chart.yaml b/.github/workflows/test-chart.yaml
@@ -94,9 +94,15 @@ jobs:
           - k3s-channel: v1.19
             test: upgrade
             upgrade-from: stable
+            upgrade-from-extra-args: >-
+              --set proxy.secretToken=aaa111
+              --set hub.cookieSecret=bbb222
+              --set hub.config.CryptKeeper.keys[0]=ccc333
           - k3s-channel: v1.19
             test: upgrade
             upgrade-from: dev
+            upgrade-from-extra-args: >-
+              --set proxy.secretToken=aaa111
 
     steps:
       - uses: actions/checkout@v2
@@ -163,10 +169,11 @@ jobs:
           #
           #        https://github.com/helm/helm/issues/9244
           cd ci
-          helm install jupyterhub --repo https://jupyterhub.github.io/helm-chart/ jupyterhub --values ../dev-config.yaml --version=$UPGRADE_FROM_VERSION
+          helm install jupyterhub --repo https://jupyterhub.github.io/helm-chart/ jupyterhub --values ../dev-config.yaml --version=$UPGRADE_FROM_VERSION ${{ matrix.upgrade-from-extra-args }}
 
-          echo ""
-          echo "Installing Helm diff plugin while k8s resources are initializing"
+      - name: "Install helm diff plugin"
+        if: matrix.test == 'upgrade'
+        run: |
           helm plugin install https://github.com/databus23/helm-diff
 
       # ref: https://github.com/jacobtomlinson/gha-read-helm-chart
@@ -190,6 +197,7 @@ jobs:
           echo
 
           helm diff upgrade --install jupyterhub ./jupyterhub --values dev-config.yaml \
+              --show-secrets \
               --context=3 \
               --post-renderer=ci/string-replacer.sh
 
@@ -203,8 +211,11 @@ jobs:
 
       - name: "Install or upgrade to local chart"
         run: |
-          . ./ci/common
           helm upgrade --install jupyterhub ./jupyterhub --values dev-config.yaml
+
+      - name: Await local chart
+        run: |
+          . ./ci/common
           await_jupyterhub
           await_autohttps_tls_cert_acquisition
 

diff --git a/dev-config.yaml b/dev-config.yaml
@@ -1,5 +1,4 @@
 proxy:
-  secretToken: pppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppp
   service:
     type: NodePort
     nodePorts:
@@ -33,7 +32,6 @@ proxy:
       egress: [] # overrides allowance of 0.0.0.0/0
 
 hub:
-  cookieSecret: cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc
   db:
     type: sqlite-memory
   services:

diff --git a/doc/source/administrator/debug.md b/doc/source/administrator/debug.md
@@ -104,7 +104,7 @@ Now we are sure that something is wrong with our Dockerfile. Let's check
 our `config.yaml` file for the section where we specify the user's
 Docker image. Here we see our problem:
 
-```
+```yaml
 singleuser:
   image:
     name: jupyter/scipy-notebook
@@ -116,7 +116,7 @@ the pod to fail.
 
 To fix this, let's add a tag to our `config.yaml` file:
 
-```
+```yaml
 singleuser:
   image:
     name: jupyter/scipy-notebook
@@ -173,48 +173,3 @@ And now we see that we have a running user pod!
 Note that many debugging situations are not as straightforward as this one.
 It will take some time before you get a feel for the errors that Kubernetes
 may throw at you, and how these are tied to your configuration files.
-
-## Troubleshooting Examples
-
-The following sections contain some case studies that illustrate some of the
-more common bugs / gotchas that you may experience using JupyterHub with
-Kubernetes.
-
-### Hub fails to start
-
-**Symptom:** following `kubectl get pod`, the `hub` pod is in
-`Error` or `CrashLoopBackoff` state, or appears to be running but accessing
-the website for the JupyterHub returns an error message in the browser).
-
-**Investigating:** the output of `kubectl --namespace=jhub logs hub...` shows something like:
-
-```
-File "/usr/local/lib/python3.5/dist-packages/jupyterhub/proxy.py", line 589, in get_all_routes
-  resp = yield self.api_request('', client=client)
-tornado.httpclient.HTTPError: HTTP 403: Forbidden
-```
-
-**Diagnosis:** This is likely because the `hub` pod cannot
-communicate with the proxy pod API, likely because of a problem in the
-`secretToken` that was put in `config.yaml`.
-
-**Fix:** Follow these steps:
-
-1. Create a secret token:
-
-   ```
-   openssl rand -hex 32
-   ```
-
-2. Add the token to `config.yaml` like so:
-
-   ```
-   proxy:
-      secretToken: '<output of `openssl rand -hex 32`>'
-   ```
-
-3. Redeploy the helm chart:
-
-   ```
-   helm upgrade --cleanup-on-fail jhub jupyterhub/jupyterhub -f config.yaml
-   ```
diff --git a/doc/source/jupyterhub/installation.md b/doc/source/jupyterhub/installation.md
@@ -2,54 +2,45 @@
 
 # Installing JupyterHub
 
-Now that we have a {doc}`Kubernetes cluster </kubernetes/setup-kubernetes>` and {doc}`Helm </kubernetes/setup-helm>` setup, we can proceed by using Helm to install JupyterHub
-and related {term}`Kubernetes resources <Kubernetes resource>` using a
-{term}`Helm chart`.
-
-## Prepare configuration file
-
-In this step we will prepare a [YAML](https://en.wikipedia.org/wiki/YAML)
-configuration file that we will refer to as `config.yaml`. It will contain the multiple
-{term}`Helm values` to be provided to a JupyterHub {term}`Helm chart` developed
-specifically together with this guide.
-
-Helm charts contains {term}`templates <Helm template>` that with provided values will render to {term}`Kubernetes resources <Kubernetes resource>` to be installed in a Kubernetes cluster. This
-config file will provide the values to be used by our Helm chart.
-
-1. Generate a random hex string representing 32 bytes to use as a security
-   token. Run this command in a terminal and copy the output:
-
-   ```{code-block} bash
-
-   openssl rand -hex 32
-
-   ```
-
-2. Create and start editing a file called `config.yaml`. In the code snippet
-   below we start the widely available [nano editor](https://en.wikipedia.org/wiki/GNU_nano), but any editor will do.
-
-   ```
-   nano config.yaml
-   ```
-
-3. Write the following into the `config.yaml` file but instead of writing
-   `<RANDOM-HEX>` paste the generated hex string you copied in step 1.
-
-   ```
-   proxy:
-     secretToken: "<RANDOM_HEX>"
-   ```
-
-   It is common practice for Helm and Kubernetes YAML files to indent using
-   two spaces.
-
-4. Save the `config.yaml` file. In the nano editor this is done by pressing **CTRL+X** or
-   **CMD+X** followed by a confirmation to save the changes.
-
-<!---
-Don't put an example here! People will just copy paste that & that's a
-security issue.
--->
+With a {doc}`Kubernetes cluster </kubernetes/setup-kubernetes>` cluster
+available and {doc}`Helm </kubernetes/setup-helm>` installed, we can install
+JupyterHub in the Kubernetes cluster using the JupyterHub Helm chart.
+
+## Initialize a Helm chart configuration file
+
+Helm charts' contain {term}`templates <Helm template>` that can be rendered to
+the {term}`Kubernetes resources <Kubernetes resource>` to be installed. A user
+of a Helm chart can override the chart's default values to influence how the
+templates render.
+
+In this step we will initialize a chart configuration file for you to adjust
+your installation of JupyterHub. We will name and refer to it as `config.yaml`
+going onwards.
+
+```{admonition} Introduction to YAML
+If you haven't worked with YAML before, investing some
+minutes [learning about it]([YAML](https://www.youtube.com/watch?v=cdLNKUoMc6c)
+will likely be worth your time.
+```
+
+As of version 1.0.0, you don't need any configuration to get started so you can
+just create a `config.yaml` file with some helpful comments.
+
+```yaml
+# This file can update the JupyterHub Helm chart's default configuration values.
+#
+# For reference see the configuration reference and default values, but make
+# sure to refer to the Helm chart version of interest to you!
+#
+# Introduction to YAML:     https://www.youtube.com/watch?v=cdLNKUoMc6c
+# Chart config reference:   https://zero-to-jupyterhub.readthedocs.io/en/stable/resources/reference.html
+# Chart default values:     https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/HEAD/jupyterhub/values.yaml
+# Available chart versions: https://jupyterhub.github.io/helm-chart/
+#
+```
+
+In case you are working from a terminal and are unsure how to create this file,
+can try with `nano config.yaml`.
 
 ## Install JupyterHub
 

diff --git a/jupyterhub/files/hub/jupyterhub_config.py b/jupyterhub/files/hub/jupyterhub_config.py
@@ -12,7 +12,13 @@
 configuration_directory = os.path.dirname(os.path.realpath(__file__))
 sys.path.insert(0, configuration_directory)
 
-from z2jh import get_config, set_config_if_not_none, get_name, get_name_env
+from z2jh import (
+    get_config,
+    set_config_if_not_none,
+    get_name,
+    get_name_env,
+    get_secret_value,
+)
 
 
 def camelCaseify(s):
@@ -66,7 +72,6 @@ def camelCaseify(s):
     ("concurrent_spawn_limit", None),
     ("active_server_limit", None),
     ("base_url", None),
-    # ('cookie_secret', None),  # requires a Hex -> Byte transformation
     ("allow_named_servers", None),
     ("named_server_limit_per_user", None),
     ("authenticate_prometheus", None),
@@ -79,11 +84,6 @@ def camelCaseify(s):
         cfg_key = camelCaseify(trait)
     set_config_if_not_none(c.JupyterHub, trait, "hub." + cfg_key)
 
-# a required Hex -> Byte transformation
-cookie_secret_hex = get_config("hub.cookieSecret")
-if cookie_secret_hex:
-    c.JupyterHub.cookie_secret = a2b_hex(cookie_secret_hex)
-
 # hub_bind_url configures what the JupyterHub process within the hub pod's
 # container should listen to.
 hub_container_port = 8081
@@ -372,9 +372,19 @@ def camelCaseify(s):
     c.Spawner.debug = True
 
 
-# load hub.config values
+# load potentially seeded secrets
+c.JupyterHub.proxy_auth_token = get_secret_value("JupyterHub.proxy_auth_token")
+c.JupyterHub.cookie_secret = a2b_hex(get_secret_value("JupyterHub.cookie_secret"))
+c.CryptKeeper.keys = get_secret_value("CryptKeeper.keys").split(";")
+
+# load hub.config values, except potentially seeded secrets
 for section, sub_cfg in get_config("hub.config", {}).items():
-    c[section].update(sub_cfg)
+    if section == "JupyterHub" and sub_cfg in ["proxy_auth_token", "cookie_secret"]:
+        pass
+    elif section == "CryptKeeper" and sub_cfg in ["keys"]:
+        pass
+    else:
+        c[section].update(sub_cfg)
 
 # execute hub.extraConfig string
 extra_config = get_config("hub.extraConfig", {})

diff --git a/jupyterhub/files/hub/z2jh.py b/jupyterhub/files/hub/z2jh.py
@@ -36,6 +36,18 @@ def _get_config_value(key):
         raise Exception(f"{path} not found!")
 
 
+@lru_cache()
+def get_secret_value(key):
+    """Load value from the k8s Secret given a key."""
+
+    path = f"/etc/jupyterhub/secret/{key}"
+    if os.path.exists(path):
+        with open(path) as f:
+            return f.read()
+    else:
+        raise Exception(f"{path} not found!")
+
+
 def get_name(name):
     """Returns the fullname of a resource given its short name"""
     return _get_config_value(name)

diff --git a/jupyterhub/schema.yaml b/jupyterhub/schema.yaml
@@ -280,6 +280,11 @@ properties:
           - string
           - "null"
         description: |
+          ```{note}
+          As of version 1.0.0 this will automatically be generated and there is
+          no need to set it manually.
+          ```
+
           A 32-byte cryptographically secure randomly generated string used to sign values of
           secure cookies set by the hub. If unset, jupyterhub will generate one on startup and
           save it in the file `jupyterhub_cookie_secret` in the `/srv/jupyterhub` directory of
@@ -468,8 +473,6 @@ properties:
                  The user specified in the connection string must have the rights to create
                  tables in the database specified.
 
-                 Note that if you use this, you *must* also set `hub.cookieSecret`.
-
               4. **postgres**
 
                  Use an externally hosted postgres database.
@@ -484,8 +487,6 @@ properties:
 
                  The user specified in the connection string must have the rights to create
                  tables in the database specified.
-
-                 Note that if you use this, you *must* also set `hub.cookieSecret`.
           pvc:
             type: object
             description: |
@@ -717,16 +718,6 @@ properties:
           This k8s Secret must represent the structure generated by this chart
           and by using this option, you are in change of ensuring the secret
           structure is reflected when upgrading to new versions of the chart.
-
-          ```yaml
-          apiVersion: v1
-          data:
-            proxy.token: < FILL IN >
-            values.yaml: < FILL IN >
-          kind: Secret
-          metadata:
-            name: my-self-managed-secret
-          ```
       nodeSelector: &nodeSelector-spec
         type:
           - object
@@ -836,6 +827,11 @@ properties:
       secretToken:
         type: string
         description: |
+          ```{note}
+          As of version 1.0.0 this will automatically be generated and there is
+          no need to set it manually.
+          ```
+
           A 32-byte cryptographically secure randomly generated string used to secure communications
           between the hub and the configurable-http-proxy.
 
@@ -846,7 +842,7 @@ properties:
 
           Changing this value will cause the proxy and hub pods to restart. It is good security
           practice to rotate these values over time. If this secret leaks, *immediately* change
-          it to something else, or user data can be compromised
+          it to something else, or user data can be compromised.
       service:
         type: object
         description: |