Skip to content

Commit 2bb1509

Browse files
sjbermansjberman
committed
How-to guides
1 parent eb0295c commit 2bb1509

File tree

4 files changed

+453
-6
lines changed

4 files changed

+453
-6
lines changed

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

+245
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
---
2+
title: "HTTPS Termination"
3+
description: "Learn how to terminate HTTPS traffic using NGINX Gateway Fabric."
4+
weight: 500
5+
toc: true
6+
docs: "DOCS-000"
7+
---
8+
9+
In this guide, we will show how to configure HTTPS termination for your application, using an [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) redirect filter, secret, and [ReferenceGrant](https://gateway-api.sigs.k8s.io/api-types/referencegrant/).
10+
11+
## Prerequisites
12+
13+
- [Install]({{< relref "installation/" >}}) NGINX Gateway Fabric.
14+
- [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:
15+
16+
```text
17+
GW_IP=XXX.YYY.ZZZ.III
18+
GW_PORT=<port number>
19+
```
20+
21+
Save the ports of NGINX Gateway Fabric:
22+
23+
```text
24+
GW_HTTP_PORT=<http port number>
25+
GW_HTTPS_PORT=<https port number>
26+
```
27+
28+
{{< 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 >}}
29+
30+
## Set up
31+
32+
Create the **coffee** application in Kubernetes by copying and pasting the following block into your terminal:
33+
34+
```yaml
35+
kubectl apply -f - <<EOF
36+
apiVersion: apps/v1
37+
kind: Deployment
38+
metadata:
39+
name: coffee
40+
spec:
41+
replicas: 1
42+
selector:
43+
matchLabels:
44+
app: coffee
45+
template:
46+
metadata:
47+
labels:
48+
app: coffee
49+
spec:
50+
containers:
51+
- name: coffee
52+
image: nginxdemos/nginx-hello:plain-text
53+
ports:
54+
- containerPort: 8080
55+
---
56+
apiVersion: v1
57+
kind: Service
58+
metadata:
59+
name: coffee
60+
spec:
61+
ports:
62+
- port: 80
63+
targetPort: 8080
64+
protocol: TCP
65+
name: http
66+
selector:
67+
app: coffee
68+
EOF
69+
```
70+
71+
This will create the **coffee** service and a deployment. Run the following command to verify the resources were created:
72+
73+
```shell
74+
kubectl get pods,svc
75+
```
76+
77+
Your output should include the **coffee** pod and the **coffee** service:
78+
79+
```text
80+
NAME READY STATUS RESTARTS AGE
81+
pod/coffee-6b8b6d6486-7fc78 1/1 Running 0 40s
82+
83+
84+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
85+
service/coffee ClusterIP 10.96.189.37 <none> 80/TCP 40s
86+
```
87+
88+
## Configure HTTPS Termination and Routing
89+
90+
For the HTTPS, we need a certificate and key that are stored in a secret. This secret will live in a separate namespace, so we will need a ReferenceGrant in order to access it.
91+
92+
To create the **certificate** namespace and secret, copy and paste the following into your terminal:
93+
94+
```yaml
95+
kubectl apply -f - <<EOF
96+
apiVersion: v1
97+
kind: Namespace
98+
metadata:
99+
name: certificate
100+
---
101+
apiVersion: v1
102+
kind: Secret
103+
metadata:
104+
name: cafe-secret
105+
namespace: certificate
106+
type: kubernetes.io/tls
107+
data:
108+
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNzakNDQVpvQ0NRQzdCdVdXdWRtRkNEQU5CZ2txaGtpRzl3MEJBUXNGQURBYk1Sa3dGd1lEVlFRRERCQmoKWVdabExtVjRZVzF3YkdVdVkyOXRNQjRYRFRJeU1EY3hOREl4TlRJek9Wb1hEVEl6TURjeE5ESXhOVEl6T1ZvdwpHekVaTUJjR0ExVUVBd3dRWTJGbVpTNWxlR0Z0Y0d4bExtTnZiVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFECmdnRVBBRENDQVFvQ2dnRUJBTHFZMnRHNFc5aStFYzJhdnV4Q2prb2tnUUx1ek10U1Rnc1RNaEhuK3ZRUmxIam8KVzFLRnMvQVdlS25UUStyTWVKVWNseis4M3QwRGtyRThwUisxR2NKSE50WlNMb0NEYUlRN0Nhck5nY1daS0o4Qgo1WDNnVS9YeVJHZjI2c1REd2xzU3NkSEQ1U2U3K2Vab3NPcTdHTVF3K25HR2NVZ0VtL1Q1UEMvY05PWE0zZWxGClRPL051MStoMzROVG9BbDNQdTF2QlpMcDNQVERtQ0thaEROV0NWbUJQUWpNNFI4VERsbFhhMHQ5Z1o1MTRSRzUKWHlZWTNtdzZpUzIrR1dYVXllMjFuWVV4UEhZbDV4RHY0c0FXaGRXbElweHlZQlNCRURjczN6QlI2bFF1OWkxZAp0R1k4dGJ3blVmcUVUR3NZdWxzc05qcU95V1VEcFdJelhibHhJZVVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGCkFBT0NBUUVBcjkrZWJ0U1dzSnhLTGtLZlRkek1ISFhOd2Y5ZXFVbHNtTXZmMGdBdWVKTUpUR215dG1iWjlpbXQKL2RnWlpYVE9hTElHUG9oZ3BpS0l5eVVRZVdGQ2F0NHRxWkNPVWRhbUloOGk0Q1h6QVJYVHNvcUNOenNNLzZMRQphM25XbFZyS2lmZHYrWkxyRi8vblc0VVNvOEoxaCtQeDljY0tpRDZZU0RVUERDRGh1RUtFWXcvbHpoUDJVOXNmCnl6cEJKVGQ4enFyM3paTjNGWWlITmgzYlRhQS82di9jU2lyamNTK1EwQXg4RWpzQzYxRjRVMTc4QzdWNWRCKzQKcmtPTy9QNlA0UFlWNTRZZHMvRjE2WkZJTHFBNENCYnExRExuYWRxamxyN3NPbzl2ZzNnWFNMYXBVVkdtZ2todAp6VlZPWG1mU0Z4OS90MDBHUi95bUdPbERJbWlXMGc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
109+
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2UUlCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktjd2dnU2pBZ0VBQW9JQkFRQzZtTnJSdUZ2WXZoSE4KbXI3c1FvNUtKSUVDN3N6TFVrNExFeklSNS9yMEVaUjQ2RnRTaGJQd0ZuaXAwMFBxekhpVkhKYy92TjdkQTVLeApQS1VmdFJuQ1J6YldVaTZBZzJpRU93bXF6WUhGbVNpZkFlVjk0RlAxOGtSbjl1ckV3OEpiRXJIUncrVW51L25tCmFMRHF1eGpFTVBweGhuRklCSnYwK1R3djNEVGx6TjNwUlV6dnpidGZvZCtEVTZBSmR6N3Rid1dTNmR6MHc1Z2kKbW9RelZnbFpnVDBJek9FZkV3NVpWMnRMZllHZWRlRVJ1VjhtR041c09va3R2aGxsMU1udHRaMkZNVHgySmVjUQo3K0xBRm9YVnBTS2NjbUFVZ1JBM0xOOHdVZXBVTHZZdFhiUm1QTFc4SjFINmhFeHJHTHBiTERZNmpzbGxBNlZpCk0xMjVjU0hsQWdNQkFBRUNnZ0VBQnpaRE50bmVTdWxGdk9HZlFYaHRFWGFKdWZoSzJBenRVVVpEcUNlRUxvekQKWlV6dHdxbkNRNlJLczUyandWNTN4cU9kUU94bTNMbjNvSHdNa2NZcEliWW82MjJ2dUczYnkwaVEzaFlsVHVMVgpqQmZCcS9UUXFlL2NMdngvSkczQWhFNmJxdFRjZFlXeGFmTmY2eUtpR1dzZk11WVVXTWs4MGVJVUxuRmZaZ1pOCklYNTlSOHlqdE9CVm9Sa3hjYTVoMW1ZTDFsSlJNM3ZqVHNHTHFybmpOTjNBdWZ3ZGRpK1VDbGZVL2l0K1EvZkUKV216aFFoTlRpNVFkRWJLVStOTnYvNnYvb2JvandNb25HVVBCdEFTUE05cmxFemIralQ1WHdWQjgvLzRGY3VoSwoyVzNpcjhtNHVlQ1JHSVlrbGxlLzhuQmZ0eVhiVkNocVRyZFBlaGlPM1FLQmdRRGlrR3JTOTc3cjg3Y1JPOCtQClpoeXltNXo4NVIzTHVVbFNTazJiOTI1QlhvakpZL2RRZDVTdFVsSWE4OUZKZnNWc1JRcEhHaTFCYzBMaTY1YjIKazR0cE5xcVFoUmZ1UVh0UG9GYXRuQzlPRnJVTXJXbDVJN0ZFejZnNkNQMVBXMEg5d2hPemFKZUdpZVpNYjlYTQoybDdSSFZOcC9jTDlYbmhNMnN0Q1lua2Iwd0tCZ1FEUzF4K0crakEyUVNtRVFWNXA1RnRONGcyamsyZEFjMEhNClRIQ2tTazFDRjhkR0Z2UWtsWm5ZbUt0dXFYeXNtekJGcnZKdmt2eUhqbUNYYTducXlpajBEdDZtODViN3BGcVAKQWxtajdtbXI3Z1pUeG1ZMXBhRWFLMXY4SDNINGtRNVl3MWdrTWRybVJHcVAvaTBGaDVpaGtSZS9DOUtGTFVkSQpDcnJjTzhkUVp3S0JnSHA1MzRXVWNCMVZibzFlYStIMUxXWlFRUmxsTWlwRFM2TzBqeWZWSmtFb1BZSEJESnp2ClIrdzZLREJ4eFoyWmJsZ05LblV0YlhHSVFZd3lGelhNcFB5SGxNVHpiZkJhYmJLcDFyR2JVT2RCMXpXM09PRkgKcmppb21TUm1YNmxhaDk0SjRHU0lFZ0drNGw1SHhxZ3JGRDZ2UDd4NGRjUktJWFpLZ0w2dVJSSUpBb0dCQU1CVApaL2p5WStRNTBLdEtEZHUrYU9ORW4zaGxUN3hrNXRKN3NBek5rbWdGMU10RXlQUk9Xd1pQVGFJbWpRbk9qbHdpCldCZ2JGcXg0M2ZlQ1Z4ZXJ6V3ZEM0txaWJVbWpCTkNMTGtYeGh3ZEVteFQwVit2NzZGYzgwaTNNYVdSNnZZR08KditwVVovL0F6UXdJcWZ6dlVmV2ZxdStrMHlhVXhQOGNlcFBIRyt0bEFvR0FmQUtVVWhqeFU0Ym5vVzVwVUhKegpwWWZXZXZ5TW54NWZyT2VsSmRmNzlvNGMvMHhVSjh1eFBFWDFkRmNrZW96dHNpaVFTNkN6MENRY09XVWxtSkRwCnVrdERvVzM3VmNSQU1BVjY3NlgxQVZlM0UwNm5aL2g2Tkd4Z28rT042Q3pwL0lkMkJPUm9IMFAxa2RjY1NLT3kKMUtFZlNnb1B0c1N1eEpBZXdUZmxDMXc9Ci0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0K
110+
EOF
111+
```
112+
113+
To create the **access-to-cafe-secret** referencegrant, copy and paste the following into your terminal:
114+
115+
```yaml
116+
kubectl apply -f - <<EOF
117+
apiVersion: gateway.networking.k8s.io/v1beta1
118+
kind: ReferenceGrant
119+
metadata:
120+
name: access-to-cafe-secret
121+
namespace: certificate
122+
spec:
123+
to:
124+
- group: ""
125+
kind: Secret
126+
name: cafe-secret # if you omit this name, then Gateways in default namespace can access all Secrets in the certificate namespace
127+
from:
128+
- group: gateway.networking.k8s.io
129+
kind: Gateway
130+
namespace: default
131+
EOF
132+
```
133+
134+
To create the **cafe** gateway, copy and paste the following into your terminal:
135+
136+
```yaml
137+
kubectl apply -f - <<EOF
138+
apiVersion: gateway.networking.k8s.io/v1
139+
kind: Gateway
140+
metadata:
141+
name: cafe
142+
spec:
143+
gatewayClassName: nginx
144+
listeners:
145+
- name: http
146+
port: 80
147+
protocol: HTTP
148+
- name: https
149+
port: 443
150+
protocol: HTTPS
151+
tls:
152+
mode: Terminate
153+
certificateRefs:
154+
- kind: Secret
155+
name: cafe-secret
156+
namespace: certificate
157+
EOF
158+
```
159+
160+
This gateway configures:
161+
162+
- `http` listener for HTTP traffic
163+
- `https` listener for HTTPS traffic. It terminates TLS connections using the `cafe-secret` we created.
164+
165+
To create the httproute resources, copy and paste the following into your terminal:
166+
167+
```yaml
168+
kubectl apply -f - <<EOF
169+
apiVersion: gateway.networking.k8s.io/v1
170+
kind: HTTPRoute
171+
metadata:
172+
name: cafe-tls-redirect
173+
spec:
174+
parentRefs:
175+
- name: cafe
176+
sectionName: http
177+
hostnames:
178+
- "cafe.example.com"
179+
rules:
180+
- filters:
181+
- type: RequestRedirect
182+
requestRedirect:
183+
scheme: https
184+
port: 443
185+
---
186+
apiVersion: gateway.networking.k8s.io/v1
187+
kind: HTTPRoute
188+
metadata:
189+
name: coffee
190+
spec:
191+
parentRefs:
192+
- name: cafe
193+
sectionName: https
194+
hostnames:
195+
- "cafe.example.com"
196+
rules:
197+
- matches:
198+
- path:
199+
type: PathPrefix
200+
value: /coffee
201+
backendRefs:
202+
- name: coffee
203+
port: 80
204+
EOF
205+
```
206+
207+
The first route issues a `requestRedirect` from the `http` listener on port 80 to `https` on port 443. The second route binds the `coffee` route to the `https` listener.
208+
209+
## Send Traffic
210+
211+
Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our coffee application.
212+
213+
{{< 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 >}}
214+
215+
To test that NGINX sends an HTTPS redirect, we will send requests to the `coffee` service on the HTTP port. We
216+
will use curl's `--include` option to print the response headers (we are interested in the `Location` header).
217+
218+
```shell
219+
curl --resolve cafe.example.com:$GW_HTTP_PORT:$GW_IP http://cafe.example.com:$GW_HTTP_PORT/coffee --include
220+
```
221+
222+
```text
223+
HTTP/1.1 302 Moved Temporarily
224+
...
225+
Location: https://cafe.example.com/coffee
226+
...
227+
```
228+
229+
Now we will access the application over HTTPS. Since our certificate is self-signed, we will use curl's `--insecure`
230+
option to turn off certificate verification.
231+
232+
```shell
233+
curl --resolve cafe.example.com:$GW_HTTPS_PORT:$GW_IP https://cafe.example.com:$GW_HTTPS_PORT/coffee --insecure
234+
```
235+
236+
```text
237+
Server address: 10.244.0.6:80
238+
Server name: coffee-6b8b6d6486-7fc78
239+
```
240+
241+
## Further Reading
242+
243+
To learn more about redirects using the Gateway API, see the following resource:
244+
245+
- [Gateway API Redirects](https://gateway-api.sigs.k8s.io/guides/http-redirect-rewrite/)

0 commit comments

Comments
 (0)