Skip to content

Commit

Permalink
docs: Add note on extproc header manipulation limitations (#10273)
Browse files Browse the repository at this point in the history 
Co-authored-by: soloio-bulldozer[bot] <48420018+soloio-bulldozer[bot]@users.noreply.github.com>
Co-authored-by: Rachael Graham <[email protected]>
  • Loading branch information
@davidjumani @soloio-bulldozer @Rachael-Graham
3 people authored Nov 5, 2024
1 parent bcfb76c commit 3ec73a6
Show file tree
Hide file tree
Showing 2 changed files with 78 additions and 71 deletions.
6 changes: 6 additions & 0 deletions changelog/v1.18.0-beta32/add-extproc-header-man-note.yaml
View file
Original file line number Diff line number Diff line change
@@ -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
143 changes: 72 additions & 71 deletions docs/content/guides/traffic_management/extproc/header-manipulation.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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",
Expand All @@ -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.|
Expand All @@ -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
Expand Down Expand Up @@ -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- <<EOF
apiVersion: gateway.solo.io/v1
Expand All @@ -201,85 +202,85 @@ EOF
EOF
```

8. Send a simple request to the httpbin app and make sure that you get back a 200 HTTP response code. The following request passes in two headers `header1` and `header2` that you see in your reponse.

8. Send a simple request to the httpbin app and make sure that you get back a 200 HTTP response code. The following request passes in two headers `header1` and `header2` that you see in your reponse.
```
curl -vik $(glooctl proxy url)/get -H "header1: value1" -H "header2: value2"
```
Example output:
Example output:
```
HTTP/1.1 200 OK
...
{
"args": {},
"args": {},
"headers": {
"Accept": "*/*",
"Header1": "value1",
"Header2": "value2",
"Host": "example.com.com",
"User-Agent": "curl/7.77.0",
"Accept": "*/*",
"Header1": "value1",
"Header2": "value2",
"Host": "example.com.com",
"User-Agent": "curl/7.77.0",
"X-Envoy-Expected-Rq-Timeout-Ms": "15000"
},
"origin": "10.0.11.109",
},
"origin": "10.0.11.109",
"url": "http://example.com/get"
}
```
9. Send another request to the httpbin app. This time, you pass along instructions for the ExtProc server in an `instruction` header. In this example, you use the ExtProc server to add the `header3` header, and to remove `header2`.
9. Send another request to the httpbin app. This time, you pass along instructions for the ExtProc server in an `instruction` header. In this example, you use the ExtProc server to add the `header3` header, and to remove `header2`.
```sh
curl -vik $(glooctl proxy url)/get -H "header1: value1" -H "header2: value2" -H 'instructions: {"addHeaders":{"header3":"value3","header4":"value4"},"removeHeaders":["instructions", "header2"]}'
```
Example output:

Example output:
```
{
"args": {},
"args": {},
"headers": {
"Accept": "*/*",
"Header1": "value1",
"Header3": "value3",
"Header4": "value4",
"Host": "example.com",
"User-Agent": "curl/7.77.0",
"Accept": "*/*",
"Header1": "value1",
"Header3": "value3",
"Header4": "value4",
"Host": "example.com",
"User-Agent": "curl/7.77.0",
"X-Envoy-Expected-Rq-Timeout-Ms": "15000"
},
"origin": "10.0.11.109",
},
"origin": "10.0.11.109",
"url": "http://example.com/get"
}
```
10. Edit the `Settings` resource again and set `requestHeaderMode: SKIP`. This setting instructs the ExtProc filter to not send any request headers to the ExtProc server.

10. Edit the `Settings` resource again and set `requestHeaderMode: SKIP`. This setting instructs the ExtProc filter to not send any request headers to the ExtProc server.
```sh
kubectl edit settings default -n gloo-system
```
11. Send the same request to the httpbin app. Note that this time, `header2` is not removed and `header3` and `header4` are not added to the request, because the request headers are not sent to the ExtProc server.

11. Send the same request to the httpbin app. Note that this time, `header2` is not removed and `header3` and `header4` are not added to the request, because the request headers are not sent to the ExtProc server.
```sh
curl -vik $(glooctl proxy url)/get -H "header1: value1" -H "header2: value2" -H 'instructions: {"addHeaders":{"header3":"value3","header4":"value4"},"removeHeaders":["instructions", "header2"]}'
```
Example output:

Example output:
```
{
"args": {},
"args": {},
"headers": {
"Accept": "*/*",
"Header1": "value1",
"Header2": "value2",
"Host": "example.com",
"Instructions": "{\"addHeaders\":{\"header3\":\"value3\",\"header4\":\"value4\"},\"removeHeaders\":[\"instructions\", \"header2\"]}",
"User-Agent": "curl/7.77.0",
"Accept": "*/*",
"Header1": "value1",
"Header2": "value2",
"Host": "example.com",
"Instructions": "{\"addHeaders\":{\"header3\":\"value3\",\"header4\":\"value4\"},\"removeHeaders\":[\"instructions\", \"header2\"]}",
"User-Agent": "curl/7.77.0",
"X-Envoy-Expected-Rq-Timeout-Ms": "15000"
},
"origin": "10.0.11.109",
},
"origin": "10.0.11.109",
"url": "http://example.com/get"
}
```

## Cleanup

You can optionally remove the resources that you created as part of this guide.
You can optionally remove the resources that you created as part of this guide.

```sh
kubectl delete deployment ext-proc-grpc httpbin
Expand All @@ -292,5 +293,5 @@ kubectl delete virtualservice vs -n gloo-system





0 comments on commit 3ec73a6

Please sign in to comment.