--- title: Kubernetes Envoy Gateway summary: null url: >- https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/kubernetes-envoy-gateway --- The Next-Gen WAF agent integrates with [Envoy Gateway](https://gateway.envoyproxy.io/docs/) as an extensible external processing service. This enables real-time traffic inspection and security enforcement within the Gateway's request and response processing pipeline. ## Prerequisites [Copy the agent keys](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/agent-management/accessing-agent-keys) for your workspace. You will need them when configuring the deployment. ## How the Next-Gen WAF Service extension works The Envoy Gateway API uses a set of Gateway API extensions, which enable you to use the [Envoy proxy](https://gateway.envoyproxy.io/docs/concepts/gateway_api_extensions/#gateway-api-extensions-in-envoy-gateway). You can use a CRD called EnvoyExtensionPolicy to configure external processing. ## GRPC External Processing Service In this section, we'll deploy the Next-Gen WAF agent for the Envoy Gateway's example app. 1. Follow Envoy Gateway's [prerequisite instructions](https://gateway.envoyproxy.io/docs/tasks/extensibility/ext-proc/#prerequisites) to install the Gateway API CRDs, Envoy Gateway, and the example app. 2. Create a Kubernetes deployment for the Next-Gen WAF agent that will be used as the external processing service: > **NOTE:** The `readinessProbe` and SIGSCI_ENVOY_GRPC_ADDRESS ports much match. ```yaml copy --- apiVersion: apps/v1 kind: Deployment metadata: name: ngwaf-agent spec: replicas: 2 selector: matchLabels: app: ngwaf-agent template: metadata: labels: app: ngwaf-agent spec: containers: - name: ngwaf-agent-container image: signalsciences/sigsci-agent:latest imagePullPolicy: Never ports: - containerPort: 9999 env: - name: SIGSCI_ACCESSKEYID valueFrom: secretKeyRef: name: ngwaf-agent-keys key: your-access-key-id - name: SIGSCI_SECRETACCESSKEY valueFrom: secretKeyRef: name: ngwaf-agent-keys key: your-secret-access-key - name: SIGSCI_ENVOY_EXTPROC_ENABLED value: "true" - name: SIGSCI_ENVOY_GRPC_ADDRESS value: "0.0.0.0:9999" - name: SIGSCI_SERVER_FLAVOR value: "envoy-gateway" readinessProbe: grpc: port: 9999 --- apiVersion: v1 kind: Service metadata: name: ngwaf-agent spec: selector: app: ngwaf-agent ports: - protocol: TCP port: 9999 targetPort: 9999 ``` 3. Create agent secret credentials: ```bash kubectl create secret generic ngwaf-agent-keys \ --from-literal=your-access-key-id=YOUR_ACCESS_KEY_ID \ --from-literal=your-secret-access-key=YOUR_SECRET_ACCESS_KEY ``` 4. Create a new [HTTPRoute](https://gateway.envoyproxy.io/docs/tasks/extensibility/ext-proc/#grpc-external-processing-service) resource to route traffic on the path /mywaf to the backend service. Additionally, set up a request buffer limit to restrict how much the Next-Gen WAF agent inspects. ```yaml --- apiVersion: gateway.envoyproxy.io/v1alpha1 kind: BackendTrafficPolicy metadata: name: request-buffer-limit spec: targetRefs: - group: gateway.networking.k8s.io kind: HTTPRoute name: mywaf requestBuffer: # Maximum request body buffered and sent to the ngwaf-agent limit: 1Mi # Supports SI units (e.g., 4Ki, 1Mi) --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: mywaf spec: parentRefs: - name: eg hostnames: - "www.example.com" rules: - matches: - path: type: PathPrefix value: /mywaf backendRefs: - name: backend port: 3000 ``` 5. Create a new EnvoyExtensionPolicy resource to configure the external processing service. This EnvoyExtensionPolicy targets the HTTPRoute `mywaf` created in the previous step. It calls the GRPC external processing service `ngwaf-agent` on port 9999 for processing. > **NOTE:** The `processingMode` struct is used to define what should be sent to the external processor. For requests, the Next-Gen WAF agent only supports Buffered message bodies. In this mode, it will buffer the message body in memory and send the entire body at once. > > If the body exceeds the configured buffer limit, then any request over the limit will fail with an HTTP "413 Payload Too Large" ```yaml --- apiVersion: gateway.envoyproxy.io/v1alpha1 kind: EnvoyExtensionPolicy metadata: name: ngwaf-agent-policy spec: targetRefs: - group: gateway.networking.k8s.io kind: HTTPRoute name: mywaf extProc: - backendRefs: - name: ngwaf-agent port: 9999 processingMode: request: body: Buffered attributes: - connection.tls_version - request.host - request.path - request.scheme - source.address response: {} failOpen: true messageTimeout: 250ms ``` 6. Test the setup by sending a request to the backend service through the created HTTPRoute. Here's a sample request and response. You should see that the ngwaf-agent has added signals to the request. ```bash curl -v -H "Host: www.example.com" -H "Content-Type: text/plain" "http://${GATEWAY_HOST}/mywaf?cmd.exe=../../../etc/passwd" -d "{\"payload\": \"traversal\"}" * Trying 172.19.0.3:80... * Connected to 172.19.0.3 (172.19.0.3) port 80 > POST /mywaf?cmd.exe=../../../etc/passwd HTTP/1.1 > Host: www.example.com > User-Agent: curl/8.5.0 > Accept: */* > Content-Type: text/plain > Content-Length: 24 > < HTTP/1.1 200 OK < content-type: application/json < x-content-type-options: nosniff < date: Thu, 14 May 2026 06:14:35 GMT < content-length: 632 < x-sigsci-tags: TRAVERSAL,SUSPECTED-BAD-BOT < x-sigsci-request-id: 6a05684b826b7576ad8e98ab < { "path": "/mywaf?cmd.exe=../../../etc/passwd", "host": "www.example.com", "method": "POST", "proto": "HTTP/1.1", "headers": { "Accept": "*/*", "Content-Length": "24", "Content-Type": "text/plain", "Host": "www.example.com", "User-Agent": "curl/8.5.0", "X-Sigsci-Request-Id": "6a05684deadbeef76ad8e98ab", "X-Sigsci-Tags": "TRAVERSAL,SUSPECTED-BAD-BOT" }, "body": "{\"payload\": \"traversal\"}", "clientIP": "172.19.0.1", "timestamp": "2026-05-14T06:14:35Z" } ``` ## Debug logging Enable detailed logging for troubleshooting. 1. Add the following environment variable. ```yaml env: - name: SIGSCI_DEBUG_LOG_VERBOSITY value: "3" # Enables ext_proc debug logs ``` 2. Check agent logs for processing details. ```bash kubectl logs -l app=ngwaf-agent -f ``` ## Related content - [Kubernetes overview](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/) - [Getting started with the agent](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/agent-management/getting-started-with-the-agent)