mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-08 18:44:10 +00:00
4eaa7c5eb3
- suggest token page first - remove caveat about JupyterHub 0.8, which can be assumed now - undocument `jupyterhub token` - refresh token page screenshots, and remove duplicate screenshot of the token page - minor improvements to language in token page
150 lines
4.6 KiB
Markdown
150 lines
4.6 KiB
Markdown
# External services
|
|
|
|
When working with JupyterHub, a **Service** is defined as a process
|
|
that interacts with the Hub's REST API. A Service may perform a specific
|
|
action or task. For example, shutting down individuals' single user
|
|
notebook servers that have been idle for some time is a good example of
|
|
a task that could be automated by a Service. Let's look at how the
|
|
[jupyterhub_idle_culler][] script can be used as a Service.
|
|
|
|
## Real-world example to cull idle servers
|
|
|
|
JupyterHub has a REST API that can be used by external services. This
|
|
document will:
|
|
|
|
- explain some basic information about API tokens
|
|
- clarify that API tokens can be used to authenticate to
|
|
single-user servers as of [version 0.8.0](changelog)
|
|
- show how the [jupyterhub_idle_culler][] script can be:
|
|
- used in a Hub-managed service
|
|
- run as a standalone script
|
|
|
|
Both examples for `jupyterhub_idle_culler` will communicate tasks to the
|
|
Hub via the REST API.
|
|
|
|
## API Token basics
|
|
|
|
### Step 1: Generate an API token
|
|
|
|
To run such an external service, an API token must be created and
|
|
provided to the service.
|
|
|
|
As of [version 0.6.0](changelog), the preferred way of doing
|
|
this is to first generate an API token:
|
|
|
|
```bash
|
|
openssl rand -hex 32
|
|
```
|
|
|
|
In [version 0.8.0](changelog), a TOKEN request page for
|
|
generating an API token is available from the JupyterHub user interface:
|
|
|
|
|
|
|
|
|
|
|
|
### Step 2: Pass environment variable with token to the Hub
|
|
|
|
In the case of `cull_idle_servers`, it is passed as the environment
|
|
variable called `JUPYTERHUB_API_TOKEN`.
|
|
|
|
### Step 3: Use API tokens for services and tasks that require external access
|
|
|
|
While API tokens are often associated with a specific user, API tokens
|
|
can be used by services that require external access for activities
|
|
that may not correspond to a specific human, e.g. adding users during
|
|
setup for a tutorial or workshop. Add a service and its API token to the
|
|
JupyterHub configuration file, `jupyterhub_config.py`:
|
|
|
|
```python
|
|
c.JupyterHub.services = [
|
|
{'name': 'adding-users', 'api_token': 'super-secret-token'},
|
|
]
|
|
```
|
|
|
|
### Step 4: Restart JupyterHub
|
|
|
|
Upon restarting JupyterHub, you should see a message like below in the
|
|
logs:
|
|
|
|
```none
|
|
Adding API token for <username>
|
|
```
|
|
|
|
## Authenticating to single-user servers using API token
|
|
|
|
In JupyterHub 0.7, there is no mechanism for token authentication to
|
|
single-user servers, and only cookies can be used for authentication.
|
|
0.8 supports using JupyterHub API tokens to authenticate to single-user
|
|
servers.
|
|
|
|
## How to configure the idle culler to run as a Hub-Managed Service
|
|
|
|
### Step 1: Install the idle culler:
|
|
|
|
```
|
|
pip install jupyterhub-idle-culler
|
|
```
|
|
|
|
### Step 2: In `jupyterhub_config.py`, add the following dictionary for the `idle-culler` Service to the `c.JupyterHub.services` list:
|
|
|
|
```python
|
|
c.JupyterHub.services = [
|
|
{
|
|
'name': 'idle-culler',
|
|
'command': [sys.executable, '-m', 'jupyterhub_idle_culler', '--timeout=3600'],
|
|
}
|
|
]
|
|
|
|
c.JupyterHub.load_roles = [
|
|
{
|
|
"name": "list-and-cull", # name the role
|
|
"services": [
|
|
"idle-culler", # assign the service to this role
|
|
],
|
|
"scopes": [
|
|
# declare what permissions the service should have
|
|
"list:users", # list users
|
|
"read:users:activity", # read user last-activity
|
|
"admin:servers", # start/stop servers
|
|
],
|
|
}
|
|
]
|
|
```
|
|
|
|
where:
|
|
|
|
- `command` indicates that the Service will be launched as a
|
|
subprocess, managed by the Hub.
|
|
|
|
```{versionchanged} 2.0
|
|
Prior to 2.0, the idle-culler required 'admin' permissions.
|
|
It now needs the scopes:
|
|
|
|
- `list:users` to access the user list endpoint
|
|
- `read:users:activity` to read activity info
|
|
- `admin:servers` to start/stop servers
|
|
```
|
|
|
|
## How to run `cull-idle` manually as a standalone script
|
|
|
|
Now you can run your script by providing it
|
|
the API token and it will authenticate through the REST API to
|
|
interact with it.
|
|
|
|
This will run the idle culler service manually. It can be run as a standalone
|
|
script anywhere with access to the Hub, and will periodically check for idle
|
|
servers and shut them down via the Hub's REST API. In order to shutdown the
|
|
servers, the token given to `cull-idle` must have permission to list users
|
|
and admin their servers.
|
|
|
|
Generate an API token and store it in the `JUPYTERHUB_API_TOKEN` environment
|
|
variable. Run `jupyterhub_idle_culler` manually.
|
|
|
|
```bash
|
|
export JUPYTERHUB_API_TOKEN='token'
|
|
python -m jupyterhub_idle_culler [--timeout=900] [--url=http://127.0.0.1:8081/hub/api]
|
|
```
|
|
|
|
[jupyterhub_idle_culler]: https://github.com/jupyterhub/jupyterhub-idle-culler
|