Proxy API

Module: jupyterhub_traefik_proxy

Traefik implementation of the JupyterHub proxy API

TraefikProxy

class jupyterhub_traefik_proxy.TraefikProxy(**kwargs)[source]

JupyterHub Proxy implementation using traefik

async add_route(routespec, target, data)[source]

Add a route to the proxy.

Subclasses must define this method

Parameters
  • routespec (str) – A URL prefix ([host]/path/) for which this route will be matched, e.g. host.name/path/

  • target (str) – A full URL that will be the target of this route.

  • data (dict) – A JSONable dict that will be associated with this route, and will be returned when retrieving information about this route.

Will raise an appropriate Exception (FIXME: find what?) if the route could not be added.

The proxy implementation should also have a way to associate the fact that a route came from JupyterHub.

check_route_timeout c.TraefikProxy.check_route_timeout = Int(30)

Timeout (in seconds) when waiting for traefik to register an updated route.

check_route_timeout c.TraefikProxy.check_route_timeout = Int(30)

Timeout (in seconds) when waiting for traefik to register an updated route.

async delete_route(routespec)[source]

Delete a route with a given routespec if it exists.

Subclasses must define this method

extra_routes c.TraefikProxy.extra_routes = Dict()

Additional routes to be maintained in the proxy.

A dictionary with a route specification as key, and a URL as target. The hub will ensure this route is present in the proxy.

If the hub is running in host based mode (with JupyterHub.subdomain_host set), the routespec must have a domain component (example.com/my-url/). If the hub is not running in host based mode, the routespec must not have a domain component (/my-url/).

Helpful when the hub is running in API-only mode.

async get_all_routes()[source]

Fetch and return all the routes associated by JupyterHub from the proxy.

Subclasses must define this method

Should return a dictionary of routes, where the keys are routespecs and each value is a dict of the form:

