From f34aceb0dbb7605e229ba7c80369b934ce852b24 Mon Sep 17 00:00:00 2001 From: Min RK Date: Mon, 4 Nov 2024 10:06:04 +0100 Subject: [PATCH] more links, references in upgrade docs - add explicit discussion of static subPath - remove redundant version update references - remove OAuthenticator change references --- .../administrator/upgrading/upgrade-3-to-4.md | 53 ++++++++++++------- docs/source/changelog.md | 16 ++++-- docs/source/conf.py | 1 + 3 files changed, 48 insertions(+), 22 deletions(-) diff --git a/docs/source/administrator/upgrading/upgrade-3-to-4.md b/docs/source/administrator/upgrading/upgrade-3-to-4.md index c0ce56ffa9..0770a06b7f 100644 --- a/docs/source/administrator/upgrading/upgrade-3-to-4.md +++ b/docs/source/administrator/upgrading/upgrade-3-to-4.md @@ -6,13 +6,19 @@ zero-to-jupyterhub 4.0 is a major upgrade that may require some changes to your depending on what features you may use. This mostly comes in the form of some upgraded packages, described below. -See the [changelog](changelog) for details of upgraded packages. +:::{seealso} + +- the [general upgrade documentation](upgrading-major-upgrades) for upgrade steps to take every time you do a major chart update +- the [changelog](changelog-4.0) for details of upgraded packages + +::: ## JupyterHub 5 zero-to-jupyterhub 4.0 upgrades the JupyterHub version from 4.1.6 to 5.2.1. :::{seealso} + For more detailed changes in JupyterHub, see JupyterHub's own documentation on upgrading to version 5: Especially if you use features like per-user subdomains or custom page templates. @@ -49,10 +55,12 @@ especially those that have the `{username}` or `{servername}` fields, those values are likely to change under the new scheme for some usernames. In particular, there are new fields that should make things easier: -- `{user_server}` combines the username and server name, and is equivalent to `{username}{servername}` in the old escape scheme -- `{pod_name}`, `{pvc_name}` +- `{user_server}` combines the username and server name, and is equivalent to `{username}{servername}` in the old escape scheme. + It is the recommended value when a string should be unique per named server, as opposed to per user. +- `{pod_name}`, `{pvc_name}` are now available to reference the fully resolved names of these objects + and can be used to avoid duplicating templates. -You can opt in to the kubespawner 6 behavior with: +You can opt in globally to keep the kubespawner 6 behavior with: ```yaml hub: @@ -63,23 +71,32 @@ hub: which _should_ result in no changes for you from previous behavior. -:::{seealso} +One user-facing place where a default template may require administrator action is if you are using: -- [KubeSpawner changelog](https://jupyterhub-kubespawner.readthedocs.io/en/latest/changelog.html) -- [KubeSpawner docs on templated fields](https://jupyterhub-kubespawner.readthedocs.io/en/latest/templates.html#fields) +```yaml +singleuser: + storage: + type: static +``` -::: +The default value for `subPath` is `{username}` which may resolve to a different value for some usernames, which could appear like a 'lost' home directory because the mount path changes. +The data is not lost, but the mount location has changed. +To ensure this value doesn't change, you can use: -## OAuthenticator 17 +```yaml +singleuser: + storage: + type: static + static: + subPath: "{escaped_username}" +``` -OAuthenticator is upgraded from 16.3.1 to 17.1. -The main changes are related to using group information from OAuth providers. -If you used or would like to use groups for authentication, -check out the [OAuthenticator changelog](https://oauthenticator.readthedocs.io/en/stable/reference/changelog.html) +which applies the previous 'escape' scheme to the subPath. +Alternatively, you can keep the new scheme, and perform a one-time migration to move files for the affected usernames. -## Other package upgrades +:::{seealso} -- Python is upgraded from 3.11 to 3.12 in the Hub image -- LDAPAuthenticator is upgraded from 1 to 2 ([changelog](https://github.com/jupyterhub/ldapauthenticator/blob/2.0.0/CHANGELOG.md#200---2024-10-18)) -- FirstUseAuthenticator is upgraded from 1.0 to 1.1 ([changelog](https://github.com/jupyterhub/firstuseauthenticator/blob/1.1.0/CHANGELOG.md)) -- idle culler is upgraded from 1.3.1 to 1.4.0 ([changelog](https://github.com/jupyterhub/jupyterhub-idle-culler/blob/1.4.0/CHANGELOG.md)) +- [KubeSpawner changelog](https://jupyterhub-kubespawner.readthedocs.io/en/latest/changelog.html) +- [KubeSpawner docs on templated fields](https://jupyterhub-kubespawner.readthedocs.io/en/latest/templates.html#fields) + +::: diff --git a/docs/source/changelog.md b/docs/source/changelog.md index 730039e5bf..d2b7e65f46 100644 --- a/docs/source/changelog.md +++ b/docs/source/changelog.md @@ -10,19 +10,27 @@ This Helm chart provides [development releases], and as we merge [breaking changes in pull requests], this list should be updated. [development releases]: https://hub.jupyter.org/helm-chart/#development-releases-jupyterhub + [breaking changes in pull requests]: https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pulls?q=is%3Apr+is%3Aclosed+label%3Abreaking +(changelog-4.0)= + ## 4.0 -### 4.0.0 - 2024-10 +### 4.0.0 - 2024-11 This release updates JupyterHub itself from version 4 to 5, and the dependencies `jupyterhub-kubespawner`, `oauthenticator`, and `ldapauthenticator` to a new major version. -See the [upgrade guide](upgrade-3-to-4) for specific instructions for upgrading chart version from 3 to 4, -and check the summary of breaking changes and the linked changelogs below -if you use any of the upgraded packages. +:::{seealso} + +- the [general upgrade documentation](upgrading-major-upgrades) for upgrade steps to take every time you do a major chart update +- the [upgrade guide](upgrade-3-to-4) for specific instructions for upgrading chart version from 3 to 4 +- check the summary of breaking changes and the linked changelogs below + if you use any of the upgraded packages. + +::: #### Breaking changes diff --git a/docs/source/conf.py b/docs/source/conf.py index 5ec97c8b03..d2b0c87e30 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -38,6 +38,7 @@ # ref: https://myst-parser.readthedocs.io/en/latest/configuration.html # myst_enable_extensions = [ + "colon_fence", "substitution", ]