Add user docs for EnvoyPatchPolicy

Relates to envoyproxy#24

Signed-off-by: Arko Dasgupta <arko@tetrate.io>

docs/latest/user/envoy-patch-policy.md

@@ -0,0 +1,109 @@
+# Envoy Patch Policy
+
+This guide explains the usage of the [EnvoyPatchPolicy][] API.
+__Note:__ This API is meant for users extremely familiar with Envoy [xDS][] semantics.
+Also before considering this API for production use cases, please be aware that this API
+is unstable and the outcome may change across versions. Use at your own risk.
+
+## Introduction
+
+The [EnvoyPatchPolicy][] API allows user to modify the output [xDS][]
+configuration generated by Envoy Gateway intended for EnvoyProxy, 
+using [JSON Patch][] semantics.
+
+## Motivation
+
+This API was introduced to allow advanced users to be able to leverage Envoy Proxy functionality
+not exposed by Envoy Gateway APIs today.
+
+## Installation
+
+### Prerequistes
+
+#### Enable EnvoyPatchPolicy
+
+* By default EnvoyPatchPolicy][] is disabled. Lets enable it in the [EnvoyGateway][] startup configuration
+
+* The default installation of Envoy Gateway installs a default [EnvoyGateway][] configuration and attaches it
+using a `ConfigMap`. In the next step, we will update this resource to enable EnvoyPatchPolicy. 
+
+
+```shell
+cat <<EOF | kubectl apply -f -
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: envoy-gateway-config
+  namespace: envoy-gateway-system
+data:
+  envoy-gateway.yaml: |
+    apiVersion: config.gateway.envoyproxy.io/v1alpha1
+    kind: EnvoyGateway
+    provider:
+      type: Kubernetes
+    gateway:
+      controllerName: gateway.envoyproxy.io/gatewayclass-controller
+    extensionAPIs:
+      enableEnvoyPatchPolicy: true
+EOF
+```
+
+* After updating the `ConfigMap`, you will need to restart the `envoy-gateway` deployment so the configuration kicks in
+
+```shell
+kubectl rollout restart deployment envoy-gateway -n envoy-gateway-system
+```
+
+#### Quickstart
+
+* Follow the steps from the [Quickstart](quickstart.md) guide to install Envoy Gateway and the example manifest.
+Before proceeding, you should be able to query the example backend using HTTP.
+
+## Customize Response
+
+* Lets use EnvoyProxy's [Local Reply Modification][] feature to return a custom response back to the client when
+the status code is `404`
+
+* Lets apply the configuration
+
+```shell
+cat <<EOF | kubectl apply -f -
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyPatchPolicy
+metadata:
+  name: ratelimit-patch-policy
+  namespace: default
+spec:
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    name: eg
+    namespace: default
+  type: JSONPatch
+  jsonPatches:
+    - type: "type.googleapis.com/envoy.config.listener.v3.Listener"
+      # The listener name is of the form <GatewayNamespace>/<GatewayName>/<GatewayListenerName>
+      name: default/eg/http
+      operation:
+        op: add
+        path: "/default_filter_chain/filters/0/typed_config"
+        value:
+          local_reply_config:
+            mappers:
+            - filter:
+                status_code_filter:
+                  comparison:
+                   op: EQ
+                   value:
+                     default_value: 404
+                     runtime_key: key_b
+              body:
+                inline_string: "could not find what you are looking for"
+EOF
+```
+
+[EnvoyPatchPolicy]: https://gateway.envoyproxy.io/latest/api/extension_types.html#envoypatchpolicy
+[EnvoyGateway]: https://gateway.envoyproxy.io/latest/api/config_types.html#envoygateway
+[JSON Patch]: https://datatracker.ietf.org/doc/html/rfc6902
+[xDS]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/operations/dynamic_configuration
+[Local Reply Modification]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/local_reply

docs/latest/user_docs.rst

@@ -23,6 +23,7 @@ Learn how to deploy, use, and operate Envoy Gateway.
   user/grpc-routing
   user/authn
   user/rate-limit
+  user/envoy-patch-policy
   user/egctl
   user/customize-envoyproxy
   user/deployment-mode