Skip to content

Commit 105c349

Browse files
ciarams87ciarams87
committed
Improve how-to guide
1 parent 498c43a commit 105c349

File tree

1 file changed

+116
-48
lines changed

1 file changed

+116
-48
lines changed

‎site/content/how-to/traffic-management/backend-tls-termination.md

Lines changed: 116 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ toc: true
66
docs: "DOCS-000"
77
---
88

9-
In this guide, we will show how to specify the TLS configuration of the connection from the Gateway to a backend pod/s via the Service API object using a [BackendTLSPolicy](https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/).
9+
In this guide, we will show how to specify the TLS configuration of the connection from the Gateway to a backend pod/s via the Service API object using a [BackendTLSPolicy](https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/). This covers the use-case where the service or backend owner is doing their own TLS and NGINX Gateway Fabric needs to know how to connect to this backend pod that has its own certificate over HTTPS.
1010

1111
## Prerequisites
1212

13-
- [Install]({{< relref "installation/" >}}) NGINX Gateway Fabric. Please note that the Gateway APIs from the experimental channel are required, and NGF must be deployed with the `- --experimental-features-enable` flag..
13+
- [Install]({{< relref "installation/" >}}) NGINX Gateway Fabric. Please note that the Gateway APIs from the experimental channel are required, and NGF must be deployed with the `- --experimental-features-enable` flag.
1414
- [Expose NGINX Gateway Fabric]({{< relref "installation/expose-nginx-gateway-fabric.md" >}}) and save the public IP address and port of NGINX Gateway Fabric into shell variables:
1515

1616
```text
@@ -106,7 +106,7 @@ data:
106106
EOF
107107
```
108108

109-
This will create the **secure-app** service and a deployment, as well as a Secret containing the certificate and key that will be used by the backend application to decrypt the HTTP traffic. Note that the application is configured to accept HTTPS traffic only. Run the following command to verify the resources were created:
109+
This will create the **secure-app** service and a deployment, as well as a Secret containing the certificate and key that will be used by the backend application to decrypt the HTTPS traffic. Note that the application is configured to accept HTTPS traffic only. Run the following command to verify the resources were created:
110110

111111
```shell
112112
kubectl get pods,svc
@@ -122,9 +122,76 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
122122
service/secure-app ClusterIP 10.96.213.57 <none> 8443/TCP 9s
123123
```
124124

125+
## Configure Routing rules
126+
127+
First, we will create the Gateway resource with an HTTP listener:
128+
129+
```yaml
130+
kubectl apply -f - <<EOF
131+
apiVersion: gateway.networking.k8s.io/v1
132+
kind: Gateway
133+
metadata:
134+
name: gateway
135+
spec:
136+
gatewayClassName: nginx
137+
listeners:
138+
- name: http
139+
port: 80
140+
protocol: HTTP
141+
EOF
142+
```
143+
144+
Next, we will create our HTTPRoute to route traffic to our secure-app backend:
145+
146+
```yaml
147+
kubectl apply -f - <<EOF
148+
apiVersion: gateway.networking.k8s.io/v1
149+
kind: HTTPRoute
150+
metadata:
151+
name: secure-app
152+
spec:
153+
parentRefs:
154+
- name: gateway
155+
sectionName: http
156+
hostnames:
157+
- "secure-app.example.com"
158+
rules:
159+
- matches:
160+
- path:
161+
type: PathPrefix
162+
value: /
163+
backendRefs:
164+
- name: secure-app
165+
port: 8443
166+
EOF
167+
```
168+
169+
## Send Traffic without backend TLS configuration
170+
171+
Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our secure-app application. To show what happens if we send plain HTTP traffic from NGF to our `secure-app`, let's try sending a request before we create the backend TLS configuration.
172+
173+
{{< note >}}If you have a DNS record allocated for `secure-app.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}}
174+
175+
```shell
176+
curl --resolve secure-app.example.com:$GW_PORT:$GW_IP http://secure-app.example.com:$GW_PORT/ --insecure
177+
```
178+
179+
```text
180+
<html>
181+
<head><title>400 The plain HTTP request was sent to HTTPS port</title></head>
182+
<body>
183+
<center><h1>400 Bad Request</h1></center>
184+
<center>The plain HTTP request was sent to HTTPS port</center>
185+
<hr><center>nginx/1.25.3</center>
186+
</body>
187+
</html>
188+
```
189+
190+
We can see we a status 400 Bad Request message from NGINX.
191+
125192
## Create the Backend TLS configuration
126193

127-
Create the ConfigMap that holds the `ca.crt` entry for verifying our self-signed certificates:
194+
To configure the backend TLS terminationm, first we will create the ConfigMap that holds the `ca.crt` entry for verifying our self-signed certificates:
128195

129196
```yaml
130197
kubectl apply -f - <<EOF
@@ -158,7 +225,7 @@ data:
158225
EOF
159226
```
160227

161-
Create the Backend TLS Policy which targets our `secure-app` Service and refers to the ConfigMap created in the previous step:
228+
Next, we create the Backend TLS Policy which targets our `secure-app` Service and refers to the ConfigMap created in the previous step:
162229

163230
```yaml
164231
kubectl apply -f - <<EOF
@@ -181,55 +248,56 @@ spec:
181248
EOF
182249
```
183250

184-
## Configure Routing rules
185-
186-
First, we will create the Gateway resource with a HTTP listener:
251+
To confirm the Polict was created and attached successfully, we can run a describe on the BackendTLSPolicy object:
187252

188-
```yaml
189-
kubectl apply -f - <<EOF
190-
apiVersion: gateway.networking.k8s.io/v1
191-
kind: Gateway
192-
metadata:
193-
name: gateway
194-
spec:
195-
gatewayClassName: nginx
196-
listeners:
197-
- name: http
198-
port: 80
199-
protocol: HTTP
200-
EOF
253+
```shell
254+
k describe backendtlspolicies.gateway.networking.k8s.io
201255
```
202256

