External Processing (ExtProc) — streaming request/response mutation

ExtAuth answers one question: should this request proceed? ExtProc answers a different one: what should this request or response actually look like? Same external-service pattern, very different surface area. This page walks the six processing phases, the GatewayExtension + traffic-policy wiring on both kgateway and agentgateway, and a small Python (and Go) server you can deploy in a kind cluster in under a minute.

Companion reference: Solo external auth service, the bouncer at the door. ExtProc is what runs after the bouncer waves the request through.

1 · What ExtProc can do

ExtProc is defined by envoy.service.ext_proc.v3.ExternalProcessor. Envoy holds a single bidirectional gRPC stream open per HTTP request and sends a ProcessingRequest message at each enabled phase. Your server replies with a ProcessingResponse that can carry a header mutation, a body mutation, an immediate response (terminate the request with a status code), or a dynamic-metadata write. The stream stays open until the request ends.

2 · The processing flow

Envoy can send your server up to six phases per request. You opt into each phase via processingMode on the GatewayExtension. Skip the phases you don't need, every enabled phase is a gRPC round-trip.

Each enabled phase is a separate ProcessingRequest / ProcessingResponse exchange on the same stream. The server can also tell Envoy "skip the rest" with processing_mode_override, useful when the request-headers phase already told you nothing else needs inspection.

3 · How it's wired in each product

Both products expose the ExtProc gRPC backend via a traffic policy that attaches to an HTTPRoute. agentgateway folds everything (backend + scope) into one AgentgatewayPolicy and ships with sensible streaming defaults; kgateway splits the wiring across a GatewayExtension + a TrafficPolicy and gives you full per-phase control via Envoy-native processingMode. Pick the tab for the product you're on — each has its own knobs (or absence of knobs) to be aware of.

apiVersion: v1
kind: Service
metadata:
  name: redact-extproc
  namespace: agentgateway-system
spec:
  selector: { app: redact-extproc }
  ports:
  - { port: 4444, targetPort: 18080, appProtocol: kubernetes.io/h2c }
---
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: redact
  namespace: agentgateway-system
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind:  HTTPRoute
    name:  llm-openai
  traffic:
    extProc:
      backendRef:
        name: redact-extproc
        port: 4444
      # No processingMode equivalent shipping today; see preview below for the next release.

traffic:
  extProc:
    backendRef: { name: redact-extproc, port: 4444 }
    processingOptions:
      requestHeaderMode:   Skip            # Send (default) | Skip
      responseHeaderMode:  Send
      requestBodyMode:     None            # FullDuplexStreamed (default) | Buffered | BufferedPartial | None
      responseBodyMode:    None            # Buffered modes cap at 8 KB
      requestTrailerMode:  Skip
      responseTrailerMode: Skip
      allowModeOverride:   false           # honour mode_override responses from the server

apiVersion: v1
kind: Service
metadata:
  name: redact-extproc
  namespace: kgateway-system
spec:
  selector: { app: redact-extproc }
  ports:
  - port: 4444
    targetPort: 18080
    protocol: TCP
    appProtocol: kubernetes.io/h2c

apiVersion: gateway.kgateway.dev/v1alpha1
kind: GatewayExtension
metadata:
  name: redact
  namespace: kgateway-system
spec:
  type: ExtProc
  extProc:
    grpcService:
      backendRef:
        name: redact-extproc
        port: 4444
    # Scope the stream. Default-deny: turn on only what the server needs.
    processingMode:
      requestHeaderMode:  SKIP            # UPPERCASE enums (Envoy native)
      responseHeaderMode: SEND
      responseBodyMode:   NONE            # NONE | STREAMED | BUFFERED | BUFFERED_PARTIAL
    failOpen: true                        # if ExtProc is down, forward the request unmodified
    messageTimeout: 200ms                 # per-message deadline

apiVersion: enterprisekgateway.solo.io/v1alpha1
kind: EnterpriseKgatewayTrafficPolicy
metadata:
  name: redact
  namespace: kgateway-system
spec:
  extProc:
    extensionRef:
      name: redact
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api
  namespace: kgateway-system
spec:
  parentRefs:
  - name: http
  rules:
  - matches:
    - path: { type: PathPrefix, value: /v1 }
    filters:
    - type: ExtensionRef
      extensionRef:
        group: enterprisekgateway.solo.io
        kind:  EnterpriseKgatewayTrafficPolicy
        name:  redact
    backendRefs:
    - name: my-app
      port: 80

4 · Sample, a runnable server

Smallest server that does something useful: strip any response header whose name looks like a credential, and surface the redaction as a counter header. Same logic, shown in Python and Go — pick whichever language fits your stack.

# BEFORE — route /v1 with no ExtProc filter attached
$ curl -si http://gateway.local/v1/echo -H 'Host: api.local'
HTTP/1.1 200 OK
content-type: application/json
x-api-key: sk-live-7f9c2a1e4d8b
authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...
x-internal-secret: rotate-me-2026
server: upstream/1.0

{"msg":"hi"}

# AFTER — same route with the redact ExtensionRef filter attached
$ curl -si http://gateway.local/v1/echo -H 'Host: api.local'
HTTP/1.1 200 OK
content-type: application/json
x-redacted-count: 3
server: upstream/1.0

{"msg":"hi"}

import grpc, re
from concurrent import futures
from envoy.service.ext_proc.v3 import (
    external_processor_pb2 as pb,
    external_processor_pb2_grpc as svc,
)
from envoy.config.core.v3.base_pb2 import HeaderValue, HeaderValueOption

