Using TraefikEtcdProxy#
Warning
While it works today (2024), there does not appear to be a maintained, documented Python client for the etcd API. We will keep an eye on etcd API clients, but in the meantime we recommend using redis as the backend.
Etcd is a distributed key-value store. With it, you can use JupyterHub with distributed instances of traefik, e.g. multiple replicas in kubernetes.
See also
How-To install TraefikEtcdProxy#
Install jupyterhub
Install jupyterhub-traefik-proxy
Install traefik
Install etcd
You can find the full installation guide and examples in the installation section
How-To enable TraefikEtcdProxy#
You can enable JupyterHub to work with TraefikEtcdProxy
in jupyterhub_config.py,
using the proxy_class
configuration option.
You can choose to:
use the
traefik_etcd
entrypoint, new in JupyterHub 1.0, e.g.:c.JupyterHub.proxy_class = "traefik_etcd"
use the TraefikEtcdProxy object, in which case, you have to import the module, e.g.:
from jupyterhub_traefik_proxy import TraefikEtcdProxy c.JupyterHub.proxy_class = TraefikEtcdProxy
Etcd configuration#
Depending on the value of the
should_start
proxy flag, you can choose whether or not TraefikEtcdProxy willl be externally managed.When should_start is set to True, TraefikEtcdProxy will auto-generate its static configuration (using the override values or the defaults) and store it in
traefik.toml
file. The traefik process will then be launched using this file.When should_start is set to False, prior to starting the traefik process, you must create a toml file with the desired traefik static configuration and pass it to traefik. Keep in mind that in order for the routes to be stored in etcd, this toml file must specify etcd as the provider.
TraefikEtcdProxy searches in the etcd key-value store the keys starting with the kv_traefik_prefix prefix in order to build its static configuration.
Similarly, the dynamic configuration is built by searching the kv_jupyterhub_prefix.
Note
If you want to change or add traefik’s static configuration options, you can add them to etcd under this prefix and traefik will pick them up.
The default values of this configurations options are:
kv_traefik_prefix = "/traefik/" kv_jupyterhub_prefix = "/jupyterhub/"
You can override the default values of the prefixes by passing their desired values through
jupyterhub_config.py
e.g.:c.TraefikEtcdProxy.kv_traefik_prefix = "/some_static_config_prefix/" c.TraefikEtcdProxy.kv_jupyterhub_prefix = "/some_dynamic_config_prefix/"
By default, TraefikEtcdProxy assumes etcd accepts client requests on the official default etcd port
2379
for client requests.c.TraefikEtcdProxy.etcd_url = "http://127.0.0.1:2379"
If the etcd cluster is deployed differently than using the etcd defaults, then you must pass the etcd url to the proxy using the
etcd_url
option in jupyterhub_config.py:c.TraefikEtcdProxy.etcd_url = "scheme://hostname:port"
Note
TraefikEtcdProxy does not manage the etcd cluster and assumes it is up and running before the proxy itself starts.
However, based on how etcd is configured and started, TraefikEtcdProxy needs to be told about some etcd configuration details, such as:
etcd address where it accepts client requests
c.TraefikEtcdProxy.etcd_url="scheme://hostname:port"
etcd credentials (if etcd has authentication enabled)
c.TraefikEtcdProxy.etcd_username="abc" c.TraefikEtcdProxy.etcd_password="123"
Etcd has two API versions: the API V3 and the API V2. Traefik suggests using Etcd API V3, because the API V2 won’t be supported in the future.
Checkout the etcd documentation to find out more about possible etcd configuration options.
Externally managed TraefikEtcdProxy#
If TraefikEtcdProxy is used as an externally managed service, then make sure you follow the steps enumerated below:
Let JupyterHub know that the proxy being used is TraefikEtcdProxy, using the proxy_class configuration option:
c.JupyterHub.proxy_class = "traefik_etcd"
Configure
TraefikEtcdProxy
in jupyterhub_config.pyJupyterHub configuration file, jupyterhub_config.py must specify at least:
That the proxy is externally managed
The traefik api credentials
The etcd credentials (if etcd authentication is enabled)
Example configuration:
# JupyterHub shouldn't start the proxy, it's already running c.TraefikEtcdProxy.should_start = False # if not the default: c.TraefikEtcdProxy.etcd_url = "http://etcd-host:2379" # traefik api credentials c.TraefikEtcdProxy.traefik_api_username = "abc" c.TraefikEtcdProxy.traefik_api_password = "123" # etcd credentials c.TraefikEtcdProxy.etcd_username = "def" c.TraefikEtcdProxy.etcd_password = "456"
Create a toml file with traefik’s desired static configuration
Before starting the traefik process, you must create a toml file with the desired traefik static configuration and pass it to traefik when you launch the process. Keep in mind that in order for the routes to be stored in etcd, this toml file must specify etcd as the provider/
Keep in mind that the static configuration must configure at least:
The default entrypoint
The api entrypoint
The etcd provider
Example:
[api] [entryPoints.http] address = "127.0.0.1:8000" [entryPoints.auth_api] address = "127.0.0.1:8099" [providers.etcd] endpoints = [ "127.0.0.1:2379",] rootKey = "traefik"
Note
If you choose to enable the authentication on etcd, you can use this toml file to pass the credentials to traefik, e.g.:
```toml [providers.etcd] username = "root" password = "admin" ... ```
Example setup#
This is an example setup for using JupyterHub and TraefikEtcdProxy managed by another service than JupyterHub.
Configure the proxy through the JupyterHub configuration file, jupyterhub_config.py, e.g.:
# mark the proxy as externally managed c.TraefikEtcdProxy.should_start = False # traefik api endpoint login password c.TraefikEtcdProxy.traefik_api_password = "abc" # traefik api endpoint login username c.TraefikEtcdProxy.traefik_api_username = "123" # etcd url where it accepts client requests c.TraefikEtcdProxy.etcd_url = "http://127.0.0.1:2379" # configure JupyterHub to use TraefikEtcdProxy c.JupyterHub.proxy_class = "traefik_etcd"
Note
If you intend to enable authentication on etcd, add the etcd credentials to jupyterhub_config.py:
# etcd username c.TraefikEtcdProxy.etcd_username = "def" # etcd password c.TraefikEtcdProxy.etcd_password = "456"
Start a single-note etcd cluster on the default port on localhost. e.g.:
$ etcd
Note
If you intend to enable authentication on etcd checkout this guide.
Create a traefik static configuration file, traefik.toml, e.g:.
# enable the api [api] # the public port where traefik accepts http requests [entryPoints.http] address = ":8000" # the port on localhost where the traefik api should be found [entryPoints.auth_api] address = "localhost:8099" [providers.etcd] # the etcd username (if auth is enabled) username = "def" # the etcd password (if auth is enabled) password = "456" # the etcd address endpoints = ["127.0.0.1:2379"] # the prefix to use for the static configuration rootKey = "traefik"
Start traefik with the configuration specified above, e.g.:
$ traefik -c traefik.toml