Services#

Module: jupyterhub.services.service#

A service is a process that talks to JupyterHub.

Types of services:
Managed:

  • managed by JupyterHub (always subprocess, no custom Spawners)

  • always a long-running process

  • managed services are restarted automatically if they exit unexpectedly

Unmanaged:

  • managed by external service (docker, systemd, etc.)

  • do not need to be long-running processes, or processes at all

URL: needs a route added to the proxy.

  • Public route will always be /services/service-name

  • url specified in config

  • if port is 0, Hub will select a port

API access:

  • admin: tokens will have admin-access to the API

  • not admin: tokens will only have non-admin access (not much they can do other than defer to Hub for auth)

An externally managed service running on a URL:

{
    'name': 'my-service',
    'url': 'https://host:8888',
    'admin': True,
    'api_token': 'super-secret',
}

A hub-managed service with no URL:

{
    'name': 'cull-idle',
    'command': ['python', '/path/to/cull-idle']
    'admin': True,
}

Service#

class jupyterhub.services.service.Service(**kwargs: Any)#

An object wrapping a service specification for Hub API consumers.

A service has inputs:

  • name: str

    the name of the service

  • admin: bool(False)

    whether the service should have administrative privileges

  • url: str (None)

    The URL where the service is/should be. If specified, the service will be added to the proxy at /services/:name

  • oauth_no_confirm: bool(False)

    Whether this service should be allowed to complete oauth with logged-in users without prompting for confirmation.

If a service is to be managed by the Hub, it has a few extra options:

  • command: (str/Popen list)

    Command for JupyterHub to spawn the service. Only use this if the service should be a subprocess. If command is not specified, it is assumed to be managed by a

  • environment: dict

    Additional environment variables for the service.

  • user: str

    The name of a system user to become. If unspecified, run as the same user as the Hub.

admin Bool(False)#

Does the service need admin-access to the Hub API?

api_token Unicode('')#

The API token to use for the service.

If unspecified, an API token will be generated for managed services.

command Command()#

Command to spawn this service, if managed.

cwd Unicode('')#

The working directory in which to run the service.

environment Dict()#

Environment variables to pass to the service. Only used if the Hub is spawning the service.

property kind#

The name of the kind of service as a string

  • ‘managed’ for managed services

  • ‘external’ for external services

property managed#

Am I managed by the Hub?

name Unicode('')#

The name of the service.

If the service has an http endpoint, it

oauth_client_id Unicode('')#

OAuth client ID for this service.

You shouldn’t generally need to change this. Default: service-<name>

url Unicode('')#

URL of the service.

Only specify if the service runs an HTTP(s) endpoint that. If managed, will be passed as JUPYTERHUB_SERVICE_URL env.

user Unicode('')#

The user to become when launching the service.

If unspecified, run the service as the same user as the Hub.