You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: site/content/how-to/traffic-management/tls-passthrough.md
+57-20Lines changed: 57 additions & 20 deletions
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,11 @@
1
1
---
2
2
title: "TLS Passthrough"
3
-
weight: 600
3
+
weight: 800
4
4
toc: true
5
5
docs: "DOCS-000"
6
6
---
7
7
8
-
Learn how to passthrough TLS connections using NGINX Gateway Fabric.
8
+
Learn how to use TLSRoutes to configure TLS Passthrough load-balancing with NGINX Gateway Fabric.
9
9
10
10
## Overview
11
11
@@ -18,19 +18,14 @@ In this guide, we will show how to configure TLS passthrough for your applicatio
18
18
19
19
```text
20
20
GW_IP=XXX.YYY.ZZZ.III
21
-
GW_PORT=<port number>
22
-
```
23
-
24
-
Save the ports of NGINX Gateway Fabric:
25
-
26
-
```text
27
-
GW_HTTP_PORT=<http port number>
28
-
GW_HTTPS_PORT=<https port number>
21
+
GW_TLS_PORT=<port number>
29
22
```
30
23
31
24
{{< 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 >}}
32
25
33
-
Create the tls-backend application by copying and pasting the following block into your terminal:
26
+
## Set up
27
+
28
+
Create the `secure-app` application by copying and pasting the following block into your terminal:
34
29
35
30
```yaml
36
31
kubectl apply -f - <<EOF
@@ -98,7 +93,7 @@ data:
98
93
default_type text/plain;
99
94
100
95
location / {
101
-
return 200 "hello from pod $hostname\n";
96
+
return 200 "hello from pod \$hostname\n";
102
97
}
103
98
}
104
99
---
@@ -112,7 +107,9 @@ data:
112
107
EOF
113
108
```
114
109
115
-
This will create the **secure-app** service and a deployment. Run the following command to verify the resources were created:
110
+
This will create the **secure-app** service and a deployment. The secure app is configured to serve HTTPS traffic on port 8443 for the host app.example.com. For TLS termination, a self-signed TLS certificate, with the common name `app.example.com`, and key are used. The app responds to clients HTTPS requests with a simple text response "hello from pod $POD_HOSTNAME".
111
+
112
+
Run the following command to verify the resources were created:
116
113
117
114
```shell
118
115
kubectl get pods,svc
@@ -128,7 +125,7 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
Create a gateway. This will create TLS listener with the hostname *.example.com. Copy paste this into your terminal.
128
+
Create a gateway. This will create a TLS listener with the hostname `*.example.com` and a TLS mode of passthrough. Copy and paste this into your terminal.
132
129
133
130
```yaml
134
131
kubectl apply -f - <<EOF
@@ -154,7 +151,11 @@ spec:
154
151
EOF
155
152
```
156
153
157
-
Create a TLSRoute, this will reference the service and the gateway.
154
+
This gateway will configure NGINX Gateway Fabric to accept TLS connections on port 443 and route them to the corresponding backend services without decryption. The routing is done based on the SNI, which allows clients to specify a server name (like example.com) during the SSL handshake.
155
+
156
+
{{< note >}} 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 >}}
157
+
158
+
Create a TLSRoute that attaches to the gateway and routes requests to `app.example.com` to the `secure-app` service:
158
159
159
160
```yaml
160
161
kubectl apply -f - <<EOF
@@ -168,7 +169,6 @@ spec:
168
169
- name: gateway
169
170
namespace: default
170
171
hostnames:
171
-
- "cafe.example.com"
172
172
- "app.example.com"
173
173
rules:
174
174
- backendRefs:
@@ -177,18 +177,55 @@ spec:
177
177
EOF
178
178
```
179
179
180
+
{{< note >}}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 >}}
181
+
180
182
## Send traffic
181
183
182
-
Using the external IP address and port for NGINX Gateway Fabric, send traffic to the coffee application.
184
+
Using the external IP address and port for NGINX Gateway Fabric, send traffic to the `secure-app` application.
183
185
184
-
{{< note >}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}}
186
+
{{< 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 >}}
185
187
186
-
Send a request to the `secure-app` service on the HTTPS port with the `--insecure` flag. The `--insecure` flag is required because the `secure-app` is using self-signed certificates.
188
+
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.
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.
@@ -123,6 +123,7 @@ See the [static-mode]({{< relref "/reference/cli-help.md#static-mode">}}) comman
123
123
-`Accepted/False/UnsupportedProtocol`
124
124
-`Accepted/False/InvalidCertificateRef`
125
125
-`Accepted/False/ProtocolConflict`
126
+
-`Accpeted/False/HostnameConflict`
126
127
-`Accepted/False/UnsupportedValue`: Custom reason for when a value of a field in a Listener is invalid or not supported.
127
128
-`Accepted/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting Gateway. NGINX Gateway Fabric only supports a single Gateway.
128
129
-`Programmed/True/Programmed`
@@ -131,6 +132,7 @@ See the [static-mode]({{< relref "/reference/cli-help.md#static-mode">}}) comman
-`Accepted/False/UnsupportedValue`: Custom reason for when the TLSRoute includes an invalid or unsupported value.
282
+
-`Accepted/False/InvalidListener`: Custom reason for when the TLSRoute references an invalid listener.
283
+
-`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.
284
+
-`Accepted/False/HostnameConflict`: Custom reason for when the TLSRoute has a hostname that conflicts with another TLSRoute on the same port.
285
+
-`ResolvedRefs/True/ResolvedRefs`
286
+
-`ResolvedRefs/False/InvalidKind`
287
+
-`ResolvedRefs/False/RefNotPermitted`
288
+
-`ResolvedRefs/False/BackendNotFound`
289
+
-`ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the TLSRoute rules has a backendRef with an unsupported value.
0 commit comments