add document on enabling https, both with manual and letsencrypt certificates

Author: minrk

docs/source/file.md

@@ -116,29 +116,14 @@ If TraefikFileProviderProxy is used as an externally managed service, then make
    # c.TraefikFileProviderProxy.traefik_api_validate_cert = True
 
    # jupyterhub will configure traefik for itself, using this Host name
-   # (and optional path) on the router rule:-
-   c.JupyterHub.bind_url = 'https://hub.contoso.com'
+   # (and optional path) on the router rule:
+   c.JupyterHub.bind_url = 'http://hub.contoso.com'
 
    # jupyterhub will also configure traefik's 'service' url, so this needs
    # to be accessible from traefik. By default, jupyterhub will bind to
    # 'localhost', but this will bind jupyterhub to its hostname
+   # (only necessary when traefik is in a different machine or container)
    c.JupyterHub.hub_bind_url = 'http://:8000'
-
-   # jupyterhub will only allow path-based routing by default. To stop
-   # jupyterhub from serving all requests, i.e. it will add a global router
-   # rule of just PathPrefix(`/`) by default, we must configure jupyterhub as
-   # a subdomain host.
-   c.JupyterHub.subdomain_host = "https://hub.contoso.com"
-
-   # traefik can automatically request certificates from an ACME CA.
-   # JupyterHub needs to know the name of traefik's certificateResolver
-   c.TraefikFileProviderProxy.traefik_cert_resolver = "leresolver"
-
-   # For jupyterhub to let traefik manage certificates, 'ssl_cert' needs a
-   # value. (This gets around a validate rule on 'proxy.bind_url', which
-   # forces the protocol to 'http' unless there is a value in ssl_cert).
-   c.JupyterHub.ssl_cert = 'externally managed'
-
    ```
 
 3. Ensure **traefik.toml** / **traefik.yaml**

docs/source/https.md

@@ -0,0 +1,146 @@
+# Enabling HTTPS with TraefikProxy
+
+When running JupyterHub, you almost always want to use TLS (HTTPS).
+Traefik has a few ways to do that.
+The first tricky bit is that traefik separates [dynamic configuration from static configuration](https://doc.traefik.io/traefik/getting-started/configuration-overview/#the-dynamic-configuration),
+and some configuration needs to go in static, while some goes in dynamic.
+
+## Static configuration
+
+If you are using externally-managed traefik (`c.TraefikProxy.should_start = False`),
+you must write the _static_ configuration file yourself.
+The only static configuration required by juptyerhub-traefik-proxy
+is the creation of the entrypoints for the api and jupyterhub itself:
+
+```toml
+# static configuration
+
+# enable API
+[api]
+
+[entryPoints.auth_api]
+address = "localhost:8099" # should match c.TraefikProxy.traefik_api_url
+
+[entrypoints.https]
+address = ":443"
+
+[entrypoints.https.http.tls]
+options = "default"
+```
+
+jupyterhub-traefik-proxy can take care of the rest because it will apply its dynamic configuration when JupyterHub starts.
+
+## Manual SSL
+
+Configuring SSL with your own certificates works the same with traefik proxy as any other JupyterHub proxy implementation:
+
+```python
+c.JupyterHub.ssl_cert = "/path/to/ssl.cert"
+c.JupyterHub.ssl_key = "/path/to/ssl.key"
+```
+
+This will set the traefik **dynamic configuration**:
+
+```toml
+# dynamic configuration
+[tls.stores.default.defaultCertificate]
+certFile = "path/to/cert.crt"
+keyFile  = "path/to/cert.key"
+```
+
+If you don't tell jupyterhub about these files,
+you will need to set this configuration yourself in **dynamic configuration**
+(Traefik ignores TLS configuration in the "static" configuration file).
+Passing the certificates via JupyterHub configuration assumes the `options = "default"` static configuration:
+
+```toml
+# static configuration
+[entrypoints.https.http.tls]
+options = "default"
+```
+
+If you use your own static and dynamic configuration files, you don't have to use the 'default' TLS options or tell jupyterhub anything about your TLS configuration.
+
+## Let's Encrypt
+
+Traefik supports using Let's Encrypt for automatically issuing and renewing certificates.
+It's great!
+
+To configure traefik to use let's encrypt, first we need to register a [certificate resolver](https://doc.traefik.io/traefik/https/acme/) in static configuration:
+
+```toml
+# static configuration
+
+# need an http endpoint, not just https
+[entrypoints.http]
+address = ":80"
+
+[certificateResolvers.letsencrypt.acme]
+email = "[email protected]"
+storage = "acme.json" # file where certificates are stored
+[certificateResolvers.letsencrypt.acme.httpChallenge]
+entryPoint = "http"
+```
+
+And in your extra dynamic configuration, specify the domain(s) you want certificates for:
+
+```toml
+# dynamic configuration
+[tls.stores.default.defaultGeneratedCert]
+resolver = "letsencrypt"
+[tls.stores.default.defaultGeneratedCert.domain]
+main = "hub.example.com"
+sans = [
+  # if you are serving more than one domain
+  "other.service.example.com",
+]
+```
+
+If you are using JupyterHub-managed traefik (`c.TraefikProxy.should_start = True`),
+you can specify this same configuration via TraefikProxy's `extra_static_config` and `extra_dynamic_config`:
+
+```python
+c.TraefikProxy.traefik_entrypoint = "https"
+c.TraefikProxy.extra_static_config = {
+    "entryPoints": {
+        "http": {
+            "address": ":80"
+        },
+        "https": {
+            "http": {
+                "tls": {
+                    "options": "default"
+                }
+            }
+        },
+    },
+    "certificateResolvers": {
+        "letsencrypt": {
+            "acme": {
+                "email": "[email protected]",
+                "storage": "acme.json",
+            },
+            "httpChallenge": {
+                "entryPoint": "https"
+            }
+        }
+
+    }
+}
+
+
+c.TraefikProxy.extra_dynamic_config = {
+    "tls": {
+        "stores": {
+            "default": {
+                "defaultGeneratedCert": {
+                    "resolver": "letsencrypt",
+                    "domain": {
+                        "main": "hub.example.com",
+                    }
+                }
+            }
+        }
+    },
+}
+```

docs/source/index.md

@@ -32,6 +32,7 @@ install
 ```{toctree}
 :maxdepth: 1
 
+https
 file
 etcd
 consul