From 256ae03dfaf7ba3526285801425eb005f174b246 Mon Sep 17 00:00:00 2001 From: Arko Dasgupta Date: Mon, 31 Jul 2023 13:12:30 -0700 Subject: [PATCH 1/5] Add user docs for EnvoyPatchPolicy Relates to https://github.com/envoyproxy/gateway/issues/24 Signed-off-by: Arko Dasgupta --- docs/latest/user/envoy-patch-policy.md | 109 +++++++++++++++++++++++++ docs/latest/user_docs.rst | 1 + 2 files changed, 110 insertions(+) create mode 100644 docs/latest/user/envoy-patch-policy.md diff --git a/docs/latest/user/envoy-patch-policy.md b/docs/latest/user/envoy-patch-policy.md new file mode 100644 index 0000000000..e13a0e548d --- /dev/null +++ b/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 <// + 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 diff --git a/docs/latest/user_docs.rst b/docs/latest/user_docs.rst index faa4875c4e..eb0fb7714b 100644 --- a/docs/latest/user_docs.rst +++ b/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 From 3672bda42ae642ec83dada01753fd4c4f6286046 Mon Sep 17 00:00:00 2001 From: Arko Dasgupta Date: Mon, 31 Jul 2023 13:37:11 -0700 Subject: [PATCH 2/5] nits Signed-off-by: Arko Dasgupta --- docs/latest/user/envoy-patch-policy.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/latest/user/envoy-patch-policy.md b/docs/latest/user/envoy-patch-policy.md index e13a0e548d..0154052152 100644 --- a/docs/latest/user/envoy-patch-policy.md +++ b/docs/latest/user/envoy-patch-policy.md @@ -20,6 +20,11 @@ not exposed by Envoy Gateway APIs today. ### Prerequistes +#### 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. + #### Enable EnvoyPatchPolicy * By default EnvoyPatchPolicy][] is disabled. Lets enable it in the [EnvoyGateway][] startup configuration @@ -54,11 +59,6 @@ EOF 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 @@ -71,7 +71,7 @@ cat < Date: Mon, 31 Jul 2023 14:58:00 -0700 Subject: [PATCH 3/5] wrap up Signed-off-by: Arko Dasgupta --- docs/latest/user/envoy-patch-policy.md | 94 +++++++++++++++++++++++++- 1 file changed, 93 insertions(+), 1 deletion(-) diff --git a/docs/latest/user/envoy-patch-policy.md b/docs/latest/user/envoy-patch-policy.md index 0154052152..d911e6731f 100644 --- a/docs/latest/user/envoy-patch-policy.md +++ b/docs/latest/user/envoy-patch-policy.md @@ -59,7 +59,9 @@ EOF kubectl rollout restart deployment envoy-gateway -n envoy-gateway-system ``` -## Customize Response +## Testing + +### 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` @@ -102,8 +104,98 @@ spec: EOF ``` +* Lets edit the HTTPRoute resource from the Quickstart to only match on paths with value `/get` +``` +kubectl patch httproute backend --type=json --patch '[{ + "op": "add", + "path": "/spec/rules/0/matches/0/path/value", + "value": "/get", +}]' +``` + +* Lets test it out by specifying a path apart from `/get` + +``` +$ curl --header "Host: www.example.com" http://localhost:8888/find +Handling connection for 8888 +could not find what you are looking for +``` + +## Debugging + +### Runtime + +* The `Status` subresource should have information about the status of the resource. Make sure +`Accepted=True` and `Programmed=True` conditions are set to ensure that the policy has been +applied to Envoy Proxy. + +``` +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyPatchPolicy +metadata: + annotations: + kubectl.kubernetes.io/last-applied-configuration: | + {"apiVersion":"gateway.envoyproxy.io/v1alpha1","kind":"EnvoyPatchPolicy","metadata":{"annotations":{},"name":"custom-response-patch-policy","namespace":"default"},"spec":{"jsonPatches":[{"name":"default/eg/http","operation":{"op":"add","path":"/default_filter_chain/filters/0/typed_config/local_reply_config","value":{"mappers":[{"body":{"inline_string":"could not find what you are looking for"},"filter":{"status_code_filter":{"comparison":{"op":"EQ","value":{"default_value":404}}}}}]}},"type":"type.googleapis.com/envoy.config.listener.v3.Listener"}],"priority":0,"targetRef":{"group":"gateway.networking.k8s.io","kind":"Gateway","name":"eg","namespace":"default"},"type":"JSONPatch"}} + creationTimestamp: "2023-07-31T21:47:53Z" + generation: 1 + name: custom-response-patch-policy + namespace: default + resourceVersion: "10265" + uid: a35bda6e-a0cc-46d7-a63a-cee765174bc3 +spec: + jsonPatches: + - name: default/eg/http + operation: + op: add + path: /default_filter_chain/filters/0/typed_config/local_reply_config + value: + mappers: + - body: + inline_string: could not find what you are looking for + filter: + status_code_filter: + comparison: + op: EQ + value: + default_value: 404 + type: type.googleapis.com/envoy.config.listener.v3.Listener + priority: 0 + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: eg + namespace: default + type: JSONPatch +status: + conditions: + - lastTransitionTime: "2023-07-31T21:48:19Z" + message: EnvoyPatchPolicy has been accepted. + observedGeneration: 1 + reason: Accepted + status: "True" + type: Accepted + - lastTransitionTime: "2023-07-31T21:48:19Z" + message: successfully applied patches. + reason: Programmed + status: "True" + type: Programmed +``` + +### Offline + +* You can use [egctl x translate][] to validate the translated xds output. + +## Caveats + +This API will always be an unstable API and the same outcome cannot be garunteed +across versions for these reasons +* The Envoy Proxy API might deprecate and remove API fields +* Envoy Gateway might alter the xDS translation creating a different xDS output +such as changing the `name` field of resources. + [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 +[egctl x translate]: https://gateway.envoyproxy.io/latest/user/egctl.html#egctl-experimental-translate From 524ad596c48bc12b3d82bb8f9cd9721e04b1bc02 Mon Sep 17 00:00:00 2001 From: Arko Dasgupta Date: Mon, 31 Jul 2023 15:00:34 -0700 Subject: [PATCH 4/5] lint Signed-off-by: Arko Dasgupta --- docs/latest/user/envoy-patch-policy.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/latest/user/envoy-patch-policy.md b/docs/latest/user/envoy-patch-policy.md index d911e6731f..2b667e7351 100644 --- a/docs/latest/user/envoy-patch-policy.md +++ b/docs/latest/user/envoy-patch-policy.md @@ -105,6 +105,7 @@ EOF ``` * Lets edit the HTTPRoute resource from the Quickstart to only match on paths with value `/get` + ``` kubectl patch httproute backend --type=json --patch '[{ "op": "add", From 50ff1b2daf539f12aaee775ce469607005df7eeb Mon Sep 17 00:00:00 2001 From: Arko Dasgupta Date: Tue, 1 Aug 2023 15:04:53 -0700 Subject: [PATCH 5/5] address comments && fix config Signed-off-by: Arko Dasgupta --- docs/latest/user/envoy-patch-policy.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/latest/user/envoy-patch-policy.md b/docs/latest/user/envoy-patch-policy.md index 2b667e7351..a06e5b416c 100644 --- a/docs/latest/user/envoy-patch-policy.md +++ b/docs/latest/user/envoy-patch-policy.md @@ -16,16 +16,14 @@ using [JSON Patch][] semantics. This API was introduced to allow advanced users to be able to leverage Envoy Proxy functionality not exposed by Envoy Gateway APIs today. -## Installation +## Quickstart ### Prerequistes -#### 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. -#### Enable EnvoyPatchPolicy +### Enable EnvoyPatchPolicy * By default EnvoyPatchPolicy][] is disabled. Lets enable it in the [EnvoyGateway][] startup configuration @@ -48,7 +46,7 @@ data: type: Kubernetes gateway: controllerName: gateway.envoyproxy.io/gatewayclass-controller - extensionAPIs: + extensionApis: enableEnvoyPatchPolicy: true EOF ```