Merge pull request #2528 from consideRatio/pr/add-changelog-for-2.0.0

docs: add changelog for 2.0.0 (beta.1)

Author: consideRatio

docs/source/administrator/upgrading/upgrade-1-to-2.md

@@ -3,6 +3,8 @@
 Z2JH 2 contains several breaking changes, including some that affect the security of your deployment.
 This guide will help you upgrade from 1.\* to 2.\*.
 
+(upgrade-1-2-security-breaking-change)=
+
 ## Security: breaking change to `*.networkPolicy.egress`
 
 NetworkPolicy egress rules have been extended with a new property.
@@ -47,23 +49,29 @@ and the configuration reference entries under
 
 ## JupyterHub 2 and related hub components
 
-Z2JH 2.0.0 upgrades JupyterHub to the 2.\* series, and also upgrades all hub components.
+Z2JH 2.0.0 upgrades from JupyterHub 1 directly to JupyterHub 3, and also upgrades all hub components.
 If you are using any custom JupyterHub services, addons, API integrations, or extra configuration, you should review the breaking changes in the
-[JupyterHub 2.0.0 changelog](https://github.com/jupyterhub/jupyterhub/blob/2.3.1/docs/source/changelog.md#200).
+major releases of JupyterHub 2 and 3 in the [JupyterHub changelog](https://jupyterhub.readthedocs.io/en/latest/changelog.html).
 
-JupyterHub 2 uses an updated database schema.
-Z2JH 2.0.0 automatically handles the upgrade for SQLite databases (the default), but if you use an external database you need to configure [`hub.db.upgrade`](schema_hub.db.upgrade) to true when upgrading. It will not be possible to downgrade to older releases after this without also using a backup or resetting the database.
+JupyterHub 2 and 3 updates the database schema, which means a migration takes place when you upgrade JupyterHub.
+Z2JH automatically handles the upgrade if you are using sqlite (`hub.db.type = 'sqlite-pvc'`, the default), but it may not be possible to downgrade to older releases after this.
+When using sqlite, JupyterHub automatically creates a backup in the `hub-db` volume,
+which can be restored manually if you need to downgrade.
+If you use an external database you need to configure [`hub.db.upgrade`](schema_hub.db.upgrade) to `true` when upgrading.
 
 JupyterHub 2 adds RBAC for managing permissions in JupyterHub.
-The old permissions model of admin/non-admin still works but you should use
-[RBAC to assign the required privileges to users or services in future](https://jupyterhub.readthedocs.io/en/stable/rbac/index.html)
+The old permissions model of admin/non-admin still works, but we recommend using [RBAC to assign only the required privileges to users or services in future](https://jupyterhub.readthedocs.io/en/stable/rbac/index.html).
+Default permissions are mostly unchanged, but a few have:
+
+- Servers' own API tokens have limited permissions by default, which can be expanded by defining the `server` role. The previous behavior was the maximum permission of `inherit`.
+- `admin_access` as a concept is removed, so disabling it has no effect. In 2.0, admins by definition can do everything, including access servers. To limit user permissions, assign them to roles which have only the needed permissions.
 
 KubeSpawner has replaced the [`kubernetes`] library with [`kubernetes_asyncio`](https://github.com/tomplus/kubernetes_asyncio).
 If you have extended the JupyterHub image and you rely on the kubernetes library you will need to modify your extensions.
 
 See
-`TODO: link to Notable dependencies updated`
-in the changelog for more information on other upgraded hub components.
+[Notable dependencies updated](notable-dependencies-200)
+for more information on other upgraded hub components.
 
 ## JupyterLab and Jupyter Server
 
@@ -81,6 +89,16 @@ singleuser:
   allowPrivilegeEscalation: true
 ```
 
+If you want to add custom arguments to the command, you must specify the full command and any arguments in `singleuser.cmd`, for example:
+
+```yaml
+singleuser:
+  cmd:
+    - jupyterhub-singleuser
+    - "--collaborative"
+    - "--debug"
+```
+
 ## Configuration in `jupyterhub_config.d` has a higher priority than `hub.config` [#2457](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pull/2457)
 
 Previously if `hub.config` was used to configure some JupyterHub traitlets it would override any custom configuration files mounted into `jupyterhub_config.d` in the hub container.