Skip to content

Commit

Permalink
docs: update BackendTLSPolicy docs (envoyproxy#4868)
Browse files Browse the repository at this point in the history
update btlsp docs

Signed-off-by: Huabing Zhao <[email protected]>
  • Loading branch information
zhaohuabing authored Dec 10, 2024
1 parent 9ef758b commit e5f1550
Show file tree
Hide file tree
Showing 3 changed files with 36 additions and 24 deletions.
20 changes: 12 additions & 8 deletions site/content/en/docs/tasks/security/backend-tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][].

## TLS Certificates

Generate the certificates and keys used by the backend to terminate TLS connections from the Gateways.
Generate the certificates and keys used by the backend to terminate TLS connections from the Gateways.

Create a root certificate and private key to sign certificates:

Expand Down Expand Up @@ -67,7 +67,7 @@ kubectl create configmap example-ca --from-file=ca.crt

## Setup TLS on the backend

Patch the existing quickstart backend to enable TLS. The patch will mount the TLS certificate secret into the backend as volume.
Patch the existing quickstart backend to enable TLS. The patch will mount the TLS certificate secret into the backend as volume.

```shell
kubectl patch deployment backend --type=json --patch '
Expand Down Expand Up @@ -100,7 +100,7 @@ kubectl patch deployment backend --type=json --patch '
'
```

Create a service that exposes port 443 on the backend service.
Create a service that exposes port 443 on the backend service.

{{< tabpane text=true >}}
{{% tab header="Apply from stdin" %}}
Expand Down Expand Up @@ -155,6 +155,9 @@ spec:
Create a [BackendTLSPolicy][] instructing Envoy Gateway to establish a TLS connection with the backend and validate the backend certificate is issued by a trusted CA and contains an appropriate DNS SAN.
Note: SectionName is an optional field that specifies the name of the port in the target backend. This example uses a Kubernetes Service as the backend target, so the sectionName is set to `https` to match the port name in the Service.
If the target is a [Backend] resource, the `sectionName` field should be set to the port number of the backend.

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

Expand All @@ -170,7 +173,7 @@ spec:
- group: ''
kind: Service
name: tls-backend
sectionName: "443"
sectionName: https
validation:
caCertificateRefs:
- name: example-ca
Expand All @@ -196,7 +199,7 @@ spec:
- group: ''
kind: Service
name: tls-backend
sectionName: "443"
sectionName: https
validation:
caCertificateRefs:
- name: example-ca
Expand Down Expand Up @@ -298,8 +301,8 @@ Inspect the output and see that the response contains the details of the TLS han

## 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.
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:

Expand Down Expand Up @@ -390,7 +393,7 @@ 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.
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
Expand All @@ -406,3 +409,4 @@ The TLS version is now TLS1.3, as configured in the EnvoyProxy resource. The TLS

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

## TLS Certificates

Generate the certificates and keys used by the backend to terminate TLS connections from the Gateways.
Generate the certificates and keys used by the backend to terminate TLS connections from the Gateways.

Create a root certificate and private key to sign certificates:

Expand Down Expand Up @@ -67,7 +67,7 @@ kubectl create configmap example-ca --from-file=ca.crt

## Setup TLS on the backend

Patch the existing quickstart backend to enable TLS. The patch will mount the TLS certificate secret into the backend as volume.
Patch the existing quickstart backend to enable TLS. The patch will mount the TLS certificate secret into the backend as volume.

```shell
kubectl patch deployment backend --type=json --patch '
Expand Down Expand Up @@ -100,7 +100,7 @@ kubectl patch deployment backend --type=json --patch '
'
```

Create a service that exposes port 443 on the backend service.
Create a service that exposes port 443 on the backend service.

{{< tabpane text=true >}}
{{% tab header="Apply from stdin" %}}
Expand Down Expand Up @@ -155,6 +155,9 @@ spec:
Create a [BackendTLSPolicy][] instructing Envoy Gateway to establish a TLS connection with the backend and validate the backend certificate is issued by a trusted CA and contains an appropriate DNS SAN.
Note: SectionName is an optional field that specifies the name of the port in the target backend. This example uses a Kubernetes Service as the backend target, so the sectionName is set to `https` to match the port name in the Service.
If the target is a [Backend] resource, the `sectionName` field should be set to the port number of the backend.

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

Expand All @@ -170,7 +173,7 @@ spec:
- group: ''
kind: Service
name: tls-backend
sectionName: "443"
sectionName: https
validation:
caCertificateRefs:
- name: example-ca
Expand All @@ -196,7 +199,7 @@ spec:
- group: ''
kind: Service
name: tls-backend
sectionName: "443"
sectionName: https
validation:
caCertificateRefs:
- name: example-ca
Expand Down Expand Up @@ -298,8 +301,8 @@ Inspect the output and see that the response contains the details of the TLS han

## 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.
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:

Expand Down Expand Up @@ -390,7 +393,7 @@ 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.
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
Expand All @@ -406,3 +409,4 @@ The TLS version is now TLS1.3, as configured in the EnvoyProxy resource. The TLS

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

## TLS Certificates

Generate the certificates and keys used by the backend to terminate TLS connections from the Gateways.
Generate the certificates and keys used by the backend to terminate TLS connections from the Gateways.

Create a root certificate and private key to sign certificates:

Expand Down Expand Up @@ -67,7 +67,7 @@ kubectl create configmap example-ca --from-file=ca.crt

## Setup TLS on the backend

Patch the existing quickstart backend to enable TLS. The patch will mount the TLS certificate secret into the backend as volume.
Patch the existing quickstart backend to enable TLS. The patch will mount the TLS certificate secret into the backend as volume.

```shell
kubectl patch deployment backend --type=json --patch '
Expand Down Expand Up @@ -100,7 +100,7 @@ kubectl patch deployment backend --type=json --patch '
'
```

Create a service that exposes port 443 on the backend service.
Create a service that exposes port 443 on the backend service.

{{< tabpane text=true >}}
{{% tab header="Apply from stdin" %}}
Expand Down Expand Up @@ -155,6 +155,9 @@ spec:
Create a [BackendTLSPolicy][] instructing Envoy Gateway to establish a TLS connection with the backend and validate the backend certificate is issued by a trusted CA and contains an appropriate DNS SAN.
Note: SectionName is an optional field that specifies the name of the port in the target backend. This example uses a Kubernetes Service as the backend target, so the sectionName is set to `https` to match the port name in the Service.
If the target is a [Backend] resource, the `sectionName` field should be set to the port number of the backend.

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

Expand All @@ -170,7 +173,7 @@ spec:
- group: ''
kind: Service
name: tls-backend
sectionName: "443"
sectionName: https
validation:
caCertificateRefs:
- name: example-ca
Expand All @@ -196,7 +199,7 @@ spec:
- group: ''
kind: Service
name: tls-backend
sectionName: "443"
sectionName: https
validation:
caCertificateRefs:
- name: example-ca
Expand Down Expand Up @@ -298,8 +301,8 @@ Inspect the output and see that the response contains the details of the TLS han

## 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.
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:

Expand Down Expand Up @@ -390,7 +393,7 @@ 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.
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
Expand All @@ -406,3 +409,4 @@ The TLS version is now TLS1.3, as configured in the EnvoyProxy resource. The TLS

[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
[EnvoyProxy]: ../../api/extension_types#envoyproxy
[Backend]: ../../api/extension_types#backend

0 comments on commit e5f1550

Please sign in to comment.