docs: format, typo, clarification, z2jh ingress example

consideRatio · consideRatio · commit ce49d22af0be · 2021-07-23T04:59:04.000+02:00
diff --git a/README.md b/README.md
@@ -21,7 +21,7 @@ The JupyterHub SSH service provides SSH access to your user environment in a Jup
 
 ![Overview](https://raw.githubusercontent.com/yuvipanda/jupyterhub-ssh/main/docs/source/_static/images/technical-overview.png)
 
-Apart from SSH access to JupyterHub, once `jupyterhub-ssh` was deployed, you can also use it to tranfer files from your local
+Apart from SSH access to JupyterHub, once `jupyterhub-ssh` was deployed, you can also use it to transfer files from your local
 home directory into your remote hub home directory. This is achieved through `jupyterhub-sftp`, a service that provides a SFTP
 setup using [OpenSSH](https://www.openssh.com/). `jupyterhub-sftp` currently supports only [NFS](https://tldp.org/LDP/nag/node140.html)
 based home directories.
@@ -30,14 +30,16 @@ based home directories.
 
 Instructions on how to install and deploy JupyterHub SSH & SFTP services.
 
-### Regular deployment
+### Regular deployment (jupyterhub ssh only)
 
 1. Clone the repo and install the jupyterhub-ssh package:
+
    ```bash
    $ git clone https://github.com/yuvipanda/jupyterhub-ssh.git
    $ cd jupyterhub-ssh
    $ pip install -e .
    ```
+
 1. Or install the package directly:
 
    ```bash
@@ -59,47 +61,144 @@ Instructions on how to install and deploy JupyterHub SSH & SFTP services.
 
 1. Start the JupyterHubSSH app from the directory where the config file
    `jupyterhub_ssh_config.py` is located:
-   `bash $ python -m jupyterhub_ssh `
 
-### Kubernetes based deployment
-
-If your JupyterHub was deployed using Kubernetes, you can use the Helm charts available in this repo to deploy JupyterHub SSH & SFTP
-directly into your Kubernetes cluster.
+   ```bash
+   python -m jupyterhub_ssh
+   ```
 
-- Let helm the command line tool know about a Helm chart repository that we decide to name jupyterhub.
-  ```bash
-  $ helm repo add jupyterhub-ssh https://yuvipanda.github.io/jupyterhub-ssh/
-  $ helm repo update
-  ```
-- Simplified example on how to install a Helm chart from a Helm chart repository named jupyterhub-ssh. See the Helm chart's documentation
-  for additional details required.
-  ```bash
-  $ helm install jupyterhub-ssh/jupyterhub-ssh --version <helm chart version> --set hubUrl=https://jupyter.example.org --set-file hostKey=<path to a private SSH key>
-  ```
+### Kubernetes based deployment (jupyterhub ssh and/or sftp)
+
+If your JupyterHub has been deployed to Kubernetes, you can use the Helm chart
+available in this repo to deploy JupyterHub SSH and/or JupyterHub SFTP directly
+into your Kubernetes cluster.
+
+```bash
+helm install <helm-release-name> \
+   --repo https://yuvipanda.github.io/jupyterhub-ssh/ jupyterhub-ssh \
+   --version <helm chart version> \
+   --set hubUrl=https://jupyter.example.org \
+   --set ssh.enabled=true \
+   --set sftp.enabled=false
+```
+
+If you install JupyterHub SFTP, then it needs access to the home folders. These
+home folders are assumed to be exposed via a k8s PVC resource that you should
+name via the `sftp.pvc.name` configuration.
+
+If your JupyterHub has been deployed using [the official JupyterHub Helm
+chart](https://z2jh.jupyter.org) version 1.1.0 or later, and you have
+_configured the official JupyterHub Helm chart_ with `proxy.https.enabled=true`
+and `proxy.https.type=letsencrypt`, then you can add the following to to acquire
+access to the jupyterhub-ssh and jupyterhub-sftp services via that setup.
+
+```yaml
+# Configuration for the official JupyterHub Helm chart to accept traffic via
+proxy:
+   https:
+      enabled: true
+      type: letsencrypt
+      letsencryptEmail: <my-email-here>
+
+   service:
+     # jupyterhub-ssh/sftp integration part 1/3:
+     #
+     # We must accept traffic to the k8s Service (proxy-public) receiving traffic
+     # from the internet. Port 22 is typically used for both SSH and SFTP, but we
+     # can't use the same port for both so we use 23.
+     #
+     extraPorts:
+       - name: ssh
+         port: 22
+         targetPort: ssh
+       - name: sftp
+         port: 23
+         targetPort: sftp
+
+   traefik:
+     # jupyterhub-ssh/sftp integration part 2/3:
+     #
+     # We must accept traffic arriving to the autohttps pod (traefik) from the
+     # proxy-public service. Expose a port and update the NetworkPolicy
+     # to tolerate incoming (ingress) traffic on the exposed port.
+     #
+     extraPorts:
+       - name: ssh
+         containerPort: 8022
+       - name: sftp
+         containerPort: 8023
+     networkPolicy:
+       allowedIngressPorts: [http, https, ssh]
+
+     # jupyterhub-ssh/sftp integration part 3/3:
+     #
+     # We must let traefik know it should listen for traffic (traefik entrypoint)
+     # and route it (traefik router) onwards to the jupyterhub-ssh k8s Service
+     # (traefik service).
+     #
+     extraStaticConfig:
+       entryPoints:
+         ssh-entrypoint:
+           address: :8022
+         ssh-entrypoint:
+           address: :8023
+     extraDynamicConfig:
+       tcp:
+         services:
+           ssh-service:
+             loadBalancer:
+               servers:
+                 - address: jupyterhub-ssh:22
+           sftp-service:
+             loadBalancer:
+               servers:
+                 - address: jupyterhub-sftp:22
+         routers:
+           ssh-router:
+             entrypoints:
+               - ssh-entrypoint
+             rule: HostSNI(`*`)
+             service: ssh-service
+           sftp-router:
+             entrypoints:
+               - sftp-entrypoint
+             rule: HostSNI(`*`)
+             service: sftp-service
+```
 
 ## How to use it
 
 ### How to SSH
 
 1. Login into your JupyterHub and go to `https://<hub-address>/hub/token`.
+
 2. Copy the token from JupyterHub.
+
 3. SSH into JupyterHub:
+
    ```bash
-   $ ssh <username-you-used>@<hub-address>
+   ssh <hub-username>@<hub-address>
    ```
+
 4. Enter the token received from JupyterHub as a password.
+
 5. TADA :tada: Now you have an interactive terminal! You can do anything you would generally interactively do via ssh: run editors,
    fully interactive programs, use the commandline, etc. Some features like non-interactive command running, tunneling, etc are currently
    unavailable.
 
 ### How to SFTP
 
 1. Login into your JupyterHub and go to `https://<hub-address>/hub/token`.
+
 2. Copy the token from JupyterHub.
+
 3. Transfer file into Jupyterhub:
+
    - Using the `sftp` command:
+
      ```bash
-     $ sftp <hub-username>@<hub-address>
+     sftp <hub-username>@<hub-address>
      ```
+
 4. Enter the token received from JupyterHub as a password.
+
 5. TADA :tada: Now you can transfer files to and from your home directory on the hubs.
