Merge pull request #2206 from consideRatio/pr/refactor-away-helper

Minor documentation fixes

doc/source/administrator/authentication.md

@@ -85,26 +85,39 @@ hub:
 ### [enable_auth_state](https://jupyterhub.readthedocs.io/en/latest/api/auth.html#jupyterhub.auth.Authenticator.enable_auth_state)
 
 If you want JupyterHub to persist often sensitive information received as part
-of logging in, you need to enable it and provide one or more keys for encryption
-and decryption.
+of logging in, you need to enable it.
 
-The recommended way of doing so for this Helm chart is to configure
-[CryptKeeper](https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/crypto.py)
-with keys rather than setting an environment variable.
+```yaml
+hub:
+  config:
+    Authenticator:
+      enable_auth_state: true
+```
 
-For more information, see [JupyterHub's own
+For more information about authentication state, see [JupyterHub's own
 documentation](https://jupyterhub.readthedocs.io/en/latest/reference/authenticators.html#authentication-state)
 about authentication state.
 
+````{note}
+The encryption and decryption of auth state requires a cryptographical key.
+
+As of version 1.0.0 this will automatically be generated and there is no need to
+set it manually.
+
+If you wish to reset a generated key, you can use `kubectl edit` on the k8s
+Secret typically named `hub` and remove the `hub.config.CryptKeeper.keys` entry
+in the k8s Secret, then perform a new `helm upgrade`.
+
+To manually set a cryptographical key, you can do it like this.
+
 ```yaml
 hub:
   config:
-    Authenticator:
-      enable_auth_state: true
     CryptKeeper:
       keys:
         - 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
 ```
+````
 
 ## Configuring authenticator classes
 

jupyterhub/schema.yaml

@@ -472,6 +472,11 @@ properties:
           ```{note}
           As of version 1.0.0 this will automatically be generated and there is
           no need to set it manually.
+
+          If you wish to reset a generated key, you can use `kubectl edit` on
+          the k8s Secret typically named `hub` and remove the
+          `hub.config.JupyterHub.cookie_secret` entry in the k8s Secret, then
+          perform a new `helm upgrade`.
           ```
 
           A 32-byte cryptographically secure randomly generated string used to sign values of
@@ -939,7 +944,6 @@ properties:
           1. The self managed k8s Secret must mirror the structure in the chart
              managed secret.
           2. [`proxy.secretToken`](schema_proxy.secretToken) (aka.
-             `hub.config.JupyterHub.proxy_auth_token` and
              `hub.config.ConfigurableHTTPProxy.auth_token`) is only read from
              the chart managed k8s Secret.
           ```
@@ -1174,10 +1178,17 @@ properties:
           ```{note}
           As of version 1.0.0 this will automatically be generated and there is
           no need to set it manually.
+
+          If you wish to reset a generated key, you can use `kubectl edit` on
+          the k8s Secret typically named `hub` and remove the
+          `hub.config.ConfigurableHTTPProxy.auth_token` entry in the k8s Secret,
+          then perform a new `helm upgrade`.
           ```
 
-          A 32-byte cryptographically secure randomly generated string used to secure communications
-          between the hub and the configurable-http-proxy.
+          A 32-byte cryptographically secure randomly generated string used to
+          secure communications between the hub pod and the proxy pod running a
+          [configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy)
+          instance.
 
           ```sh
           # to generate a value, run

jupyterhub/templates/NOTES.txt

@@ -50,71 +50,88 @@ If you have questions, please:
   2. Ask for help or chat to us on https://discourse.jupyter.org/
   3. If you find a bug please report it at https://github.com/jupyterhub/zero-to-jupyterhub-k8s/issues
 
-{{- if hasKey .Values.singleuser.cloudMetadata "enabled" }}{{ println }}
-DEPRECATION: singleuser.cloudMetadata.enabled is deprecated, instead use singleuser.cloudMetadata.blockWithIptables with the inverted value.
+
+
+
+
+{{- /*
+  Warnings for likely misconfiguration
+*/}}
+
+{{- if and (not .Values.scheduling.podPriority.enabled) (and .Values.scheduling.userPlaceholder.enabled .Values.scheduling.userPlaceholder.replicas) }}
+
+WARNING: You are using user placeholders without pod priority enabled, either
+enable pod priority or stop using the user placeholders to avoid wasting cloud
+resources.
 {{- end }}
 
 
-{{- /* Warn about an attempt to configure HTTPS but not having enabled it. */}}
 {{- if eq .Values.proxy.https.enabled false }}
 {{- if or (not (eq .Values.proxy.https.type "letsencrypt")) (not (eq (.Values.proxy.https.letsencrypt.contactEmail | default "") "")) }}{{ println }}
 WARNING: Configuring proxy.https without setting proxy.https.enabled to true is no longer allowed.
 {{- end }}
 {{- end }}
 
 
-{{- if .Values.proxy.containerSecurityContext }}
-{{- fail "DEPRECATION: proxy.containerSecurityContext has been renamed to proxy.chp.containerSecurityContext" }}
-{{- end }}
 
 
-{{- if .Values.proxy.networkPolicy }}
-{{- fail "DEPRECATION: proxy.networkPolicy has been renamed to proxy.chp.networkPolicy" }}
-{{- end }}
 
+{{- /*
+  Deprecation messages that can be removed in 2.0.0
+*/}}
 
 {{- if .Values.hub.extraConfigMap }}{{ println }}
 DEPRECATION: hub.extraConfigMap is deprecated in jupyterhub chart 0.8.
 Use top-level `custom` instead:
 
----
 custom:
-{{- (merge dict .Values.custom .Values.hub.extraConfigMap) | toYaml | nindent 2}}
----
+{{- (merge dict .Values.custom .Values.hub.extraConfigMap) | toYaml | nindent 2 }}
 {{- end }}
 
-{{- if and (not .Values.scheduling.podPriority.enabled) (and .Values.scheduling.userPlaceholder.enabled .Values.scheduling.userPlaceholder.replicas) }}
 
-WARNING: You are using user placeholders without pod priority enabled, either
-enable pod priority or stop using the user placeholders to avoid wasting cloud
-resources.
+{{- if .Values.auth }}
+{{ fail (include "jupyterhub.authDep.remapOldToNew" .) }}
 {{- end }}
 
 
-{{- if hasKey .Values.hub "uid" }}{{ println }}
-DEPRECATION: hub.uid is deprecated in jupyterhub chart 0.9. Set the hub.containerSecurityContext.runAsUser value
-directly instead.
+{{- if .Values.proxy.containerSecurityContext }}
+{{- fail "\n\nHARD DEPRECATION: proxy.containerSecurityContext has been renamed to proxy.chp.containerSecurityContext" }}
 {{- end }}
 
 
-{{- if hasKey .Values.hub "imagePullSecret" }}
-{{- if .Values.hub.imagePullSecret.enabled }}
-{{ "HARD DEPRECATION: hub.imagePullSecret has renamed to imagePullSecret" | fail }}
+{{- if hasKey .Values.proxy "pdb" }}
+{{ fail "\n\nHARD DEPRECATION: proxy.pdb has renamed to proxy.chp.pdb" }}
 {{- end }}
+
+
+{{- if .Values.proxy.networkPolicy }}
+{{- fail "\n\nHARD DEPRECATION: proxy.networkPolicy has been renamed to proxy.chp.networkPolicy" }}
 {{- end }}
 
 
-{{- if hasKey .Values.singleuser "imagePullSecret" }}
-{{- if .Values.singleuser.imagePullSecret.enabled }}
-{{ "HARD DEPRECATION: singleuser.imagePullSecret has renamed to imagePullSecret" | fail }}
+{{- if hasKey .Values.hub "uid" }}
+{{- print "\n\nDEPRECATION: hub.uid is deprecated in jupyterhub chart 0.9. Set the hub.containerSecurityContext.runAsUser value directly instead." }}
 {{- end }}
+
+
+{{- if (.Values.hub | dig "imagePullSecret" "enabled" "") }}
+{{- fail "\n\nHARD DEPRECATION: hub.imagePullSecret has renamed to imagePullSecret" }}
 {{- end }}
 
 
-{{- if hasKey .Values.proxy "pdb" }}
-{{ "HARD DEPRECATION: proxy.pdb has renamed to proxy.chp.pdb" | fail }}
+{{- if (.Values.singleuser | dig "imagePullSecret" "enabled" "") }}
+{{- fail "\n\nHARD DEPRECATION: singleuser.imagePullSecret has renamed to imagePullSecret" }}
 {{- end }}
 
-{{- if .Values.auth }}
-{{ include "jupyterhub.authDep.remapOldToNew" . | fail }}
+
+{{- if (.Values.singleuser | dig "cloudMetadata" "enabled" "") }}
+{{- print "\n\nDEPRECATION: singleuser.cloudMetadata.enabled is deprecated, instead use singleuser.cloudMetadata.blockWithIptables with the inverted value." }}
 {{- end }}
+
+
+
+
+
+{{- /*
+  Deprecation messages that can be removed in 3.0.0
+*/}}

jupyterhub/templates/hub/_helpers-passwords.tpl

@@ -4,7 +4,10 @@
 
     proxy.secretToken       / hub.config.ConfigurableHTTPProxy.auth_token
     hub.cookieSecret        / hub.config.JupyterHub.cookie_secret
-    auth.state.cryptoKey    / hub.config.CryptKeeper.keys
+    auth.state.cryptoKey*   / hub.config.CryptKeeper.keys
+
+    *Note that the entire auth section is deprecated and users
+    are forced through "fail" in NOTES.txt to migrate to hub.config.
 
     Note that lookup logic returns falsy value when run with
     `helm diff upgrade`, so it is a bit troublesome to test.

jupyterhub/templates/proxy/deployment.yaml

@@ -28,6 +28,12 @@ spec:
         # Other changes to the hub config should not restart.
         # We truncate to 4 chars to avoid leaking auth token info,
         # since someone could brute force the hash to obtain the token
+        #
+        # Note that if auth_token has to be generated at random, it will be
+        # generated at random here separately from being generated at random in
+        # the k8s Secret template. This will cause this annotation to change to
+        # match the k8s Secret during the first upgrade following an auth_token
+        # was generated.
         checksum/auth-token: {{ include "jupyterhub.hub.config.ConfigurableHTTPProxy.auth_token" . | sha256sum | trunc 4 | quote }}
         checksum/proxy-secret: {{ include (print $.Template.BasePath "/proxy/secret.yaml") . | sha256sum | quote }}
         {{- with .Values.proxy.annotations }}

tools/templates/lint-and-validate-values.yaml

@@ -8,14 +8,12 @@ imagePullSecret:
 imagePullSecrets: [a, b]
 
 hub:
-  cookieSecret: bbbb2222
   config:
     # We pin these to avoid generating changes which cause diffs
-    # FIXME: https://github.com/jupyterhub/zero-to-jupyterhub-k8s/issues/2108
     ConfigurableHTTPProxy:
-      auth_token: aaaa1111 # currently ignored, proxy.secretToken is used
+      auth_token: aaaa1111
     JupyterHub:
-      cookie_secret: bbbb2222 # currently ignored, hub.cookieSecret is used
+      cookie_secret: bbbb2222
     CryptKeeper:
       keys: [cccc3333]
   extraFiles:
@@ -155,7 +153,6 @@ rbac:
   enabled: true
 
 proxy:
-  secretToken: aaaa1111 # see hub.config section for a FIXME
   service:
     extraPorts:
       - name: ssh