docs: per backend client cert (#7341)

* docs for per backend client cert

Signed-off-by: Huabing Zhao <[email protected]>

Author: zhaohuabing

site/content/en/latest/tasks/security/backend-mtls.md

@@ -13,26 +13,26 @@ Envoy Gateway supports the Gateway-API defined [BackendTLSPolicy][] to establish
 
 ## Installation
 
-Follow the steps from the [Backend TLS][] to install Envoy Gateway and configure TLS to the backend server. 
+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. 
+Generate the client certificate and key used by the Gateway for authentication against the backend.
 
-Create a root certificate and private key to sign certificates:
+Create a root certificate and private key to sign the client certificate:
 
 ```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`:
+Create the client 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:
+Store the the client cert/key in a Secret:
 
 ```shell
 kubectl -n envoy-gateway-system create secret tls example-client-cert --key=client.key --cert=client.crt
@@ -46,7 +46,7 @@ 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. 
+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 '
@@ -56,7 +56,7 @@ kubectl patch deployment backend --type=json --patch '
     - name: client-certs-volume
       mountPath: /etc/client-certs
     - name: secret-volume
-      mountPath: /etc/secret-volume      
+      mountPath: /etc/secret-volume
   - op: add
     path: /spec/template/spec/volumes
     value:
@@ -73,7 +73,7 @@ kubectl patch deployment backend --type=json --patch '
         - key: tls.crt
           path: crt
         - key: tls.key
-          path: key          
+          path: key
   - op: add
     path: /spec/template/spec/containers/0/env/-
     value:
@@ -82,12 +82,19 @@ kubectl patch deployment backend --type=json --patch '
   '
 ```
 
-## Configure Envoy Proxy to use a client certificate 
+## 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.
+Envoy Gateway supports two ways to configure client certificates for backend mTLS.
+* Configure the [EnvoyProxy][] resource to specify a client certificate globally.
+* Configure a [Backend][] resource to specify a client certificate per backend.
 
-First, you need to add ParametersRef in GatewayClass, and refer to EnvoyProxy Config:
+### Configure EnvoyProxy
+
+The [EnvoyProxy][] resource can be used to specify a client certificate globally for a GatewayClass or Gateway.
+
+The following example shows how to configure a GatewayClass to reference an EnvoyProxy resource with a client certificate.
+
+First, add a parametersRef field in the GatewayClass to reference the EnvoyProxy configuration:
 
 {{< tabpane text=true >}}
 {{% tab header="Apply from stdin" %}}
@@ -142,7 +149,7 @@ metadata:
   namespace: envoy-gateway-system
 spec:
   backendTLS:
-    clientCertificateRef: 
+    clientCertificateRef:
       kind: Secret
       name: example-client-cert
       namespace: envoy-gateway-system
@@ -171,6 +178,151 @@ spec:
 {{% /tab %}}
 {{< /tabpane >}}
 
+### Configure a Backend Resource
+
+When multiple backends require distinct client certificates, configure each one using a dedicated [Backend][] resource that includes its own client certificate reference.
+TLS settings defined in the Backend resource take precedence over the defaults set in EnvoyProxy.backendTLS.
+
+Before creating Backend resources, make sure the Backend API is enabled in the Envoy Gateway configuration (see [Backend Routing](../traffic/backend#enable-backend) for full details). If it is not already enabled, update the `envoy-gateway-config` ConfigMap as shown below:
+
+{{< tabpane text=true >}}
+{{% tab header="Apply from stdin" %}}
+
+```shell
+cat <<EOF | kubectl apply -f -
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: envoy-gateway-config
+  namespace: envoy-gateway-system
+data:
+  envoy-gateway.yaml: |
+    apiVersion: gateway.envoyproxy.io/v1alpha1
+    kind: EnvoyGateway
+    provider:
+      type: Kubernetes
+    gateway:
+      controllerName: gateway.envoyproxy.io/gatewayclass-controller
+    extensionApis:
+      enableBackend: true
+EOF
+```
+
+{{% /tab %}}
+{{% tab header="Apply from file" %}}
+Save and apply the following resource to your cluster:
+
+```yaml
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: envoy-gateway-config
+  namespace: envoy-gateway-system
+data:
+  envoy-gateway.yaml: |
+    apiVersion: gateway.envoyproxy.io/v1alpha1
+    kind: EnvoyGateway
+    provider:
+      type: Kubernetes
+    gateway:
+      controllerName: gateway.envoyproxy.io/gatewayclass-controller
+    extensionApis:
+      enableBackend: true
+```
+
+{{% /tab %}}
+{{< /tabpane >}}
+
+{{< boilerplate rollout-envoy-gateway >}}
+
+Roll out the updated Envoy Gateway deployment:
+
+```shell
+kubectl -n envoy-gateway-system rollout restart deployment envoy-gateway
+```
+
+Create the client certificate secret in the backend namespace (reusing the same certificate and key generated earlier):
+
+```shell
+kubectl -n default create secret tls example-client-cert --key=client.key --cert=client.crt
+```
+
+Define the backend and include both the trust anchor and the client credentials:
+
+{{< tabpane text=true >}}
+{{% tab header="Apply from stdin" %}}
+
+```shell
+cat <<EOF | kubectl apply -f -
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: Backend
+metadata:
+  name: tls-backend-client-cert
+  namespace: default
+spec:
+  endpoints:
+  - fqdn:
+      hostname: tls-backend.default.svc.cluster.local
+      port: 443
+  tls:
+    clientCertificateRef:
+      kind: Secret
+      name: example-client-cert
+    caCertificateRefs:
+    - group: ""
+      kind: ConfigMap
+      name: example-ca
+EOF
+```
+
+{{% /tab %}}
+{{% tab header="Apply from file" %}}
+Save and apply the following resource to your cluster:
+
+```yaml
+---
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: Backend
+metadata:
+  name: tls-backend-client-cert
+  namespace: default
+spec:
+  endpoints:
+  - fqdn:
+      hostname: tls-backend.default.svc.cluster.local
+      port: 443
+  tls:
+    clientCertificateRef:
+      kind: Secret
+      name: example-client-cert
+    caCertificateRefs:
+    - group: ""
+      kind: ConfigMap
+      name: example-ca
+```
+
+{{% /tab %}}
+{{< /tabpane >}}
+
+Update the HTTPRoute to reference the backend instead of the Kubernetes Service:
+
+```shell
+kubectl patch HTTPRoute backend --type=json --patch '
+  - op: replace
+    path: /spec/rules/0/backendRefs/0/group
+    value: gateway.envoyproxy.io
+  - op: replace
+    path: /spec/rules/0/backendRefs/0/kind
+    value: Backend
+  - op: replace
+    path: /spec/rules/0/backendRefs/0/name
+    value: tls-backend-client-cert
+  - op: remove
+    path: /spec/rules/0/backendRefs/0/port
+  '
+```
+
 ## Testing mTLS
 
 Query the TLS-enabled backend through Envoy proxy:
@@ -180,8 +332,8 @@ 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. 
+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
@@ -197,4 +349,5 @@ The response now contains a "peerCertificates" attribute that reflects the clien
 
 [Backend TLS]: ./backend-tls
 [BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
-[EnvoyProxy]: ../../api/extension_types#envoyproxy
+[EnvoyProxy]: ../../api/extension_types#envoyproxy
+[Backend]: ../../api/extension_types#backend