Introduction

Envoy offers multiple filters that you can use to manage, monitor, and secure traffic to your apps. Although Envoy is extensible via C++ and WebAssembly modules, it might not be practical to implement these extensions for all of your apps. You might also have very specific requirements for how to process a request or response to allow traffic routing between different types of apps, such as adding specific headers to new and legacy apps.

With external processing, you can implement an external gRPC processing server that can read and modify all aspects of an HTTP request or response, such as headers, body, and trailers, and add that server to the Envoy filter chain by using the Envoy external processing (ExtProc) filter. The external service can manipulate headers, body, and trailers of a request or response before it is forwarded to an upstream or downstream service. The request or response can also be terminated at any given time.

With this approach, you have the flexibility to apply your requirements to all types of apps, without the need to run WebAssembly or other custom scripts.

How it works

The following diagram shows an example for how request header manipulation works when an external processing server is used.

Request header manipulation with external processing
  1. The downstream service sends a request with headers to the Envoy gateway.
  2. The gateway extracts the header information and sends it to the external processing server.
  3. The external processing server modifies, adds, or removes the request headers.
  4. The modified request headers are sent back to the gateway.
  5. The modified headers are added to the request.
  6. The request is forwarded to the upstream application.

ExtProc server considerations

The ExtProc server is a gRPC interface that must be able to respond to events in the lifecycle of an HTTP request. When the ExtProc filter is enabled in Gloo Gateway and a request or response is received on the gateway, the filter communicates with the ExtProc server by using bidirectional gRPC streams.

To implement your own ExtProc server, make sure that you follow Envoy’s technical specification for an external processor. You can also follow the Header manipulation example to try out ExtProc in Gloo Gateway with a sample ExtProc server.

Enable ExtProc in Gloo Gateway

You can enable ExtProc for all requests and responses that the gateway processes by using the Settings custom resource.

  1. Edit the default Settings resource.

      kubectl edit settings default -n gloo-system
      
  2. Add the following values to the spec section.

      
       spec: 
         extProc:
           allowModeOverride: false
           failureModeAllow: false
           filterStage:
             predicate: After
             stage: AuthZStage
           grpcService:
             extProcServerRef:
               name: ext-proc-grpc
               namespace: gloo-system
           processingMode:
             requestHeaderMode: SEND
             responseHeaderMode: SKIP
      
    SettingDescription
    allowModeOverrideAllow the extProc server to override the processing mode settings that you set. Default value is false.
    failureModeAllowAllow 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.
    filterStage.predicateHow to apply the filter relative to filterStage.stage.
    filterStage.stageThe stage in the filter chain where you want to enable external processing. In this example, external processing is added after the authorization stage.
    grpcService.extProcServerRefThe name and namespace of the Upstream resource that represents your external processing server.
    processingMode.requestHeaderModeSend (SEND) or skip sending (SKIP) request header information to the extProc server.
    processingMode.responseHeaderModeSend (SEND) or skip sending (SKIP) response header information to the extProc server.