Traefik v2 file provider

README.md

@@ -19,7 +19,7 @@ depending on how traefik store its routing configuration.
 
 For **smaller**, single-node deployments:
 
-* TraefikTomlProxy
+* TraefikFileProxy
 
 For **distributed** setups:
 
@@ -32,7 +32,7 @@ The [documentation](https://jupyterhub-traefik-proxy.readthedocs.io) contains a
 guide](https://jupyterhub-traefik-proxy.readthedocs.io/en/latest/install.html)
 with examples for the three different implementations.
 
-* [For TraefikTomlProxy](https://jupyterhub-traefik-proxy.readthedocs.io/en/latest/toml.html#example-setup)
+* [For TraefikFileProxy](https://jupyterhub-traefik-proxy.readthedocs.io/en/latest/file.html#example-setup)
 * [For TraefikEtcdProxy](https://jupyterhub-traefik-proxy.readthedocs.io/en/latest/etcd.html#example-setup)
 * [For TraefikConsulProxy](https://jupyterhub-traefik-proxy.readthedocs.io/en/latest/consul.html#example-setup)
 

docs/source/api/index.rst

@@ -15,10 +15,10 @@ Module: :mod:`jupyterhub_traefik_proxy`
 .. autoconfigurable:: TraefikProxy
     :members:
 
-:class:`TraefikTomlProxy`
+:class:`TraefikFileProxy`
 -------------------------
 
-.. autoconfigurable:: TraefikTomlProxy
+.. autoconfigurable:: TraefikFileProxy
     :members:
 
 :class:`TKvProxy`

docs/source/file.md

@@ -0,0 +1,194 @@
+# Using TraefikFileProxy
+
+**jupyterhub-traefik-proxy** can be used with simple toml or yaml configuration files, for smaller, single-node deployments such as
+[The Littlest JupyterHub](https://tljh.jupyter.org).
+
+## How-To install TraefikFileProxy
+
+1. Install **jupyterhub**
+2. Install **jupyterhub-traefik-proxy**
+3. Install **traefik**
+
+* You can find the full installation guide and examples in the [Introduction section](install.html#traefik-proxy-installation)
+
+## How-To enable TraefikFileProxy
+
+You can enable JupyterHub to work with `TraefikFileProxy` in jupyterhub_config.py, using the `proxy_class` configuration option.
+
+You can choose to:
+
+* use the `traefik_file` entrypoint, new in JupyterHub 1.0, e.g.:
+
+    ```python
+    c.JupyterHub.proxy_class = "traefik_file"
+    ```
+
+* use the TraefikFileProxy object, in which case, you have to import the module, e.g.:
+
+    ```python
+    from jupyterhub_traefik_proxy import TraefikFileProxy
+    c.JupyterHub.proxy_class = TraefikFileProxy
+    ```
+
+
+## Traefik configuration
+
+Traefik's configuration is divided into two parts:
+
+* The **static** configuration (loaded only at the beginning)
+* The **dynamic** configuration (can be hot-reloaded, without restarting the proxy), 
+where the routing table will be updated continuously.
+
+Traefik allows us to have one file for the static configuration file (`traefik.toml` or `traefik.yaml`) and one or several files for the routes, that traefik would watch.
+
+```{note}
+  **TraefikFileProxy**, uses two configuration files: one file for the routes (**rules.toml** or **rules.yaml**), and one for the static configuration (**traefik.toml** or **traefik.yaml**).
+```
+
+
+By **default**, Traefik will search for `traefik.toml` and `rules.toml` in the following places:
+
+* /etc/traefik/
+* $HOME/.traefik/
+* . the working directory
+
+You can override this in TraefikFileProxy, by modifying the **toml_static_config_file** argument:
+
+```python
+c.TraefikFileProxy.static_config_file="/path/to/static_config_filename.toml"
+```
+
+Similarly, you can override the dynamic configuration file by modifying the **dynamic_config_file** argument:
+
+```python
+c.TraefikFileProxy.dynamic_config_file="/path/to/dynamic_config_filename.toml"
+```
+
+```{note}
+
+* **When JupyterHub starts the proxy**, it writes the static config once, then only edits the dynamic config file. 
+
+* **When JupyterHub does not start the proxy**, the user is totally responsible for the static config and 
+JupyterHub is responsible exclusively for the routes.
+
+* **When JupyterHub does not start the proxy**, the user should tell `traefik` to get its dynamic configuration
+from a directory. Then, one (or more) dynamic configuration file(s) can be managed externally, and `dynamic_config_file`
+will be managed by JupyterHub. This allows e.g., the administrator to configure traefik's API outside of JupyterHub.
+
+```
+
+## Externally managed TraefikFileProxy
+
+When TraefikFileProxy is externally managed, service managers like [systemd](https://www.freedesktop.org/wiki/Software/systemd/)
+or [docker](https://www.docker.com/) will be responsible for starting and stopping the proxy.
+
+If TraefikFileProxy is used as an externally managed service, then make sure you follow the steps enumerated below:
+
+1. Let JupyterHub know that the proxy being used is TraefikFileProxy, using the *proxy_class* configuration option:
+    ```python
+    from jupyterhub_traefik_proxy import TraefikFileProxy
+    c.JupyterHub.proxy_class = TraefikFileProxy
+    ```
+
+2. Configure `TraefikFileProxy` in **jupyterhub_config.py**
+
+   JupyterHub configuration file, *jupyterhub_config.py* must specify at least:
+   * That the proxy is externally managed
+   * The traefik api credentials
+   * The dynamic configuration file, 
+     if different from *rules.toml* or if this file is located 
+     in another place than traefik's default search directories (etc/traefik/, $HOME/.traefik/, the working directory)
+
+    Example configuration:
+    ```python
+    # JupyterHub shouldn't start the proxy, it's already running
+    c.TraefikFileProxy.should_start = False
+
+    # if not the default:
+    c.TraefikFileProxy.dynamic_config_file = "/path/to/somefile.toml"
+
+    # traefik api credentials
+    c.TraefikFileProxy.traefik_api_username = "abc"
+    c.TraefikFileProxy.traefik_api_password = "xxx"
+    ```
+
+3. Ensure **traefik.toml** / **traefik.yaml**
+
+   The static configuration file, *traefik.toml* (or **traefik.yaml**) must configure at least:
+   * The default entrypoint
+   * The api entrypoint (*and authenticate it in a user-managed dynamic configuration file*)
+   * The websockets protocol
+   * The dynamic configuration directory to watch
+    (*make sure this configuration directory exists, even if empty before the proxy is launched*)
+   * Check `tests/config_files/traefik.toml` for an example.
+
+## Example setup
+
+This is an example setup for using JupyterHub and TraefikFileProxy managed by another service than JupyterHub.
+
+1. Configure the proxy through the JupyterHub configuration file, *jupyterhub_config.py*, e.g.:
+
+   ```python
+   from jupyterhub_traefik_proxy import TraefikFileProxy
+
+   # mark the proxy as externally managed
+   c.TraefikFileProxy.should_start = False
+
+   # traefik api endpoint login password
+   c.TraefikFileProxy.traefik_api_password = "admin"
+
+   # traefik api endpoint login username
+   c.TraefikFileProxy.traefik_api_username = "api_admin"
+
+   # traefik's dynamic configuration file, which will be managed by JupyterHub
+   c.TraefikFileProxy.dynamic_config_file = "/var/run/traefik/rules.toml"
+
+   # configure JupyterHub to use TraefikFileProxy
+   c.JupyterHub.proxy_class = TraefikFileProxy
+    ```
+
+2. Create a traefik static configuration file, *traefik.toml*, e.g.:
+
+    ```
+    # the api entrypoint
+    [api]
+    dashboard = true
+
+    # websockets protocol
+    [wss]
+    protocol = "http"
+
+    # the port on localhost where traefik accepts http requests
+    [entryPoints.web]
+    address = ":8000"
+
+    # the port on localhost where the traefik api and dashboard can be found
+    [entryPoints.enter_api]
+    address = ":8099"
+
+    # the dynamic configuration directory
+    # This must match the directory provided in Step 1. above.
+    [providers.file]
+    directory = "/var/run/traefik"
+    watch = true
+   ```
+
+3. Create a traefik dynamic configuration file in the directory provided in the dynamic configuration above, to provide the api authentication parameters, e.g.
+
+    ```
+    # Router configuration for the api service
+    [http.routers.router-api]
+    rule = "Host(`localhost`) && PathPrefix(`/api`)"
+    entryPoints = ["enter_api"]
+    service = "api@internal"
+    middlewares = ["auth_api"]
+
+    # authenticate the traefik api entrypoint
+    [http.middlewares.auth_api.basicAuth]
+    users = [ "api_admin:$apr1$eS/j3kum$q/X2khsIEG/bBGsteP.x./",]
+    ```
+
+4. Start traefik with the configuration specified above, e.g.:
+    ```bash
+    $ traefik --configfile traefik.toml
+    ```

docs/source/index.rst

@@ -20,7 +20,7 @@ Moreover it offers *HTTPS* support through a straight-forward `ACME (Let's Encry
 There are three versions for the proxy, depending on how traefik stores the routes:
 
 * *for* **smaller**, *single-node deployments*:
-   * TraefikTomlProxy
+   * TraefikFileProxy
 * *for* **distributed** *setups*:
    * TraefikEtcdProxy
    * TraefikConsulProxy
@@ -39,7 +39,7 @@ Getting Started
 .. toctree::
    :maxdepth: 1
 
-   toml
+   fileprovider
    etcd
    consul
 

docs/source/install.md

@@ -69,7 +69,7 @@
 ## Enabling traefik-proxy in JupyterHub
 
 
-[TraefikTomlProxy](https://github.com/jupyterhub/traefik-proxy/blob/master/jupyterhub_traefik_proxy/toml.py), [TraefikEtcdProxy](https://github.com/jupyterhub/traefik-proxy/blob/master/jupyterhub_traefik_proxy/etcd.py) and [TraefikConsulProxy](https://github.com/jupyterhub/traefik-proxy/blob/master/jupyterhub_traefik_proxy/consul.py)  are custom proxy implementations that subclass [Proxy](https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/proxy.py) and can register in JupyterHub config using `c.JupyterHub.proxy_class` entrypoint.
+[TraefikFileProxy](https://github.com/jupyterhub/traefik-proxy/blob/traefik-v2/jupyterhub_traefik_proxy/fileprovider.py), [TraefikEtcdProxy](https://github.com/jupyterhub/traefik-proxy/blob/traefik-v2/jupyterhub_traefik_proxy/etcd.py) and [TraefikConsulProxy](https://github.com/jupyterhub/traefik-proxy/blob/traefik-v2/jupyterhub_traefik_proxy/consul.py)  are custom proxy implementations that subclass [Proxy](https://github.com/jupyterhub/jupyterhub/blob/traefik-v2/jupyterhub/proxy.py) and can register in JupyterHub config using `c.JupyterHub.proxy_class` entrypoint.
 
 On startup, JupyterHub will look by default for a configuration file, *jupyterhub_config.py*, in the current working directory. If the configuration file is not in the current working directory,
 you can load a specific config file and start JupyterHub using:
@@ -78,13 +78,13 @@ you can load a specific config file and start JupyterHub using:
 $ jupyterhub -f /path/to/jupyterhub_config.py
 ```
 
-There is an example configuration file [here](https://github.com/jupyterhub/traefik-proxy/blob/master/examples/jupyterhub_config.py) that configures JupyterHub to run with *TraefikEtcdProxy* as the proxy and uses dummyauthenticator and simplespawner to enable testing without administrative privileges.
+There is an example configuration file [here](https://github.com/jupyterhub/traefik-proxy/blob/traefik-v2/examples/jupyterhub_config.py) that configures JupyterHub to run with *TraefikEtcdProxy* as the proxy and uses dummyauthenticator and simplespawner to enable testing without administrative privileges.
 
 In *jupyterhub_config.py*:
 
 ```
-c.JupyterHub.proxy_class = "traefik_toml"
-# will configure JupyterHub to run with TraefikTomlProxy
+c.JupyterHub.proxy_class = "traefik_file"
+# will configure JupyterHub to run with TraefikFileProxy
 ```
 
 ```
@@ -110,9 +110,9 @@ c.JupyterHub.proxy_class = "traefik_consul"
     The port on which traefik-proxy's api will run, as well as the username and password used for authenticating, can be passed to the proxy through `jupyterhub_config.py`, e.g.:
 
     ```
-    c.TraefikTomlProxy.traefik_api_url = "http://127.0.0.1:8099"
-    c.TraefikTomlProxy.traefik_api_password = "admin"
-    c.TraefikTomlProxy.traefik_api_username = "admin"
+    c.TraefikFileProxy.traefik_api_url = "http://127.0.0.1:8099"
+    c.TraefikFileProxy.traefik_api_password = "admin"
+    c.TraefikFileProxy.traefik_api_username = "admin"
     ```
     Check out TraefikProxy's **API Reference** for more configuration options.
     <br/><br/>