Skip to content

Commit

Permalink
docs: add backend tls docs (envoyproxy#3843)
Browse files Browse the repository at this point in the history
* add backend tls docs

Signed-off-by: Guy Daich <[email protected]>

* fix links

Signed-off-by: Guy Daich <[email protected]>

* add gateway paramsref

Signed-off-by: Guy Daich <[email protected]>

* nit

Signed-off-by: Guy Daich <[email protected]>

---------

Signed-off-by: Guy Daich <[email protected]>
  • Loading branch information
guydc authored Jul 16, 2024
1 parent e2088cc commit 0ec17ab
Show file tree
Hide file tree
Showing 4 changed files with 321 additions and 7 deletions.
5 changes: 3 additions & 2 deletions site/content/en/docs/tasks/security/backend-tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][].

## Installation

Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest.
Follow the steps from the [Quickstart][] to install Envoy Gateway and the example manifest.

## TLS Certificates

Expand All @@ -28,7 +28,7 @@ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example In
Create a certificate and a private key for `www.example.com`:

```shell
openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization"
openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" -addext "subjectAltName = DNS:www.example.com"
openssl x509 -req -days 365 -CA ca.crt -CAkey ca.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt
```

Expand Down Expand Up @@ -209,4 +209,5 @@ Inspect the output and see that the response contains the details of the TLS han
}
```

[Quickstart]: ../quickstart
[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
200 changes: 200 additions & 0 deletions site/content/en/latest/tasks/security/backend-mtls.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
---
title: "Backend Mutual TLS: Gateway to Backend"
---

This task demonstrates how mTLS can be achieved between the Gateway and a backend.
This task uses a self-signed CA, so it should be used for testing and demonstration purposes only.

Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][] to establish TLS. For mTLS, the Gateway must authenticate by presenting a client certificate to the backend.

## Prerequisites

- OpenSSL to generate TLS assets.

## Installation

Follow the steps from the [Backend TLS][] to install Envoy Gateway and configure TLS to the backend server.

## TLS Certificates

Generate the certificates and keys used by the Gateway for authentication against the backend.

Create a root certificate and private key to sign certificates:

```shell
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout clientca.key -out clientca.crt
```

Create a certificate and a private key for `www.example.com`:

```shell
openssl req -new -newkey rsa:2048 -nodes -keyout client.key -out client.csr -subj "/CN=example-client/O=example organization"
openssl x509 -req -days 365 -CA clientca.crt -CAkey clientca.key -set_serial 0 -in client.csr -out client.crt
```

Store the cert/key in a Secret:

```shell
kubectl -n envoy-gateway-system create secret tls example-client-cert --key=client.key --cert=client.crt
```

Store the CA Cert in another Secret:

```shell
kubectl create configmap example-client-ca --from-file=clientca.crt
```

## Enforce Client Certificate Authentication on the backend

Patch the existing quickstart backend to enforce Client Certificate Authentication. The patch will mount the server certificate and key required for TLS, and the CA certificate into the backend as volumes.

```shell
kubectl patch deployment backend --type=json --patch '
- op: add
path: /spec/template/spec/containers/0/volumeMounts
value:
- name: client-certs-volume
mountPath: /etc/client-certs
- name: secret-volume
mountPath: /etc/secret-volume
- op: add
path: /spec/template/spec/volumes
value:
- name: client-certs-volume
configMap:
name: example-client-ca
items:
- key: clientca.crt
path: crt
- name: secret-volume
secret:
secretName: example-cert
items:
- key: tls.crt
path: crt
- key: tls.key
path: key
- op: add
path: /spec/template/spec/containers/0/env/-
value:
name: TLS_CLIENT_CACERTS
value: /etc/client-certs/crt
'
```

## Configure Envoy Proxy to use a client certificate

In addition to enablement of backend TLS with the Gateway-API BackendTLSPolicy, Envoy Gateway supports customizing TLS parameters such as TLS Client Certificate.
To achieve this, the [EnvoyProxy][] resource can be used to specify a TLS Client Certificate.

First, you need to add ParametersRef in GatewayClass, and refer to EnvoyProxy Config:

{{< tabpane text=true >}}
{{% tab header="Apply from stdin" %}}

```shell
cat <<EOF | kubectl apply -f -
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: eg
spec:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
parametersRef:
group: gateway.envoyproxy.io
kind: EnvoyProxy
name: custom-proxy-config
namespace: envoy-gateway-system
EOF
```

{{% /tab %}}
{{% tab header="Apply from file" %}}
Save and apply the following resource to your cluster:

```yaml
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: eg
spec:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
parametersRef:
group: gateway.envoyproxy.io
kind: EnvoyProxy
name: custom-proxy-config
namespace: envoy-gateway-system
```
{{% /tab %}}
{{< /tabpane >}}
{{< tabpane text=true >}}
{{% tab header="Apply from stdin" %}}
```shell
cat <<EOF | kubectl apply -f -
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
name: custom-proxy-config
namespace: envoy-gateway-system
spec:
backendTLS:
clientCertificateRef:
kind: Secret
name: example-client-cert
namespace: envoy-gateway-system
EOF
```

{{% /tab %}}
{{% tab header="Apply from file" %}}
Save and apply the following resource to your cluster:

```yaml
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
name: custom-proxy-config
namespace: envoy-gateway-system
spec:
backendTLS:
clientCertificateRef:
kind: Secret
name: example-client-cert
namespace: envoy-gateway-system
```
{{% /tab %}}
{{< /tabpane >}}
## Testing mTLS
Query the TLS-enabled backend through Envoy proxy:
```shell
curl -v -HHost:www.example.com --resolve "www.example.com:80:127.0.0.1" \
http://www.example.com:80/get
```

Inspect the output and see that the response contains the details of the TLS handshake between Envoy and the backend.
The response now contains a "peerCertificates" attribute that reflects the client certificate used by the Gateway to establish mTLS with the backend.

```shell
< HTTP/1.1 200 OK
[...]
"tls": {
"version": "TLSv1.2",
"serverName": "www.example.com",
"negotiatedProtocol": "http/1.1",
"cipherSuite": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
"peerCertificates": ["-----BEGIN CERTIFICATE-----\n[...]-----END CERTIFICATE-----\n"]
}
```

[Backend TLS]: ./backend-tls
[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
[EnvoyProxy]: ../../api/extension_types#envoyproxy
118 changes: 115 additions & 3 deletions site/content/en/latest/tasks/security/backend-tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][].

## Installation

Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest.
Follow the steps from the [Quickstart][] to install Envoy Gateway and the example manifest.

## TLS Certificates

Expand All @@ -28,10 +28,12 @@ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example In
Create a certificate and a private key for `www.example.com`:

```shell
openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization"
openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" -addext "subjectAltName = DNS:www.example.com"
openssl x509 -req -days 365 -CA ca.crt -CAkey ca.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt
```

Note that the certificate must contain a DNS SAN for the relevant domain.

Store the cert/key in a Secret:

```shell
Expand Down Expand Up @@ -206,7 +208,7 @@ Verify the HTTPRoute status:
kubectl get HTTPRoute backend -o yaml
```
## Testing
## Testing backend TLS
{{< tabpane text=true >}}
{{% tab header="With External LoadBalancer Support" %}}
Expand Down Expand Up @@ -275,4 +277,114 @@ Inspect the output and see that the response contains the details of the TLS han
{{% /tab %}}
{{< /tabpane >}}

## Customize backend TLS Parameters

In addition to enablement of backend TLS with the Gateway-API BackendTLSPolicy, Envoy Gateway supports customizing TLS parameters.
To achieve this, the [EnvoyProxy][] resource can be used to specify TLS parameters. We will customize the TLS version in this example.

First, you need to add ParametersRef in GatewayClass, and refer to EnvoyProxy Config:

{{< tabpane text=true >}}
{{% tab header="Apply from stdin" %}}

```shell
cat <<EOF | kubectl apply -f -
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: eg
spec:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
parametersRef:
group: gateway.envoyproxy.io
kind: EnvoyProxy
name: custom-proxy-config
namespace: envoy-gateway-system
EOF
```

{{% /tab %}}
{{% tab header="Apply from file" %}}
Save and apply the following resource to your cluster:

```yaml
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: eg
spec:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
parametersRef:
group: gateway.envoyproxy.io
kind: EnvoyProxy
name: custom-proxy-config
namespace: envoy-gateway-system
```
{{% /tab %}}
{{< /tabpane >}}
You can customize the EnvoyProxy Backend TLS Parameters via EnvoyProxy Config like:
{{< tabpane text=true >}}
{{% tab header="Apply from stdin" %}}
```shell
cat <<EOF | kubectl apply -f -
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
name: custom-proxy-config
namespace: envoy-gateway-system
spec:
backendTLS:
minVersion: "1.3"
EOF
```

{{% /tab %}}
{{% tab header="Apply from file" %}}
Save and apply the following resource to your cluster:

```yaml
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
name: custom-proxy-config
namespace: envoy-gateway-system
spec:
backendTLS:
MinVersion: "1.3"
```
{{% /tab %}}
{{< /tabpane >}}
## Testing TLS Parameters
Query the TLS-enabled backend through Envoy proxy:
```shell
curl -v -HHost:www.example.com --resolve "www.example.com:80:127.0.0.1" \
http://www.example.com:80/get
```

Inspect the output and see that the response contains the details of the TLS handshake between Envoy and the backend.
The TLS version is now TLS1.3, as configured in the EnvoyProxy resource. The TLS cipher is also changed, since TLS1.3 supports different ciphers from TLS1.2.

```shell
< HTTP/1.1 200 OK
[...]
"tls": {
"version": "TLSv1.3",
"serverName": "www.example.com",
"negotiatedProtocol": "http/1.1",
"cipherSuite": "TLS_AES_128_GCM_SHA256"
}
```

[Quickstart]: ../quickstart
[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
[EnvoyProxy]: ../../api/extension_types#envoyproxy
5 changes: 3 additions & 2 deletions site/content/en/v1.0/tasks/security/backend-tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][].

## Installation

Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest.
Follow the steps from the [Quickstart][] to install Envoy Gateway and the example manifest.

## TLS Certificates

Expand All @@ -28,7 +28,7 @@ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example In
Create a certificate and a private key for `www.example.com`:

```shell
openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization"
openssl req -out www.example.com.csr -newkey rsa:2048 -nodes -keyout www.example.com.key -subj "/CN=www.example.com/O=example organization" -addext "subjectAltName = DNS:www.example.com"
openssl x509 -req -days 365 -CA ca.crt -CAkey ca.key -set_serial 0 -in www.example.com.csr -out www.example.com.crt
```

Expand Down Expand Up @@ -209,4 +209,5 @@ Inspect the output and see that the response contains the details of the TLS han
}
```

[Quickstart]: ../quickstart
[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/

0 comments on commit 0ec17ab

Please sign in to comment.