{
  'routespec': the route specification ([host]/path/)
  'target': the target host URL (proto://host) for this route
  'data': the attached data dict for this route (as specified in add_route)
}
async get_route(routespec)[source]

Return the route info for a given routespec.

Parameters

routespec (str) – A URI that was used to add this route, e.g. host.tld/path/

Returns

dict with the following keys:

'routespec': The normalized route specification passed in to add_route
    ([host]/path/)
'target': The target host for this route (proto://host)
'data': The arbitrary data dict that was passed in by JupyterHub when adding this
        route.

None: if there are no routes matching the given routespec

Return type

result (dict)

should_start c.TraefikProxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

async start()[source]

Start the proxy.

Will be called during startup if should_start is True.

Subclasses must define this method if the proxy is to be started by the Hub

async stop()[source]

Stop the proxy.

Will be called during teardown if should_start is True.

Subclasses must define this method if the proxy is to be started by the Hub

toml_static_config_file c.TraefikProxy.toml_static_config_file = Unicode('traefik.toml')

traefik’s static configuration file

toml_static_config_file c.TraefikProxy.toml_static_config_file = Unicode('traefik.toml')

traefik’s static configuration file

traefik_api_password c.TraefikProxy.traefik_api_password = Unicode('')

The password for traefik api login

traefik_api_password c.TraefikProxy.traefik_api_password = Unicode('')

The password for traefik api login

traefik_api_url c.TraefikProxy.traefik_api_url = Unicode('http://127.0.0.1:8099')

traefik authenticated api endpoint url

traefik_api_url c.TraefikProxy.traefik_api_url = Unicode('http://127.0.0.1:8099')

traefik authenticated api endpoint url

traefik_api_username c.TraefikProxy.traefik_api_username = Unicode('')

The username for traefik api login

traefik_api_username c.TraefikProxy.traefik_api_username = Unicode('')

The username for traefik api login

traefik_api_validate_cert c.TraefikProxy.traefik_api_validate_cert = Bool(True)

validate SSL certificate of traefik api endpoint

traefik_api_validate_cert c.TraefikProxy.traefik_api_validate_cert = Bool(True)

validate SSL certificate of traefik api endpoint

traefik_log_level c.TraefikProxy.traefik_log_level = Unicode('ERROR')

traefik’s log level

traefik_log_level c.TraefikProxy.traefik_log_level = Unicode('ERROR')

traefik’s log level

TraefikTomlProxy

class jupyterhub_traefik_proxy.TraefikTomlProxy(**kwargs)[source]

JupyterHub Proxy implementation using traefik and toml config file

async add_route(routespec, target, data)[source]

Add a route to the proxy.

Subclasses must define this method

Parameters
  • routespec (str) – A URL prefix ([host]/path/) for which this route will be matched, e.g. host.name/path/

  • target (str) – A full URL that will be the target of this route.

  • data (dict) – A JSONable dict that will be associated with this route, and will be returned when retrieving information about this route.

Will raise an appropriate Exception (FIXME: find what?) if the route could not be added.

The proxy implementation should also have a way to associate the fact that a route came from JupyterHub.

check_route_timeout c.TraefikTomlProxy.check_route_timeout = Int(30)

Timeout (in seconds) when waiting for traefik to register an updated route.

async delete_route(routespec)[source]

Delete a route with a given routespec if it exists.

Subclasses must define this method

extra_routes c.TraefikTomlProxy.extra_routes = Dict()

Additional routes to be maintained in the proxy.

A dictionary with a route specification as key, and a URL as target. The hub will ensure this route is present in the proxy.

If the hub is running in host based mode (with JupyterHub.subdomain_host set), the routespec must have a domain component (example.com/my-url/). If the hub is not running in host based mode, the routespec must not have a domain component (/my-url/).

Helpful when the hub is running in API-only mode.

async get_all_routes()[source]

Fetch and return all the routes associated by JupyterHub from the proxy.

Subclasses must define this method

Should return a dictionary of routes, where the keys are routespecs and each value is a dict of the form:

{
  'routespec': the route specification ([host]/path/)
  'target': the target host URL (proto://host) for this route
  'data': the attached data dict for this route (as specified in add_route)
}
async get_route(routespec)[source]

Return the route info for a given routespec.

Parameters

routespec (str) – A URI that was used to add this route, e.g. host.tld/path/

Returns

dict with the following keys:

'routespec': The normalized route specification passed in to add_route
    ([host]/path/)
'target': The target host for this route (proto://host)
'data': The arbitrary data dict that was passed in by JupyterHub when adding this
        route.

None: if there are no routes matching the given routespec

Return type

result (dict)

should_start c.TraefikTomlProxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

async start()[source]

Start the proxy.

Will be called during startup if should_start is True.

Subclasses must define this method if the proxy is to be started by the Hub

async stop()[source]

Stop the proxy.

Will be called during teardown if should_start is True.

Subclasses must define this method if the proxy is to be started by the Hub

toml_dynamic_config_file c.TraefikTomlProxy.toml_dynamic_config_file = Unicode('rules.toml')

traefik’s dynamic configuration file

toml_dynamic_config_file c.TraefikTomlProxy.toml_dynamic_config_file = Unicode('rules.toml')

traefik’s dynamic configuration file

toml_static_config_file c.TraefikTomlProxy.toml_static_config_file = Unicode('traefik.toml')

traefik’s static configuration file

traefik_api_password c.TraefikTomlProxy.traefik_api_password = Unicode('')

The password for traefik api login

traefik_api_url c.TraefikTomlProxy.traefik_api_url = Unicode('http://127.0.0.1:8099')

traefik authenticated api endpoint url

traefik_api_username c.TraefikTomlProxy.traefik_api_username = Unicode('')

The username for traefik api login

traefik_api_validate_cert c.TraefikTomlProxy.traefik_api_validate_cert = Bool(True)

validate SSL certificate of traefik api endpoint

traefik_log_level c.TraefikTomlProxy.traefik_log_level = Unicode('ERROR')

traefik’s log level

TKvProxy

class jupyterhub_traefik_proxy.TKvProxy(**kwargs)[source]

JupyterHub Proxy implementation using traefik and a key-value store. Custom proxy implementations based on trafik and a key-value store can sublass TKvProxy.

async add_route(routespec, target, data)[source]

Add a route to the proxy.

Parameters
  • routespec (str) – A URL prefix ([host]/path/) for which this route will be matched, e.g. host.name/path/

  • target (str) – A full URL that will be the target of this route.

  • data (dict) – A JSONable dict that will be associated with this route, and will be returned when retrieving information about this route.

Will raise an appropriate Exception (FIXME: find what?) if the route could not be added.

This proxy implementation prefixes the routespec with proxy.jupyterhub_prefix when adding it to the kv store in orde to associate the fact that the route came from JupyterHub. Everything traefik related is prefixed with proxy.traefik_prefix.

check_route_timeout c.TKvProxy.check_route_timeout = Int(30)

Timeout (in seconds) when waiting for traefik to register an updated route.

async delete_route(routespec)[source]

Delete a route and all the traefik related info associated given a routespec, (if it exists).

extra_routes c.TKvProxy.extra_routes = Dict()

Additional routes to be maintained in the proxy.

A dictionary with a route specification as key, and a URL as target. The hub will ensure this route is present in the proxy.

If the hub is running in host based mode (with JupyterHub.subdomain_host set), the routespec must have a domain component (example.com/my-url/). If the hub is not running in host based mode, the routespec must not have a domain component (/my-url/).

Helpful when the hub is running in API-only mode.

async get_all_routes()[source]

Fetch and return all the routes associated by JupyterHub from the proxy.

Returns a dictionary of routes, where the keys are routespecs and each value is a dict of the form:

{
  'routespec': the route specification ([host]/path/)
  'target': the target host URL (proto://host) for this route
  'data': the attached data dict for this route (as specified in add_route)
}
async get_route(routespec)[source]

Return the route info for a given routespec.

Parameters

routespec (str) – A URI that was used to add this route, e.g. host.tld/path/

Returns

dict with the following keys:

'routespec': The normalized route specification passed in to add_route
    ([host]/path/)
'target': The target host for this route (proto://host)
'data': The arbitrary data dict that was passed in by JupyterHub when adding this
        route.

None: if there are no routes matching the given routespec

Return type

result (dict)

kv_jupyterhub_prefix c.TKvProxy.kv_jupyterhub_prefix = Unicode('')

The key value store key prefix for traefik dynamic configuration

kv_jupyterhub_prefix c.TKvProxy.kv_jupyterhub_prefix = Unicode('')

The key value store key prefix for traefik dynamic configuration

kv_password c.TKvProxy.kv_password = Unicode('')

The password for key value store login

kv_password c.TKvProxy.kv_password = Unicode('')

The password for key value store login

kv_traefik_prefix c.TKvProxy.kv_traefik_prefix = KVStorePrefix('')

The key value store key prefix for traefik static configuration

kv_traefik_prefix c.TKvProxy.kv_traefik_prefix = KVStorePrefix('')

The key value store key prefix for traefik static configuration

kv_url c.TKvProxy.kv_url = Unicode('')

The URL of the key value store server

kv_url c.TKvProxy.kv_url = Unicode('')

The URL of the key value store server

kv_username c.TKvProxy.kv_username = Unicode('')

The username for key value store login

kv_username c.TKvProxy.kv_username = Unicode('')

The username for key value store login

should_start c.TKvProxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

async start()[source]

Start the proxy. Will be called during startup if should_start is True.

async stop()[source]

Stop the proxy. Will be called during teardown if should_start is True.

toml_static_config_file c.TKvProxy.toml_static_config_file = Unicode('traefik.toml')

traefik’s static configuration file

traefik_api_password c.TKvProxy.traefik_api_password = Unicode('')

The password for traefik api login

traefik_api_url c.TKvProxy.traefik_api_url = Unicode('http://127.0.0.1:8099')

traefik authenticated api endpoint url

traefik_api_username c.TKvProxy.traefik_api_username = Unicode('')

The username for traefik api login

traefik_api_validate_cert c.TKvProxy.traefik_api_validate_cert = Bool(True)

validate SSL certificate of traefik api endpoint

traefik_log_level c.TKvProxy.traefik_log_level = Unicode('ERROR')

traefik’s log level

TraefikEtcdProxy

class jupyterhub_traefik_proxy.TraefikEtcdProxy(**kwargs)[source]

JupyterHub Proxy implementation using traefik and etcd

check_route_timeout c.TraefikEtcdProxy.check_route_timeout = Int(30)

Timeout (in seconds) when waiting for traefik to register an updated route.

etcd_client_ca_cert c.TraefikEtcdProxy.etcd_client_ca_cert = Unicode(None)

Etcd client root certificates

etcd_client_ca_cert c.TraefikEtcdProxy.etcd_client_ca_cert = Unicode(None)

Etcd client root certificates

etcd_client_cert_crt c.TraefikEtcdProxy.etcd_client_cert_crt = Unicode(None)

Etcd client certificate chain (etcd_client_cert_key must also be specified)

etcd_client_cert_crt c.TraefikEtcdProxy.etcd_client_cert_crt = Unicode(None)

Etcd client certificate chain (etcd_client_cert_key must also be specified)

etcd_client_cert_key c.TraefikEtcdProxy.etcd_client_cert_key = Unicode(None)

Etcd client private key (etcd_client_cert_crt must also be specified)

etcd_client_cert_key c.TraefikEtcdProxy.etcd_client_cert_key = Unicode(None)

Etcd client private key (etcd_client_cert_crt must also be specified)

extra_routes c.TraefikEtcdProxy.extra_routes = Dict()

Additional routes to be maintained in the proxy.

A dictionary with a route specification as key, and a URL as target. The hub will ensure this route is present in the proxy.

If the hub is running in host based mode (with JupyterHub.subdomain_host set), the routespec must have a domain component (example.com/my-url/). If the hub is not running in host based mode, the routespec must not have a domain component (/my-url/).

Helpful when the hub is running in API-only mode.

kv_jupyterhub_prefix c.TraefikEtcdProxy.kv_jupyterhub_prefix = Unicode('')

The key value store key prefix for traefik dynamic configuration

kv_password c.TraefikEtcdProxy.kv_password = Unicode('')

The password for key value store login

kv_traefik_prefix c.TraefikEtcdProxy.kv_traefik_prefix = KVStorePrefix('')

The key value store key prefix for traefik static configuration

kv_url c.TraefikEtcdProxy.kv_url = Unicode('')

The URL of the key value store server

kv_username c.TraefikEtcdProxy.kv_username = Unicode('')

The username for key value store login

should_start c.TraefikEtcdProxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

toml_static_config_file c.TraefikEtcdProxy.toml_static_config_file = Unicode('traefik.toml')

traefik’s static configuration file

traefik_api_password c.TraefikEtcdProxy.traefik_api_password = Unicode('')

The password for traefik api login

traefik_api_url c.TraefikEtcdProxy.traefik_api_url = Unicode('http://127.0.0.1:8099')

traefik authenticated api endpoint url

traefik_api_username c.TraefikEtcdProxy.traefik_api_username = Unicode('')

The username for traefik api login

traefik_api_validate_cert c.TraefikEtcdProxy.traefik_api_validate_cert = Bool(True)

validate SSL certificate of traefik api endpoint

traefik_log_level c.TraefikEtcdProxy.traefik_log_level = Unicode('ERROR')

traefik’s log level

TraefikConsulProxy

class jupyterhub_traefik_proxy.TraefikConsulProxy(**kwargs)[source]

JupyterHub Proxy implementation using traefik and Consul

check_route_timeout c.TraefikConsulProxy.check_route_timeout = Int(30)

Timeout (in seconds) when waiting for traefik to register an updated route.

consul_client_ca_cert c.TraefikConsulProxy.consul_client_ca_cert = Unicode(None)

Consul client root certificates

consul_client_ca_cert c.TraefikConsulProxy.consul_client_ca_cert = Unicode(None)

Consul client root certificates

extra_routes c.TraefikConsulProxy.extra_routes = Dict()

Additional routes to be maintained in the proxy.

A dictionary with a route specification as key, and a URL as target. The hub will ensure this route is present in the proxy.

If the hub is running in host based mode (with JupyterHub.subdomain_host set), the routespec must have a domain component (example.com/my-url/). If the hub is not running in host based mode, the routespec must not have a domain component (/my-url/).

Helpful when the hub is running in API-only mode.

kv_jupyterhub_prefix c.TraefikConsulProxy.kv_jupyterhub_prefix = Unicode('')

The key value store key prefix for traefik dynamic configuration

kv_password c.TraefikConsulProxy.kv_password = Unicode('')

The password for key value store login

kv_traefik_prefix c.TraefikConsulProxy.kv_traefik_prefix = KVStorePrefix('')

The key value store key prefix for traefik static configuration

kv_url c.TraefikConsulProxy.kv_url = Unicode('')

The URL of the key value store server

kv_username c.TraefikConsulProxy.kv_username = Unicode('')

The username for key value store login

should_start c.TraefikConsulProxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

async stop()[source]

Stop the proxy. Will be called during teardown if should_start is True.

toml_static_config_file c.TraefikConsulProxy.toml_static_config_file = Unicode('traefik.toml')

traefik’s static configuration file

traefik_api_password c.TraefikConsulProxy.traefik_api_password = Unicode('')

The password for traefik api login

traefik_api_url c.TraefikConsulProxy.traefik_api_url = Unicode('http://127.0.0.1:8099')

traefik authenticated api endpoint url

traefik_api_username c.TraefikConsulProxy.traefik_api_username = Unicode('')

The username for traefik api login

traefik_api_validate_cert c.TraefikConsulProxy.traefik_api_validate_cert = Bool(True)

validate SSL certificate of traefik api endpoint

traefik_log_level c.TraefikConsulProxy.traefik_log_level = Unicode('ERROR')

traefik’s log level