From f7f195cd8046a74650162560dbe249c8bf6d981e Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Thu, 14 Oct 2021 04:56:48 +0200 Subject: [PATCH] Misc README updates --- README.md | 47 ++++++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 953f74c..3621ee9 100644 --- a/README.md +++ b/README.md @@ -24,16 +24,17 @@ Prior to JupyterHub 2.0, the `jupyterhub-idle-culler` required full administrati in order to have sufficient permissions to stop servers on behalf of users. JupyterHub 2.0 introduces [scopes][] to allow for more fine-grained permission control. -This means that the cull-idle service does not need full administrative privileges anymore. +This means that the configured culler service does not need full administrative privileges anymore. It can be assigned only the permissions it needs. [scopes]: https://jupyterhub.readthedocs.io/en/latest/rbac/scopes.html#available-scopes `jupyterhub-idle-culler` requires the following scopes to function: +- `read:hub` - access to the hub's version information - `list:users` - access to the user list API, our source of information about who to cull - `read:users:activity` - read the last_activity field of the user -- `servers` - management of servers (this includes stopping servers and reading the server model) +- `delete:servers` - management of servers (this includes stopping servers) - `admin:users` (**optional**) - only needed if using `--cull-users` To assign the service the appropriate permissions, declare a role in your `jupyterhub_config.py`: @@ -41,7 +42,7 @@ To assign the service the appropriate permissions, declare a role in your `jupyt ```python c.JupyterHub.load_roles = [ { - "name": "cull-idle", + "name": "jupyterhub-idle-culler", "scopes": [ "read:hub", "list:users", @@ -49,7 +50,7 @@ c.JupyterHub.load_roles = [ "delete:servers", # "admin:users", # if using --cull-users ], - "services": ["idle-culler"], # assign our service to this role, so it has these permissions + "services": ["jupyterhub-idle-culler"], # assign the role's permission to this service } ] ``` @@ -62,57 +63,55 @@ Service to the `c.JupyterHub.services` list: ```python c.JupyterHub.services = [ { - 'name': 'idle-culler', - # 'admin': True, - 'command': [ + "name": "jupyterhub-idle-culler", + "command": [ sys.executable, - '-m', 'jupyterhub_idle_culler', - '--timeout=3600' + "-m", "jupyterhub_idle_culler", + "--timeout=3600", ], + # "admin": True, } ] ``` where: -- `'admin': True` indicates that the Service requires admin permissions so - it can shut down arbitrary user notebooks - (only for jupyterhub < 2.0; see [above][permissions]), and -- `'command'` indicates that the Service will be managed by the Hub. +- `"command"` indicates that the Service will be managed by the Hub, and +- `"admin": True` grants admin permissions to this Service and is only meant for + use with jupyterhub < 2.0; see [above][permissions]. ### As a standalone script `jupyterhub-idle-culler` can also be run as a standalone script. It can access the hub's api with a service token. -Register the service token with JupyterHub in jupyterhub_config.py: +Register the service token with JupyterHub in `jupyterhub_config.py`: ```python c.JupyterHub.services = [ { - 'name': 'idle-culler', - # 'admin': True, - 'api_token': '...', + "name": "jupyterhub-idle-culler", + "api_token": "...", + # "admin": True, } ] ``` where: -- `'admin': True` indicates that the Service requires admin permissions so - it can shut down arbitrary user notebooks - (only for jupyterhub < 2.0; see [above][permissions]), and -- `'api_token'` contains a secret token, e.g. generated by `openssl rand -hex 32` +- `'api_token'` contains a secret token, e.g. generated by `openssl rand -hex 32`, and +- `"admin": True` grants admin permissions to this Service and is only meant for + use with jupyterhub < 2.0; see [above][permissions]. and store the same token in a `JUPYTERHUB_API_TOKEN` environment variable. -Then start `jupyterhub-idle-culler` manually +Then start `jupyterhub-idle-culler` manually. ```bash export JUPYTERHUB_API_TOKEN=api_token_above... python3 -m jupyterhub-idle-culler [--timeout=900] [--url=http://localhost:8081/hub/api] ``` -The command line interface also gives a quick overview of the different options for configuration. +## Command line flags ``` --api-page-size Number of users to request per page, when @@ -124,6 +123,8 @@ The command line interface also gives a quick overview of the different options same time can slow down the Hub, so limit the number of API requests we have outstanding at any given time. (default 10) + --cull-admin-users Whether admin users should be culled (only + if --cull-users=true). (default True) --cull-every The interval (in seconds) for checking for idle servers to cull. (default 0) --cull-users Cull users in addition to servers. This is