From 3ec73a6cb6007e7cde941ebd666ff868fda2bb65 Mon Sep 17 00:00:00 2001 From: David Jumani Date: Tue, 5 Nov 2024 12:46:37 -0500 Subject: [PATCH] docs: Add note on extproc header manipulation limitations (#10273) Co-authored-by: soloio-bulldozer[bot] <48420018+soloio-bulldozer[bot]@users.noreply.github.com> Co-authored-by: Rachael Graham --- .../add-extproc-header-man-note.yaml | 6 + .../extproc/header-manipulation.md | 143 +++++++++--------- 2 files changed, 78 insertions(+), 71 deletions(-) create mode 100644 changelog/v1.18.0-beta32/add-extproc-header-man-note.yaml diff --git a/changelog/v1.18.0-beta32/add-extproc-header-man-note.yaml b/changelog/v1.18.0-beta32/add-extproc-header-man-note.yaml new file mode 100644 index 00000000000..8ffc2603584 --- /dev/null +++ b/changelog/v1.18.0-beta32/add-extproc-header-man-note.yaml @@ -0,0 +1,6 @@ +changelog: +- type: NON_USER_FACING + description: >- + Adds a note about the limitations of header manipulation via ExtProc. + + skipCI-kube-tests:true diff --git a/docs/content/guides/traffic_management/extproc/header-manipulation.md b/docs/content/guides/traffic_management/extproc/header-manipulation.md index 6c754006027..70d16036f2d 100644 --- a/docs/content/guides/traffic_management/extproc/header-manipulation.md +++ b/docs/content/guides/traffic_management/extproc/header-manipulation.md @@ -1,23 +1,24 @@ --- title: Header manipulation weight: 40 -description: Walk through an example for how to manipulate request headers by using an ExtProc server. +description: Walk through an example for how to manipulate request headers by using an ExtProc server. --- Set up an external processing (ExtProc) server that manipulates request headers for a sample app. {{% notice note %}} -External processing is an Enterprise-only feature. +External processing is an Enterprise-only feature. {{% /notice %}} {{% notice warning %}} Envoy's external processing filter is considered a work in progress and has an unknown security posture. Use caution when using this feature in production environments. For more information, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_proc_filter#external-processing). +Note that as of Envoy 1.32, header manipulation via ExtProc does not support the [`append_action`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/base.proto#envoy-v3-api-msg-config-core-v3-headervalueoption) field. {{% /notice %}} -1. Before you begin, install [Gloo Gateway Enterprise]({{% versioned_link_path fromRoot="/installation/enterprise/" %}}) in your cluster. +1. Before you begin, install [Gloo Gateway Enterprise]({{% versioned_link_path fromRoot="/installation/enterprise/" %}}) in your cluster. + +2. Set up the ExtProc server. This example uses a prebuilt ExtProc server that manipulates request and response headers based on instructions that are sent in an `instructions` header. -2. Set up the ExtProc server. This example uses a prebuilt ExtProc server that manipulates request and response headers based on instructions that are sent in an `instructions` header. - {{< tabs >}} {{% tab %}} ```yaml @@ -63,9 +64,9 @@ EOF {{% /tab %}} {{< /tabs >}} - The `instructions` header must be provided as a JSON string in the following format: - - ```json + The `instructions` header must be provided as a JSON string in the following format: + + ```json { "addHeaders": { "header1": "value1", @@ -75,40 +76,40 @@ EOF } } ``` - -3. Verify that the ExtProc server is up and running. + +3. Verify that the ExtProc server is up and running. ```sh - kubectl get pods + kubectl get pods ``` - - Example output: + + Example output: ``` NAME READY STATUS RESTARTS AGE ext-proc-grpc-59d44ddf76-42q2x 1/1 Running 0 24m ``` - -4. Edit the default `Settings` custom resource to enable ExtProc in Gloo Gateway. + +4. Edit the default `Settings` custom resource to enable ExtProc in Gloo Gateway. ``` kubectl edit settings default -n gloo-system ``` - - Add the following ExtProc settings to the `spec` section: + + Add the following ExtProc settings to the `spec` section: ```yaml - extProc: - grpcService: - extProcServerRef: + extProc: + grpcService: + extProcServerRef: name: default-ext-proc-grpc-4444 namespace: gloo-system - filterStage: + filterStage: stage: AuthZStage predicate: After failureModeAllow: false allowModeOverride: false - processingMode: + processingMode: requestHeaderMode: SEND responseHeaderMode: SKIP ``` - + |Setting|Description| |--|--| |`grpcService`| The configuration of the external processing server that you created earlier.| @@ -120,8 +121,8 @@ EOF |`processingMode`|Decide how you want the ExtProc server to process request and response information. | |`processingMode.requestHeaderMode`|Send (`SEND`) or skip sending (`SKIP`) request header information to the ExtProc server. | |`processingMode.responseHeaderMode`|Send (`SEND`) or skip sending (`SKIP`) response header information to the ExtProc server. | - -5. Deploy the `httpbin` sample app. + +5. Deploy the `httpbin` sample app. {{< tabs >}} {{% tab %}} ```yaml @@ -172,13 +173,13 @@ EOF ``` {{% /tab %}} {{< /tabs>}} - -6. Verify that the httpbin pod is up an running. + +6. Verify that the httpbin pod is up an running. ```sh kubectl get pods | grep httpbin ``` -7. Create a virtual service to expose the httpbin app on the gateway. +7. Create a virtual service to expose the httpbin app on the gateway. ```yaml kubectl apply -f- <