From a99f56dcbe610ad6556cdee637391e7319c9407e Mon Sep 17 00:00:00 2001
From: Antoine Cotten <hello@acotten.com>
Date: Mon, 10 Sep 2018 19:29:11 +0200
Subject: [PATCH] Complete documentation about SSL Passthrough

---
 .../nginx-configuration/annotations.md        | 15 ++++++++-----
 docs/user-guide/tls.md                        | 22 ++++++++++++++-----
 2 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/docs/user-guide/nginx-configuration/annotations.md b/docs/user-guide/nginx-configuration/annotations.md
index 0f6939ba2..2f6ced652 100644
--- a/docs/user-guide/nginx-configuration/annotations.md
+++ b/docs/user-guide/nginx-configuration/annotations.md
@@ -379,14 +379,17 @@ This annotation allows you to modify the status code used for permanent redirect
 
 ### SSL Passthrough
 
-The annotation `nginx.ingress.kubernetes.io/ssl-passthrough` allows to configure TLS termination in the pod and not in NGINX.
+The annotation `nginx.ingress.kubernetes.io/ssl-passthrough` instructs the controller to send TLS connections directly
+to the backend instead of letting NGINX decrypt the communication. See also [TLS/HTTPS](../tls/#ssl-passthrough) in
+the User guide.
+
+!!! note
+    SSL Passthrough is **disabled by default** and requires starting the controller with the
+    [`--enable-ssl-passthrough`](../cli-arguments/) flag.
 
 !!! attention
-    Using the annotation `nginx.ingress.kubernetes.io/ssl-passthrough` invalidates all the other available annotations.
-    This is because SSL Passthrough works on level 4 of the OSI stack (TCP), not on the HTTP/HTTPS level.
-
-!!! attention
-    The use of this annotation requires the flag `--enable-ssl-passthrough` (By default it is disabled).
+    Because SSL Passthrough works on layer 4 of the OSI model (TCP) and not on the layer 7 (HTTP), using SSL Passthrough
+    invalidates all the other annotations set on an Ingress object.
 
 ### Secure backends DEPRECATED (since 0.18.0)
 
diff --git a/docs/user-guide/tls.md b/docs/user-guide/tls.md
index 250b0a5b4..9b6961423 100644
--- a/docs/user-guide/tls.md
+++ b/docs/user-guide/tls.md
@@ -36,12 +36,23 @@ add `--default-ssl-certificate=default/foo-tls` in the `nginx-controller` deploy
 
 ## SSL Passthrough
 
-The flag `--enable-ssl-passthrough` enables the SSL passthrough feature.
-By default this feature is disabled.
+The [`--enable-ssl-passthrough`](cli-arguments/) flag enables the SSL Passthrough feature, which is disabled by
+default. This is required to enable passthrough backends in Ingress objects.
 
-This is required to enable passthrough backends in Ingress configurations.
+!!! warning
+    This feature is implemented by intercepting **all traffic** on the configured HTTPS port (default: 443) and handing
+    it over to a local TCP proxy. This bypasses NGINX completely and introduces a non-negligible performance penalty.
 
-TODO: Improve this documentation.
+SSL Passthrough leverages [SNI][SNI] and reads the virtual domain from the TLS negotiation, which requires compatible
+clients. After a connection has been accepted by the TLS listener, it is handled by the controller itself and piped back
+and forth between the backend and the client.
+
+If there is no hostname matching the requested host name, the request is handed over to NGINX on the configured
+passthrough proxy port (default: 442), which proxies the request to the default backend.
+
+!!! note
+    Unlike HTTP backends, traffic to Passthrough backends is sent to the *clusterIP* of the backing Service instead of
+    individual Endpoints.
 
 ## HTTP Strict Transport Security
 
@@ -122,4 +133,5 @@ data:
 [Kube-Lego]:https://github.com/jetstack/kube-lego
 [Let's Encrypt]:https://letsencrypt.org
 [ConfigMap]: ./nginx-configuration/configmap.md
-[ssl-ciphers]: ./nginx-configuration/configmap.md#ssl-ciphers
\ No newline at end of file
+[ssl-ciphers]: ./nginx-configuration/configmap.md#ssl-ciphers
+[SNI]: https://en.wikipedia.org/wiki/Server_Name_Indication