From a22060ca7f2ea0cc6b3fe5d9c46a2c52c7bba12d Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Wed, 7 Sep 2016 11:39:15 -0700 Subject: [PATCH 1/3] Edit Services document --- docs/source/services.md | 121 +++++++++++++++++++++++++++------------- 1 file changed, 83 insertions(+), 38 deletions(-) diff --git a/docs/source/services.md b/docs/source/services.md index eafee5e9..ab10e011 100644 --- a/docs/source/services.md +++ b/docs/source/services.md @@ -1,33 +1,59 @@ -# JupyterHub services +# Services -JupyterHub 0.7 adds the notion of Services. -A Service is a process that interacts with the Hub REST API. -Services may perform actions such as shutting down user servers that have been idle for some time, -or registering additional web servers that should also use the Hub's authentication -and be served behind the Hub's proxy. -There are two main characteristics of services: +With version 0.7, JupyterHub adds support for 'Services'. -1. Is it **managed** by JupyterHub? -2. Does it have a web server that should be added to the proxy? -If a `command` is specified for launching the service, it will be started and managed by the Hub. -If a `url` is specified for where the service runs its own webserver, -it will be added to the Hub's proxy at `/service/:service-name`. +## JupyterHub's definition of a Service -## Managed 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 specialized action or +specific task. For example, each of these tasks can be a unique Service: -**Managed** services are services that the Hub starts and is responsible for. -These can only be local subprocesses of the Hub, -and the Hub will take care of starting these processes and restarting them if they stop. +- shutting down individuals' single user notebook servers that have been idle + for some time +- registering additional web servers which should use the Hub's authentication + and be served behind the Hub's proxy. -While there are similarities with notebook Spawners, -there are no plans to support the same spawning abstractions as notebook. -If you want to run these services in docker or other environments, -you can register it as an external service below. +Two main characteristics help define a Service: -A managed service is characterized by the `command` specified for launching the service. +1. Is the *Service* **managed** by JupyterHub? +2. Does the *Service* have a web server that should be added to the proxy's + table? +Currently, a Service may be either a 'Managed Service' which is managed by +JupyterHub, or an 'External Service' which runs its own web server and +communicates operation instructions via the Hub's API. + +### Properties of a Service + +If a `command` is specified for launching the Service, the Service will be +started and managed by the Hub. + +If a `url` is specified for where the Service runs its own web server, +JupyterHub will add the Service to the Hub's proxy at +`/service/:service-name`. + +## Managed Service + +If a Service is started by the Hub and the Hub is responsible for the +Service's actions, the Service is referred to as a **Managed Service** of +JupyterHub. Managed Services can only be a local subprocesses of the Hub. The +Hub will take care of starting these processes and restarting them if they +stop. + +While Managed Services share some similarities with notebook Spawners, +there are no plans for Managed Services to support the same spawning +abstractions as a notebook Spawner. If you wish to run Services in +Docker or other deployment environments, the Service can be registered as an +External Service, as described below. + +### Launching a Managed Service + +A Managed Service is characterized by its specified `command` for launching +the Service. For example, the configuration of a 'cull idle' notebook server +Managed Service would include the Service name, `True` setting for being +administered by the Hub, and the `command` to launch the Service: ```python c.JupyterHub.services = [ @@ -39,32 +65,50 @@ c.JupyterHub.services = [ ] ``` -In addition to `command`, managed services can take additional optional parameters, -to describe the environment in which to start the process: -- `env: dict` additional environment variables for the service. +In addition to the `command` to launch the Service, a Managed Service may also +be configured with additional optional parameters, which describe the +environment needed to start the process: + +- `env: dict` additional environment variables for the Service. - `user: str` name of the user to run the server as if different from the Hub. - Requires Hub to be root. -- `cwd: path` directory in which to run the service, if different from the Hub directory. + Requires Hub to be root. +- `cwd: path` directory in which to run the Service, if different from the + Hub directory. -When the service starts, the Hub will pass the following environment variables: +The Hub will pass the following environment variables to launch the Service: ``` -JUPYTERHUB_SERVICE_NAME: the name of the service ('cull-idle' above) +JUPYTERHUB_SERVICE_NAME: the name of the service +JUPYTERHUB_API_TOKEN: API token assigned to the service +JUPYTERHUB_API_URL: URL for the JupyterHub API (default, http://127.0.0.1:8080/hub/api) +JUPYTERHUB_BASE_URL: Base URL of the Hub (https://mydomain[:port]/) +JUPYTERHUB_SERVICE_PREFIX: URL path prefix of this service (/services/:service-name/) +``` + +For the previous example, these environment variables would be passed when +starting the 'cull idle' Service: + +``` +JUPYTERHUB_SERVICE_NAME: 'cull-idle' JUPYTERHUB_API_TOKEN: API token assigned to the service -JUPYTERHUB_API_URL: URL for the JupyterHub API (http://127.0.0.1:8080/hub/api) -JUPYTERHUB_BASE_URL: Base URL of the Hub (https://mydomain[:port]/) -JUPYTERHUB_SERVICE_PREFIX: URL path prefix of this service (/services/cull-idle/) +JUPYTERHUB_API_URL: http://127.0.0.1:8080/hub/api +JUPYTERHUB_BASE_URL: https://mydomain[:port] +JUPYTERHUB_SERVICE_PREFIX: /services/cull-idle/ ``` -## External services +## External Services -You can use your own service management tools, such as docker or systemd, to manage JupyterHub services. -These are not subprocesses of the Hub, and you must tell JupyterHub what API token the service is using to perform its API requests. -Each service will need a unique API token because the Hub authenticates each API request, -identifying the originating service or user. +To meet your specific use case needs, you may use your own Service management +tools, such as Docker or systemd, to manage a JupyterHub Service. +These External Services, unlike Managed Services, are not subprocesses of +the Hub. You must tell JupyterHub which API token the External Service is +using to perform its API requests. Each External Service will need a unique +API token because the Hub authenticates each API request and the API token is +used to identify the originating Service or user. -An example of an externally managed service with admin access and running its own web server: +An example of an externally managed service with admin access and running its +own web server: ```python c.JupyterHub.services = [ @@ -85,4 +129,5 @@ TODO TODO -JupyterHub 0.7 introduces some utiltiies for you to use that allow you to use the Hub's authentication mechanism. \ No newline at end of file +JupyterHub 0.7 introduces some utilities to use the Hub's authentication +mechanism. \ No newline at end of file From 0000b7447a34356f409579d18e196515c677e3fa Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Wed, 7 Sep 2016 13:52:33 -0700 Subject: [PATCH 2/3] Make command consistent with examples/cull-idle --- docs/source/services.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/services.md b/docs/source/services.md index ab10e011..f7c3457d 100644 --- a/docs/source/services.md +++ b/docs/source/services.md @@ -53,14 +53,15 @@ External Service, as described below. A Managed Service is characterized by its specified `command` for launching the Service. For example, the configuration of a 'cull idle' notebook server Managed Service would include the Service name, `True` setting for being -administered by the Hub, and the `command` to launch the Service: +administered by the Hub, and the `command` to launch the Service which will +cull idle servers after a timeout interval: ```python c.JupyterHub.services = [ { 'name': 'cull-idle', 'admin': True, - 'command': ['python', '/path/to/cull-idle.py', '--interval'] + 'command': ['python', '/path/to/cull-idle.py', '--timeout'] } ] ``` From 491b7e7d1164b09bde95b0e0b0ca50b32a9ec208 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Thu, 8 Sep 2016 08:23:47 -0700 Subject: [PATCH 3/3] Use Hub-Managed and Externally-Managed --- docs/source/services.md | 42 ++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/source/services.md b/docs/source/services.md index f7c3457d..6190bed0 100644 --- a/docs/source/services.md +++ b/docs/source/services.md @@ -21,8 +21,8 @@ Two main characteristics help define a Service: 2. Does the *Service* have a web server that should be added to the proxy's table? -Currently, a Service may be either a 'Managed Service' which is managed by -JupyterHub, or an 'External Service' which runs its own web server and +Currently, a Service may be either a 'Hub-Managed Service' which is managed by +JupyterHub, or an 'Externally-Managed Service' which runs its own web server and communicates operation instructions via the Hub's API. ### Properties of a Service @@ -34,27 +34,27 @@ If a `url` is specified for where the Service runs its own web server, JupyterHub will add the Service to the Hub's proxy at `/service/:service-name`. -## Managed Service +## Hub-Managed Service If a Service is started by the Hub and the Hub is responsible for the -Service's actions, the Service is referred to as a **Managed Service** of -JupyterHub. Managed Services can only be a local subprocesses of the Hub. The +Service's actions, the Service is referred to as a **Hub-Managed Service** of +JupyterHub. Hub-Managed Services can only be a local subprocesses of the Hub. The Hub will take care of starting these processes and restarting them if they stop. -While Managed Services share some similarities with notebook Spawners, -there are no plans for Managed Services to support the same spawning +While Hub-Managed Services share some similarities with notebook Spawners, +there are no plans for Hub-Managed Services to support the same spawning abstractions as a notebook Spawner. If you wish to run Services in Docker or other deployment environments, the Service can be registered as an -External Service, as described below. +Externally-Managed Service, as described below. -### Launching a Managed Service +### Launching a Hub-Managed Service -A Managed Service is characterized by its specified `command` for launching +A Hub-Managed Service is characterized by its specified `command` for launching the Service. For example, the configuration of a 'cull idle' notebook server -Managed Service would include the Service name, `True` setting for being -administered by the Hub, and the `command` to launch the Service which will -cull idle servers after a timeout interval: +Hub-Managed Service would include the Service name, admin permissions, and the +`command` to launch the Service which will cull idle servers after a timeout +interval: ```python c.JupyterHub.services = [ @@ -67,7 +67,7 @@ c.JupyterHub.services = [ ``` -In addition to the `command` to launch the Service, a Managed Service may also +In addition to the `command` to launch the Service, a Hub-Managed Service may also be configured with additional optional parameters, which describe the environment needed to start the process: @@ -98,18 +98,18 @@ JUPYTERHUB_BASE_URL: https://mydomain[:port] JUPYTERHUB_SERVICE_PREFIX: /services/cull-idle/ ``` -## External Services +## Externally-Managed Services -To meet your specific use case needs, you may use your own Service management +To meet your specific use case needs, you may use your own service management tools, such as Docker or systemd, to manage a JupyterHub Service. -These External Services, unlike Managed Services, are not subprocesses of -the Hub. You must tell JupyterHub which API token the External Service is -using to perform its API requests. Each External Service will need a unique +These Externally-Managed Services, unlike Hub-Managed Services, are not subprocesses of +the Hub. You must tell JupyterHub which API token the Externally-Managed Service is +using to perform its API requests. Each Externally-Managed Service will need a unique API token because the Hub authenticates each API request and the API token is used to identify the originating Service or user. -An example of an externally managed service with admin access and running its -own web server: +A configuration example of an Externally-Managed Service with admin access and running its +own web server is: ```python c.JupyterHub.services = [