1. Home
  2. Guides
  3. Next-Gen WAF
  4. Setup and configuration
  5. Kubernetes

Kubernetes Envoy Gateway

The Next-Gen WAF agent integrates with Envoy Gateway 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 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. 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 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.

    ---
    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:

    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 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.

    ---
    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.

    ---
    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.

    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.

    env:
    - name: SIGSCI_DEBUG_LOG_VERBOSITY
    value: "3"  # Enables ext_proc debug logs

  2. Check agent logs for processing details.

    kubectl logs -l app=ngwaf-agent -f

Related content

Fastly
© Fastly 2026