Header manipulation

Set up an external processing (ExtProc) server that manipulates request headers for a sample app.

External processing is an Enterprise-only feature.

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.

  1. Before you begin, install Gloo Gateway 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.

    kubectl apply -f- <<EOF
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: ext-proc-grpc
    spec:
      selector:
        matchLabels:
          app: ext-proc-grpc
      replicas: 1
      template:
        metadata:
          labels:
            app: ext-proc-grpc
        spec:
          containers:
            - name: ext-proc-grpc
              image: gcr.io/solo-test-236622/ext-proc-example-basic-sink:0.0.2
              imagePullPolicy: IfNotPresent
              ports:
                - containerPort: 18080
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: ext-proc-grpc
      labels:
        app: ext-proc-grpc
      annotations:
        gloo.solo.io/h2_service: "true"
    spec:
      ports:
      - port: 4444
        targetPort: 18080
        protocol: TCP
      selector:
        app: ext-proc-grpc
    EOF
    

    The instructions header must be provided as a JSON string in the following format:

    {
      "addHeaders": {
        "header1": "value1",
        "header2": "value2"
      },
      "removeHeaders": [ "header3", "header4" ],
      }
    }
    
  3. Verify that the ExtProc server is up and running.

    kubectl get pods 
    

    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.

    kubectl edit settings default -n gloo-system
    

    Add the following ExtProc settings to the spec section:

    extProc: 
      grpcService: 
        extProcServerRef: 
          name: default-ext-proc-grpc-4444
          namespace: gloo-system
      filterStage: 
        stage: AuthZStage
        predicate: After
      failureModeAllow: false
      allowModeOverride: false
      processingMode: 
        requestHeaderMode: SEND
        responseHeaderMode: SKIP
    
    Setting Description
    grpcService The configuration of the external processing server that you created earlier.
    grpcService.exProcServerRef.name The name of the upstream that was created for the ExtProc server.
    grpcService.exProcServerRef.namespace The namespace of the upstream that was created for the ExtProc server.
    filterStage Where in the filter chain you want to apply the external processing.
    failureModeAllow Allow the ExtProc server to continue when an error is detected during external processing. If set to true, the ExtProc server continues. If set to false, external processing is stopped and an error is returned to the Envoy proxy.
    allowModeOverride Allow the ExtProc server to override the processing mode settings that you set. Default value is false.
    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.

    kubectl apply -f- <<EOF
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: httpbin
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: httpbin
      labels:
        app: httpbin
    spec:
      ports:
      - name: http
        port: 8000
        targetPort: 80
      selector:
        app: httpbin
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: httpbin
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: httpbin
          version: v1
      template:
        metadata:
          labels:
            app: httpbin
            version: v1
        spec:
          serviceAccountName: httpbin
          containers:
          - image: docker.io/kennethreitz/httpbin
            imagePullPolicy: IfNotPresent
            name: httpbin
            ports:
            - containerPort: 80
    EOF
    

  6. Verify that the httpbin pod is up an running.

    kubectl get pods | grep httpbin
    
  7. Create a virtual service to expose the httpbin app on the gateway.

    kubectl apply -f- <<EOF
    apiVersion: gateway.solo.io/v1
    kind: VirtualService
    metadata:
      name: vs
      namespace: gloo-system
    spec:
      virtualHost:
        domains:
        - '*'
        routes:
        - matchers:
          - prefix: /
          routeAction:
            single:
              upstream:
                name: default-httpbin-8000
                namespace: gloo-system
    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.

    curl -vik $(glooctl proxy url)/get -H "header1: value1" -H "header2: value2"
    

    Example output:

    HTTP/1.1 200 OK
    ...
    {
      "args": {}, 
      "headers": {
        "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", 
      "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.

    curl -vik $(glooctl proxy url)/get -H "header1: value1" -H "header2: value2" -H 'instructions: {"addHeaders":{"header3":"value3","header4":"value4"},"removeHeaders":["instructions", "header2"]}'
    

    Example output:

    {
      "args": {}, 
      "headers": {
        "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", 
      "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.

    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.

    curl -vik $(glooctl proxy url)/get -H "header1: value1" -H "header2: value2" -H 'instructions: {"addHeaders":{"header3":"value3","header4":"value4"},"removeHeaders":["instructions", "header2"]}'
    

    Example output:

    {
     "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", 
       "X-Envoy-Expected-Rq-Timeout-Ms": "15000"
     }, 
     "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.

kubectl delete deployment ext-proc-grpc httpbin
kubectl delete service ext-proc-grpc httpbin
kubectl delete servicaccount httpbin
kubectl delete virtualservice vs -n gloo-system