diff --git a/site/content/how-to/traffic-management/tls-passthrough.md b/site/content/how-to/traffic-management/tls-passthrough.md new file mode 100644 index 0000000000..53395fbc20 --- /dev/null +++ b/site/content/how-to/traffic-management/tls-passthrough.md @@ -0,0 +1,231 @@ +--- +title: "TLS Passthrough" +weight: 800 +toc: true +docs: "DOCS-000" +--- + +Learn how to use TLSRoutes to configure TLS Passthrough load-balancing with NGINX Gateway Fabric. + +## Overview + +In this guide, we will show how to configure TLS passthrough for your application, using a [TLSRoute](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TLSRoute). + +## Before you begin + +- [Install]({{< relref "installation/" >}}) NGINX Gateway Fabric. +- Save the public IP address and port of NGINX Gateway Fabric into shell variables: + + ```text + GW_IP=XXX.YYY.ZZZ.III + GW_TLS_PORT= + ``` + +{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the Gateway will forward for.{{< /note >}} + +## Set up + +Create the `secure-app` application by copying and pasting the following block into your terminal: + +```yaml +kubectl apply -f - < 8443/TCP 12s +``` + +Create a Gateway. This will create a TLS listener with the hostname `*.example.com` and passthrough TLS mode. Copy and paste this into your terminal. + +```yaml +kubectl apply -f - <}}It is possible to add an HTTPS listener on the same port that terminates TLS connections so long as the hostname does not overlap with the TLS listener hostname.{{< /note >}} + +Create a TLSRoute that attaches to the Gateway and routes requests to `app.example.com` to the `secure-app` Service: + +```yaml +kubectl apply -f - <}}To route to a Service in a Namespace different from the TLSRoute Namespace, create a [ReferenceGrant](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1beta1.ReferenceGrant) to permit the cross-namespace reference. {{< /note >}} + +## Send traffic + +Using the external IP address and port for NGINX Gateway Fabric, send traffic to the `secure-app` application. + +{{< note >}}If you have a DNS record allocated for `app.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} + +Send a request to the `secure-app` Service on the TLS port with the `--insecure` flag. The `--insecure` flag is required because the `secure-app` is using self-signed certificates. + +```shell +curl --resolve app.example.com:$GW_TLS_PORT:$GW_IP https://app.example.com:$GW_TLS_PORT --insecure -v +``` + +```text +Added app.example.com:8443:127.0.0.1 to DNS cache +* Hostname app.example.com was found in DNS cache +* Trying 127.0.0.1:8443... +* Connected to app.example.com (127.0.0.1) port 8443 +* ALPN: curl offers h2,http/1.1 +* (304) (OUT), TLS handshake, Client hello (1): +* (304) (IN), TLS handshake, Server hello (2): +* (304) (IN), TLS handshake, Unknown (8): +* (304) (IN), TLS handshake, Certificate (11): +* (304) (IN), TLS handshake, CERT verify (15): +* (304) (IN), TLS handshake, Finished (20): +* (304) (OUT), TLS handshake, Finished (20): +* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF +* ALPN: server accepted http/1.1 +* Server certificate: +* subject: C=US; ST=CA; L=San Francisco; CN=app.example.com +* start date: Mar 23 23:20:43 2020 GMT +* expire date: Mar 23 23:20:43 2023 GMT +* issuer: C=US; ST=CA; L=San Francisco; CN=app.example.com +* SSL certificate verify result: self signed certificate (18), continuing anyway. +* using HTTP/1.x +> GET / HTTP/1.1 +> Host: app.example.com:8443 +> User-Agent: curl/8.6.0 +> Accept: */* +> +< HTTP/1.1 200 OK +< Server: nginx/1.27.0 +< Date: Wed, 14 Aug 2024 20:41:21 GMT +< Content-Type: text/plain +< Content-Length: 43 +< Connection: keep-alive +< +hello from pod secure-app-575785644-kzqf6 +``` + +Note that the server certificate used to terminate the TLS connection has the subject common name of `app.example.com`. This is the server certificate that the `secure-app` is configured with and shows that the TLS connection was terminated by the `secure-app`, not NGINX Gateway Fabric. diff --git a/site/content/overview/gateway-api-compatibility.md b/site/content/overview/gateway-api-compatibility.md index c2094de2ae..e7405e5a47 100644 --- a/site/content/overview/gateway-api-compatibility.md +++ b/site/content/overview/gateway-api-compatibility.md @@ -10,18 +10,18 @@ Learn which Gateway API resources NGINX Gateway Fabric supports and to which lev ## Summary {{< bootstrap-table "table table-striped table-bordered" >}} -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | -| ------------------------------------- | ------------------- | ---------------------- | ------------------------------------- | ----------- | -| [GatewayClass](#gatewayclass) | Supported | Not supported | Supported | v1 | -| [Gateway](#gateway) | Supported | Partially supported | Not supported | v1 | -| [HTTPRoute](#httproute) | Supported | Partially supported | Not supported | v1 | -| [ReferenceGrant](#referencegrant) | Supported | N/A | Not supported | v1beta1 | -| [GRPCRoute](#grpcroute) | Supported | Partially supported | Not supported | v1 | -| [TLSRoute](#tlsroute) | Not supported | Not supported | Not supported | N/A | -| [TCPRoute](#tcproute) | Not supported | Not supported | Not supported | N/A | -| [UDPRoute](#udproute) | Not supported | Not supported | Not supported | N/A | -| [BackendTLSPolicy](#backendtlspolicy) | Supported | Supported | Not supported | v1alpha3 | -| [Custom policies](#custom-policies) | N/A | N/A | Supported | N/A | +| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | +|---------------------------------------|--------------------|------------------------|---------------------------------------|-------------| +| [GatewayClass](#gatewayclass) | Supported | Not supported | Supported | v1 | +| [Gateway](#gateway) | Supported | Partially supported | Not supported | v1 | +| [HTTPRoute](#httproute) | Supported | Partially supported | Not supported | v1 | +| [ReferenceGrant](#referencegrant) | Supported | N/A | Not supported | v1beta1 | +| [GRPCRoute](#grpcroute) | Supported | Partially supported | Not supported | v1 | +| [TLSRoute](#tlsroute) | Supported | Not supported | Not supported | v1alpha2 | +| [TCPRoute](#tcproute) | Not supported | Not supported | Not supported | N/A | +| [UDPRoute](#udproute) | Not supported | Not supported | Not supported | N/A | +| [BackendTLSPolicy](#backendtlspolicy) | Supported | Supported | Not supported | v1alpha3 | +| [Custom policies](#custom-policies) | N/A | N/A | Supported | N/A | {{< /bootstrap-table >}} --- @@ -123,6 +123,7 @@ See the [static-mode]({{< relref "/reference/cli-help.md#static-mode">}}) comman - `Accepted/False/UnsupportedProtocol` - `Accepted/False/InvalidCertificateRef` - `Accepted/False/ProtocolConflict` + - `Accpeted/False/HostnameConflict` - `Accepted/False/UnsupportedValue`: Custom reason for when a value of a field in a Listener is invalid or not supported. - `Accepted/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting Gateway. NGINX Gateway Fabric only supports a single Gateway. - `Programmed/True/Programmed` @@ -131,6 +132,7 @@ See the [static-mode]({{< relref "/reference/cli-help.md#static-mode">}}) comman - `ResolvedRefs/False/InvalidCertificateRef` - `ResolvedRefs/False/InvalidRouteKinds` - `Conflicted/True/ProtocolConflict` + - `Conflicted/True/HostnameConflict` - `Conflicted/False/NoConflicts` --- @@ -255,10 +257,38 @@ Fields: {{< bootstrap-table "table table-striped table-bordered" >}} | Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | -| -------- | ------------------ | ---------------------- | ------------------------------------- | ----------- | -| TLSRoute | Not supported | Not supported | Not supported | N/A | +|----------|--------------------|------------------------|---------------------------------------|-------------| +| TLSRoute | Supported | Not supported | Not supported | v1alpha2 | {{< /bootstrap-table >}} +**Fields**: + +- `spec` + - `parentRefs`: Partially supported. Port not supported. + - `hostnames`: Supported. + - `rules` + - `backendRefs`: Partially supported. Only one backend ref allowed. + - `weight`: Not supported. +- `status` + - `parents` + - `parentRef`: Supported. + - `controllerName`: Supported. + - `conditions`: Supported (Condition/Status/Reason): + - `Accepted/True/Accepted` + - `Accepted/False/NoMatchingListenerHostname` + - `Accepted/False/NoMatchingParent` + - `Accepted/False/NotAllowedByListeners` + - `Accepted/False/UnsupportedValue`: Custom reason for when the TLSRoute includes an invalid or unsupported value. + - `Accepted/False/InvalidListener`: Custom reason for when the TLSRoute references an invalid listener. + - `Accepted/False/GatewayNotProgrammed`: Custom reason for when the Gateway is not Programmed. TLSRoute can be valid and configured, but will maintain this status as long as the Gateway is not Programmed. + - `Accepted/False/HostnameConflict`: Custom reason for when the TLSRoute has a hostname that conflicts with another TLSRoute on the same port. + - `ResolvedRefs/True/ResolvedRefs` + - `ResolvedRefs/False/InvalidKind` + - `ResolvedRefs/False/RefNotPermitted` + - `ResolvedRefs/False/BackendNotFound` + - `ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the TLSRoute rules has a backendRef with an unsupported value. + - `PartiallyInvalid/True/UnsupportedValue` + --- ### TCPRoute diff --git a/site/go.mod b/site/go.mod index 7dd1ab90e6..b745ac77f8 100644 --- a/site/go.mod +++ b/site/go.mod @@ -2,4 +2,4 @@ module github.com/nginxinc/nginx-gateway-fabric/site go 1.21 -require github.com/nginxinc/nginx-hugo-theme v0.41.0 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.41.1 // indirect diff --git a/site/go.sum b/site/go.sum index ea6bf85748..9f3c8112b0 100644 --- a/site/go.sum +++ b/site/go.sum @@ -1,2 +1,4 @@ github.com/nginxinc/nginx-hugo-theme v0.41.0 h1:uB9jC0Qk9i2CG63gScHxVHAEz1zyGoAdtY0Lcpkg1lI= github.com/nginxinc/nginx-hugo-theme v0.41.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v0.41.1 h1:Wan0Mb8uz1X4Z2vd/1nR0GOPel5mWVPuFD3jd4SezsU= +github.com/nginxinc/nginx-hugo-theme v0.41.1/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=