Merge pull request #6138 from DharshanSR/envoy-doc

Add Envoy Gateway configuration and Backend TLS setup instructions for Kubernetes deployment

Author: himeshsiriwardana

en/includes/deploy/deploy-is-on-kubernetes.md

@@ -31,7 +31,21 @@ Make sure you have the following before starting this guide.
 
 - A running Kubernetes cluster (e.g. [minikube](https://kubernetes.io/docs/tasks/tools/#minikube){:target="_blank"} or an existing cluster).
 
-- A Kubernetes [Ingress-Nginx Controller](https://kubernetes.github.io/ingress-nginx/deploy/){:target="_blank"}.
+- One of the following Kubernetes traffic management options, depending on the deployment pattern you choose:
+
+    - **Option 1: Kubernetes Ingress pattern** — Install a Kubernetes [Ingress-Nginx Controller](https://kubernetes.github.io/ingress-nginx/deploy/){:target="_blank"}.
+
+    - **Option 2: Kubernetes Gateway API pattern** — Install Envoy Gateway. You must install the Envoy Gateway Controller with Experimental Features and Extension APIs enabled. These are required to support `BackendTLSPolicy` for secure backend communication and `EnvoyPatchPolicy` for session persistence.
+
+        ```
+        helm install envoy-gateway oci://docker.io/envoyproxy/gateway-helm \
+          --version v1.7.0 \
+          -n envoy-gateway-system \
+          --create-namespace \
+          --set envoyGateway.gateway.experimentalFeatures.enabled=true \
+          --set config.envoyGateway.extensionApis.enableBackend=true \
+          --set config.envoyGateway.extensionApis.enableEnvoyPatchPolicy=true
+        ```
 
 ## Step 1: Set up environment variables
 
@@ -199,7 +213,127 @@ If your hostname is backed by a DNS service, create a DNS record that maps the h
 <EXTERNAL-IP> wso2is.com
 ```
 
-## Step 7: Access {{product_name}}
+## Step 7: (Optional) Configure Backend TLS for Envoy Gateway
+
+!!! note
+    This step is only required if you are using Envoy Gateway.
+
+When using Envoy Gateway, the communication between the Gateway and the WSO2 Identity Server pods is secured via Backend TLS. To establish this trust, Envoy must verify the certificate presented by the WSO2 IS.
+
+You must provide a Kubernetes ConfigMap containing the CA certificate that signed the WSO2 IS TLS certificate.
+
+Follow the steps below to generate a self-signed CA certificate and sign the WSO2 IS Keystore certificate to ensure successful Backend TLS communication between Envoy and the backend Identity Server.
+
+!!! note
+    WSO2 Identity Server supports using multiple, purpose‑specific keystores — for example, separate keystores for Primary, Internal, and TLS use cases. In production it's recommended to maintain distinct keystores so that keys used for different functions (such as internal data encryption, token signing, and TLS communication) can be managed and rotated independently. For Backend TLS communication with Envoy Gateway, only the TLS keystore (which holds the certificate used for HTTPS/TLS connections) is required.
+
+### Step 7a: Generate a Self-Signed Certificate Authority (CA)
+
+First, create a private key and a self-signed root certificate to act as your internal CA.
+
+```shell
+# Generate CA private key
+openssl genrsa -out wso2carbon-ca.key 2048
+
+# Generate Root CA certificate
+openssl req -x509 -new -nodes -key wso2carbon-ca.key -sha256 -days 3650 \
+-out wso2carbon-ca.crt \
+-subj "/CN=WSO2 Carbon Internal CA/O=WSO2"
+```
+
+### Step 7b: Create a Server Configuration File
+
+To ensure the certificate is compatible with Envoy Gateway's strict validation, you must include the keyUsage and Subject Alternative Name (SAN). Create a file named `server.conf`.
+
+```
+[req]
+distinguished_name = req_distinguished_name
+req_extensions = v3_req
+prompt = no
+
+[req_distinguished_name]
+CN = localhost
+
+[v3_req]
+keyUsage = digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth
+subjectAltName = @alt_names
+
+[alt_names]
+DNS.1 = localhost
+```
+
+### Step 7c: Generate and Sign the WSO2 IS Certificate
+
+Generate a new private key for the WSO2 IS Keystore and sign the request using the CA created in Step 7a.
+
+```shell
+# Generate private key for WSO2 IS
+openssl genrsa -out wso2carbon.key 2048
+
+# Create a Certificate Signing Request (CSR)
+openssl req -new -key wso2carbon.key -out wso2carbon.csr -config server.conf
+
+# Sign the CSR with your Internal CA
+openssl x509 -req -in wso2carbon.csr \
+  -CA wso2carbon-ca.crt \
+  -CAkey wso2carbon-ca.key \
+  -CAcreateserial \
+  -out wso2carbon.crt \
+  -days 365 -sha256 \
+  -extfile server.conf \
+  -extensions v3_req
+```
+
+### Step 7d: Package into a PKCS12 Keystore
+
+WSO2 Identity Server prefers the PKCS12 format for its Keystore. Convert the certificate and key into a `.p12` file.
+
+```shell
+openssl pkcs12 -export -in wso2carbon.crt -inkey wso2carbon.key \
+  -out wso2carbon.p12 -name wso2carbon -passout pass:wso2carbon
+```
+
+### Step 7e: Import the CA Certificate into the Truststore
+
+To ensure that WSO2 Identity Server can trust the CA for TLS communication, you need to add the CA certificate to the client truststore. You can either use the truststore provided in the WSO2 product distribution (`client-truststore.p12`) or create your own. This allows WSO2 IS to validate certificates issued by the CA, including its own TLS certificate.
+
+```shell
+keytool -importcert \
+  -alias wso2carbon \
+  -file wso2carbon-ca.crt \
+  -keystore client-truststore.p12 \
+  -storetype PKCS12 \
+  -storepass wso2carbon \
+  -noprompt
+```
+
+### Step 7f: Create Kubernetes Resources
+
+Deploy the generated TLS Keystore and CA Certificate into the Kubernetes namespace.
+
+**I. Create TLS Keystore Secret**
+
+This secret contains the PKCS12 keystore used by the WSO2 Identity Server pods to secure their TLS communication.
+
+```shell
+kubectl create secret generic keystores \
+  --from-file=wso2carbon.p12 \
+  --from-file=client-truststore.p12 \
+  -n $NAMESPACE
+```
+
+**II. Create CA Bundle ConfigMap**
+
+This ConfigMap contains the Root CA certificate. Envoy Gateway uses this to verify the identity of the WSO2 IS pods during the TLS handshake.
+
+```shell
+kubectl create configmap wso2-ca-bundle \
+  --from-file=ca.crt=wso2carbon-ca.crt \
+  -n $NAMESPACE
+```
+
+## Step 8: Access {{product_name}}
 
 Once everything is set up, you can access WSO2 Identity Server using the following URLs:
 
@@ -208,4 +342,4 @@ Once everything is set up, you can access WSO2 Identity Server using the followi
 
 Congratulations! You have successfully deployed WSO2 Identity Server on Kubernetes using Helm.
 
-If you are deploying {{product_name}} on Azure Kubernetes Service (AKS) and require an advanced set up, refer to the relevant section in the [documentation](https://github.com/wso2/kubernetes-is/blob/master/README.md#advance-setup){:target = "_blank"}.
+If you are deploying {{product_name}} on Azure Kubernetes Service (AKS) and require an advanced setup, refer to the relevant section in the [documentation](https://github.com/wso2/kubernetes-is/blob/master/README.md#advance-setup){:target = "_blank"}.