--- 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/managing-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 must 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. Optional, but recommended, set up a request buffer limit to restrict how much the Next-Gen WAF agent inspects. > **NOTE:** If a buffer limit is configured and the body exceeds the configured limit, then any request over the limit will fail with an HTTP "413 Payload Too Large" from [Envoy](https://www.envoyproxy.io/docs/envoy/latest/faq/debugging/why_is_envoy_sending_413s). ```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. For this reason, we recommended setting a buffer limit. ```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)