Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Complete documentation about SSL Passthrough #3068

Merged
merged 1 commit into from
Sep 10, 2018
Merged

Complete documentation about SSL Passthrough #3068

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions docs/user-guide/nginx-configuration/annotations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

!!! 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.
!!! note
SSL Passthrough is **disabled by default** and requires starting the controller with the
[`--enable-ssl-passthrough`](../cli-arguments/) flag.

!!! 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)

Expand Down
22 changes: 17 additions & 5 deletions docs/user-guide/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
[ssl-ciphers]: ./nginx-configuration/configmap.md#ssl-ciphers
[SNI]: https://en.wikipedia.org/wiki/Server_Name_Indication