KEY_RE = re.compile(r"(api[-_]?key|token|bearer|secret)", re.I)

class Proc(svc.ExternalProcessorServicer):
    def Process(self, request_iterator, ctx):
        for req in request_iterator:
            resp = pb.ProcessingResponse()
            if req.HasField("response_headers"):
                rm = resp.response_headers.response.header_mutation
                removed = 0
                for h in req.response_headers.headers.headers:
                    if KEY_RE.search(h.key):
                        rm.remove_headers.append(h.key)
                        removed += 1
                if removed:
                    rm.set_headers.add(
                        header=HeaderValue(key="x-redacted-count",
                                           raw_value=str(removed).encode())
                    )
            yield resp

if __name__ == "__main__":
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=8))
    svc.add_ExternalProcessorServicer_to_server(Proc(), server)
    server.add_insecure_port("0.0.0.0:18080")
    server.start(); server.wait_for_termination()

FROM python:3.12-alpine
RUN pip install --no-cache-dir grpcio envoy-extproc-sdk
COPY extproc.py /app/extproc.py
EXPOSE 18080
CMD ["python", "/app/extproc.py"]

package main

import (
	"io"
	"log"
	"net"
	"regexp"
	"strconv"

	corev3 "github.com/envoyproxy/go-control-plane/envoy/config/core/v3"
	extproc "github.com/envoyproxy/go-control-plane/envoy/service/ext_proc/v3"
	"google.golang.org/grpc"
)

var keyRE = regexp.MustCompile(`(?i)(api[-_]?key|token|bearer|secret)`)

type server struct {
	extproc.UnimplementedExternalProcessorServer
}

func (server) Process(stream extproc.ExternalProcessor_ProcessServer) error {
	for {
		req, err := stream.Recv()
		if err == io.EOF {
			return nil
		}
		if err != nil {
			return err
		}

		resp := &extproc.ProcessingResponse{}
		if rh := req.GetResponseHeaders(); rh != nil {
			mut := &corev3.HeaderMutation{}
			removed := 0
			for _, h := range rh.GetHeaders().GetHeaders() {
				if keyRE.MatchString(h.GetKey()) {
					mut.RemoveHeaders = append(mut.RemoveHeaders, h.GetKey())
					removed++
				}
			}
			if removed > 0 {
				mut.SetHeaders = append(mut.SetHeaders, &corev3.HeaderValueOption{
					Header: &corev3.HeaderValue{
						Key:      "x-redacted-count",
						RawValue: []byte(strconv.Itoa(removed)),
					},
				})
			}
			resp.Response = &extproc.ProcessingResponse_ResponseHeaders{
				ResponseHeaders: &extproc.HeadersResponse{
					Response: &extproc.CommonResponse{HeaderMutation: mut},
				},
			}
		}
		if err := stream.Send(resp); err != nil {
			return err
		}
	}
}

func main() {
	lis, err := net.Listen("tcp", "0.0.0.0:18080")
	if err != nil {
		log.Fatal(err)
	}
	s := grpc.NewServer()
	extproc.RegisterExternalProcessorServer(s, server{})
	log.Println("extproc listening on :18080")
	log.Fatal(s.Serve(lis))
}

FROM golang:1.23-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/extproc .

FROM gcr.io/distroless/static-debian12
COPY --from=build /out/extproc /extproc
EXPOSE 18080
ENTRYPOINT ["/extproc"]

Build, push to any registry your cluster can reach, then point the Deployment from §3 at the new image. The Service stays the same.

5 · Verifying

Apply the chart, then curl through the gateway. With the redact filter attached to /v1, any response header whose name matches the credential pattern should disappear and a x-redacted-count header should appear instead.

$ curl -si http://gateway.local/v1/echo \
    -H 'Host: api.local'
HTTP/1.1 200 OK
content-type: application/json
x-redacted-count: 2
...

$ kubectl -n kgateway-system logs deploy/redact-extproc
INFO: Process stream opened
INFO: response_headers: removed api-key, bearer-token (2)
INFO: Process stream closed

Compare against the same call on a route without the ExtensionRef filter, the credential headers come back unchanged. That's the cleanest before/after demo, same upstream, same path prefix, only the filter chain differs.

6 · The processingMode settings

This is where ExtProc deployments live or die. Wrong defaults on processingMode waste latency, break streaming, or starve the server. Read this once before shipping anything.

7 · When to reach for ExtProc vs ExtAuth

The two filters look superficially similar (gRPC sidecar called by Envoy on every request), but they occupy different jobs and different points in the filter chain. Pick wrong and you either pay for capability you don't need, or you build code to do something a stock config already handles.

How to read it. One request, two filters. ExtAuth runs first — a single Check() RPC over request attributes. On deny, the gateway short-circuits and the upstream never sees the call (amber dashed). On allow, ExtAuth optionally injects headers and hands off to ExtProc, which opens a bidirectional gRPC stream and can read/mutate any enabled phase on the way out and on the way back. The response only ever goes through ExtProc, never ExtAuth — that's why response-body redaction and LLM-streaming filters have to be ExtProc.

The capability matrix

Use-case picker

Where to go next

• Solo external auth service, the ExtAuth side of the same story.
• JWT claims to HTTP headers, why ExtAuth fronting ExtProc is the pattern, and how the verified-claim handoff works.
• kgateway ExtProc docs, official reference including the aggregation and dynamic-routing use cases.
• Envoy ExtProc proto, the message-by-message spec.