Skip to content

Commit ab79f47

Browse files
zhaohuabingzirain
zhaohuabing
authored and
zirain
committed
docs: skipping TLS verification (envoyproxy#6653)
* docs for skipping TLS verification Signed-off-by: Huabing (Robin) Zhao <[email protected]> * remove btlsp for skiptlsverify Signed-off-by: Huabing (Robin) Zhao <[email protected]> * address comment Signed-off-by: Huabing (Robin) Zhao <[email protected]> * address comment Signed-off-by: Huabing (Robin) Zhao <[email protected]> * remove public Signed-off-by: Huabing (Robin) Zhao <[email protected]> --------- Signed-off-by: Huabing (Robin) Zhao <[email protected]>
1 parent 16046f3 commit ab79f47

File tree

1 file changed

+341
-0
lines changed

1 file changed

+341
-0
lines changed

‎site/content/en/latest/tasks/security/backend-skip-tls-verification.md‎

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
---
2+
title: "Backend TLS: Skip TLS Verification"
3+
---
4+
5+
This task demonstrates how to skip TLS verification for a backend service in Envoy Gateway.
6+
7+
By default, you must configure a [BackendTLSPolicy][] to validate the TLS certificate of a backend service when it uses TLS.
8+
9+
However, in certain scenarios—such as development or testing—you might want to skip TLS verification for a backend service.
10+
To do this, you can use the [Backend][] API and set the `tls.insecureSkipVerify` field to true in the [Backend][] resource.
11+
12+
Warning: Skipping TLS verification disables certificate validation, which can expose your connection to man-in-the-middle
13+
attacks. This setting is typically used only for development or testing and is not recommended in production environments.
14+
15+
## Prerequisites
16+
17+
- OpenSSL to generate TLS assets.
18+
19+
## Installation
20+
21+
{{< boilerplate prerequisites >}}
22+
23+
## Enable Backend
24+
25+
The [Backend][] API is disabled by default in Envoy Gateway. To enable it, follow the steps outlined in [Backend Routing][] to configure the [EnvoyGateway][] startup settings accordingly.
26+
27+
## TLS Certificates
28+
29+
Generate the certificates and keys used by the backend to terminate TLS connections from the Gateways.
30+
31+
Create a root certificate and private key to sign certificates:
32+
33+
```shell
34+
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout ca.key -out ca.crt
35+
```
36+
37+
Create a certificate and a private key for `www.example.com`.
38+
39+
First, create an openssl configuration file:
40+
41+
```shell
42+
cat > openssl.conf <<EOF
43+
[req]
44+
req_extensions = v3_req
45+
prompt = no
46+
47+
[v3_req]
48+
keyUsage = keyEncipherment, digitalSignature
49+
extendedKeyUsage = serverAuth
50+
subjectAltName = @alt_names
51+
[alt_names]
52+
DNS.1 = www.example.com
53+
EOF
54+
```
55+
56+
Then create a certificate using this openssl configuration file:
57+
58+
```shell
59+
openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization"
60+
openssl x509 -req -days 365 -CA ca.crt -CAkey ca.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt -extfile openssl.conf -extensions v3_req
61+
```
62+
63+
Note that the certificate must contain a DNS SAN for the relevant domain.
64+
65+
Store the cert/key in a Secret:
66+
67+
```shell
68+
kubectl create secret tls example-cert --key=www.example.com.key --cert=www.example.com.crt
69+
```
70+
71+
Store the CA Cert in another Secret:
72+
73+
```shell
74+
kubectl create configmap example-ca --from-file=ca.crt
75+
```
76+
77+
## Setup TLS on the backend
78+
79+
Patch the existing quickstart backend to enable TLS. The patch will mount the TLS certificate secret into the backend as volume.
80+
81+
```shell
82+
kubectl patch deployment backend --type=json --patch '
83+
- op: add
84+
path: /spec/template/spec/containers/0/volumeMounts
85+
value:
86+
- name: secret-volume
87+
mountPath: /etc/secret-volume
88+
- op: add
89+
path: /spec/template/spec/volumes
90+
value:
91+
- name: secret-volume
92+
secret:
93+
secretName: example-cert
94+
items:
95+
- key: tls.crt
96+
path: crt
97+
- key: tls.key
98+
path: key
99+
- op: add
100+
path: /spec/template/spec/containers/0/env/-
101+
value:
102+
name: TLS_SERVER_CERT
103+
value: /etc/secret-volume/crt
104+
- op: add
105+
path: /spec/template/spec/containers/0/env/-
106+
value:
107+
name: TLS_SERVER_PRIVKEY
108+
value: /etc/secret-volume/key
109+
'
110+
```
111+
112+
Create a service that exposes port 443 on the backend service.
113+
114+
{{< tabpane text=true >}}
115+
{{% tab header="Apply from stdin" %}}
116+
117+
```shell
118+
cat <<EOF | kubectl apply -f -
119+
apiVersion: v1
120+
kind: Service
121+
metadata:
122+
labels:
123+
app: backend
124+
service: backend
125+
name: tls-backend
126+
namespace: default
127+
spec:
128+
selector:
129+
app: backend
130+
ports:
131+
- name: https
132+
port: 443
133+
protocol: TCP
134+
targetPort: 8443
135+
EOF
136+
```
137+
138+
{{% /tab %}}
139+
{{% tab header="Apply from file" %}}
140+
Save and apply the following resource to your cluster:
141+
142+
```yaml
143+
---
144+
apiVersion: v1
145+
kind: Service
146+
metadata:
147+
labels:
148+
app: backend
149+
service: backend
150+
name: tls-backend
151+
namespace: default
152+
spec:
153+
selector:
154+
app: backend
155+
ports:
156+
- name: https
157+
port: 443
158+
protocol: TCP
159+
targetPort: 8443
160+
```
161+
162+
{{% /tab %}}
163+
{{< /tabpane >}}
164+
165+
## Skip TLS Verification
166+
167+
In the following example, we will create a [Backend][] resource that routes to the `tls-backend` service, and an [HTTPRoute][]
168+
that references the [Backend][] resource.
169+
170+
{{< tabpane text=true >}}
171+
{{% tab header="Apply from stdin" %}}
172+
173+
```shell
174+
cat <<EOF | kubectl apply -f -
175+
---
176+
apiVersion: gateway.networking.k8s.io/v1
177+
kind: HTTPRoute
178+
metadata:
179+
name: backend
180+
spec:
181+
parentRefs:
182+
- name: eg
183+
hostnames:
184+
- "www.example.com"
185+
rules:
186+
- backendRefs:
187+
- group: gateway.envoyproxy.io
188+
kind: Backend
189+
name: tls-backend
190+
matches:
191+
- path:
192+
type: PathPrefix
193+
value: /
194+
---
195+
apiVersion: gateway.envoyproxy.io/v1alpha1
196+
kind: Backend
197+
metadata:
198+
name: tls-backend
199+
namespace: default
200+
spec:
201+
endpoints:
202+
- fqdn:
203+
hostname: tls-backend.default.svc.cluster.local
204+
port: 443
205+
EOF
206+
```
207+
208+
{{% /tab %}}
209+
{{% tab header="Apply from file" %}}
210+
Save and apply the following resources to your cluster:
211+
212+
```yaml
213+
---
214+
apiVersion: gateway.networking.k8s.io/v1
215+
kind: HTTPRoute
216+
metadata:
217+
name: backend
218+
spec:
219+
parentRefs:
220+
- name: eg
221+
hostnames:
222+
- "www.example.com"
223+
rules:
224+
- backendRefs:
225+
- group: gateway.envoyproxy.io
226+
kind: Backend
227+
name: tls-backend
228+
matches:
229+
- path:
230+
type: PathPrefix
231+
value: /
232+
---
233+
apiVersion: gateway.envoyproxy.io/v1alpha1
234+
kind: Backend
235+
metadata:
236+
name: tls-backend
237+
namespace: default
238+
spec:
239+
endpoints:
240+
- fqdn:
241+
hostname: tls-backend.default.svc.cluster.local
242+
port: 443
243+
```
244+
245+
{{% /tab %}}
246+
{{< /tabpane >}}
247+
248+
Send a request to the backend service:
249+
250+
```shell
251+
curl -v -HHost:www.example.com --resolve "www.example.com:80:${GATEWAY_HOST}" \
252+
http://www.example.com:80/get
253+
```
254+
255+
Because the backend service is using TLS, and no [BackendTLSPolicy][] is configured to validate the TLS certificate,
256+
the request will fail with a `400 Bad Request` error:
257+
258+
```bash
259+
* Connected to www.example.com (172.18.0.200) port 80
260+
* using HTTP/1.x
261+
> GET /get HTTP/1.1
262+
> Host:www.example.com
263+
> User-Agent: curl/8.14.1
264+
> Accept: */*
265+
>
266+
* Request completely sent off
267+
< HTTP/1.1 400 Bad Request
268+
< date: Thu, 31 Jul 2025 06:09:51 GMT
269+
< transfer-encoding: chunked
270+
```
271+
272+
Disabling TLS verification by setting the `InsecureSkipVerify` field to `true` allows the request to succeed:
273+
274+
{{< tabpane text=true >}}
275+
{{% tab header="Apply from stdin" %}}
276+
277+
```shell
278+
cat <<EOF | kubectl apply -f -
279+
apiVersion: gateway.envoyproxy.io/v1alpha1
280+
kind: Backend
281+
metadata:
282+
name: tls-backend
283+
namespace: default
284+
spec:
285+
endpoints:
286+
- fqdn:
287+
hostname: tls-backend.default.svc.cluster.local
288+
port: 443
289+
tls:
290+
insecureSkipVerify: true
291+
EOF
292+
```
293+
294+
{{% /tab %}}
295+
{{% tab header="Apply from file" %}}
296+
```yaml
297+
apiVersion: gateway.envoyproxy.io/v1alpha1
298+
kind: Backend
299+
metadata:
300+
name: tls-backend
301+
namespace: default
302+
spec:
303+
endpoints:
304+
- fqdn:
305+
hostname: tls-backend.default.svc.cluster.local
306+
port: 443
307+
tls:
308+
insecureSkipVerify: true
309+
```
310+
311+
{{% /tab %}}
312+
{{< /tabpane >}}
313+
314+
Send the request again:
315+
316+
```shell
317+
curl -v -HHost:www.example.com --resolve "www.example.com:80:${GATEWAY_HOST}" \
318+
http://www.example.com:80/get
319+
```
320+
321+
You should now see a successful response from the backend service. Since TLS verification has been skipped, the request
322+
proceeds without validating the backend’s TLS certificate. The response will include TLS details such as the protocol
323+
version and cipher suite used for the connection.
324+
325+
326+
```shell
327+
< HTTP/1.1 200 OK
328+
[...]
329+
"tls": {
330+
"version": "TLSv1.2",
331+
"serverName": "",
332+
"negotiatedProtocol": "http/1.1",
333+
"cipherSuite": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
334+
}
335+
```
336+
337+
[Backend Routing]: ../traffic/backend/#enable-backend
338+
[Backend]: ../../../api/extension_types#backend
339+
[EnvoyGateway]: ../../../api/extension_types#envoygateway
340+
[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute
341+
[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/

0 commit comments

Comments
 (0)