203-
Next, we will create our HTTPRoute to route traffic to our secure-app backend
204-
205-
```yaml
206-
kubectl apply -f - <<EOF
207-
apiVersion: gateway.networking.k8s.io/v1
208-
kind: HTTPRoute
209-
metadata:
210-
name: secure-app
211-
spec:
212-
parentRefs:
213-
- name: gateway
214-
sectionName: http
215-
hostnames:
216-
- "secure-app.example.com"
217-
rules:
218-
- matches:
219-
- path:
220-
type: PathPrefix
221-
value: /
222-
backendRefs:
223-
- name: secure-app
224-
port: 8443
225-
EOF
257+
```text
258+
Name: backend-tls
259+
Namespace: default
260+
Labels: <none>
261+
Annotations: <none>
262+
API Version: gateway.networking.k8s.io/v1alpha2
263+
Kind: BackendTLSPolicy
264+
Metadata:
265+
Creation Timestamp: 2024-02-01T12:02:38Z
266+
Generation: 1
267+
Resource Version: 19380
268+
UID: b3983a6e-92f1-4a98-b2af-64b317d74528
269+
Spec:
270+
Target Ref:
271+
Group:
272+
Kind: Service
273+
Name: secure-app
274+
Namespace: default
275+
Tls:
276+
Ca Cert Refs:
277+
Group:
278+
Kind: ConfigMap
279+
Name: backend-cert
280+
Hostname: secure-app.example.com
281+
Status:
282+
Ancestors:
283+
Ancestor Ref:
284+
Group: gateway.networking.k8s.io
285+
Kind: Gateway
286+
Name: gateway
287+
Namespace: default
288+
Conditions:
289+
Last Transition Time: 2024-02-01T12:02:38Z
290+
Message: BackendTLSPolicy is attached to the Gateway
291+
Reason: BackendTLSPolicyAttached
292+
Status: True
293+
Type: Attached
294+
Controller Name: gateway.nginx.org/nginx-gateway-controller
295+
Events: <none>
226296
```
227297

228-
## Send Traffic
298+
## Send Traffic with backend TLS configuration
229299

230-
Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our secure-app application.
231-
232-
{{< note >}}If you have a DNS record allocated for `secure-app.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}}
300+
Now let's try sending traffic again:
233301

234302
```shell
235303
curl --resolve secure-app.example.com:$GW_PORT:$GW_IP http://secure-app.example.com:$GW_PORT/ --insecure

0 commit comments

Comments
 (0)