--- title: Kubernetes Envoy summary: null url: >- https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/kubernetes-envoy --- In this example, the Next-Gen WAF agent runs in a Docker sidecar and communicates directly with an Envoy proxy deployed on the application. ## Integrating the Next-Gen WAF agent into an Envoy Proxy You can deploy the Next-Gen WAF agent for integration with the Envoy Proxy via the External Processing (`ext_proc`) HTTP filter. This filter communicates with the `sigsci-agent` via gRPC. Configure the `sigsci-agent` to run with an Envoy gRPC listener instead of the normal RPC listener. To do this, set the `envoy-grpc-address` [agent configuration](https://www.fastly.com/documentation/reference/ngwaf/agent-config#agentcfg_envoy-grpc-address) option. When set, the Envoy gRPC listener starts instead of the default RPC listener. Set the configuration value in the `sigsci-agent` config file: ```text envoy-grpc-address = "0.0.0.0:8000" ``` Alternatively, set the configuration value in the `sigsci-agent` environment: ```text SIGSCI_ENVOY_GRPC_ADDRESS=0.0.0.0:8000 ``` You can also configure the `sigsci-agent` with TLS enabled. To do this, set the certificate and key files in the `sigsci-agent` config file: ```text envoy-grpc-cert = "/path/to/cert.pem" envoy-grpc-key = "/path/to/key.pem" ``` Alternatively, set them in the `sigsci-agent` environment: ```text SIGSCI_ENVOY_GRPC_CERT=/path/to/cert.pem SIGSCI_ENVOY_GRPC_KEY=/path/to/key.pem ``` ## Envoy configuration Envoy must be configured with an [External Processing HTTP filter (`envoy.filters.http.ext_proc`)](https://www.envoyproxy.io/docs/envoy/v1.33.0/configuration/http/http_filters/ext_proc_filter) before the main handler filter to process data, such as the one shown in the example below that points at the `sigsci-agent-grpc` cluster. ```yaml http_filters: - name: envoy.filters.http.buffer typed_config: # Maximum request body bytes buffered and sent to the sigsci-agent "@type": type.googleapis.com/envoy.extensions.filters.http.buffer.v3.Buffer max_request_bytes: 1048576 # 1 MB body size limit - name: envoy.filters.http.ext_proc typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.ext_proc.v3.ExternalProcessor grpc_service: envoy_grpc: cluster_name: sigsci-agent-grpc timeout: 0.2s failure_mode_allow: true message_timeout: 0.2s request_attributes: - "connection.tls_version" - "request.host" - "request.path" - "request.scheme" - "source.address" processing_mode: request_header_mode: SEND response_header_mode: SEND request_body_mode: BUFFERED response_body_mode: NONE request_trailer_mode: SKIP response_trailer_mode: SKIP - name: envoy.filters.http.router typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router ``` ## Sample deployment The [Sample deployment configuration](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/kubernetes-envoy#sample-deployment-configuration) section contains a complete Envoy proxy deployment configuration, which you can use as a starting point for your own deployment. For the sample configuration to work, complete the following steps: 1. Update the [agent keys](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/agent-management/managing-agent-keys) for your workspace by running the following command: ```term copy nolinenums $ kubectl create secret generic sigsci.test \ --from-literal=accesskeyid= \ --from-literal=secretaccesskey= ``` Be sure to replace `` and `` with your agent keys. 2. Save the [Sample deployment configuration](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/kubernetes-envoy#sample-deployment-configuration) as `envoy-deployment.yaml`. 3. Deploy `envoy-deployment.yaml` by running the following command: ```term copy nolinenums $ kubectl apply -f envoy-deployment.yaml ``` 4. _(Optional)_ Set up port forwarding and test the deployment locally by running the following command: ```term copy nolinenums $ kubectl port-forward svc/envoy 10000:10000 ``` ### Sample deployment configuration ```yaml copy # ConfigMap: Contains the Envoy configuration apiVersion: v1 kind: ConfigMap metadata: name: envoy-config data: envoy.yaml: | node: id: proxy-node cluster: proxy-cluster static_resources: listeners: - name: listener_0 address: socket_address: address: 0.0.0.0 port_value: 10000 filter_chains: - filters: - name: envoy.filters.network.http_connection_manager typed_config: "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager stat_prefix: ingress_http route_config: name: local_route virtual_hosts: - name: backend domains: ["*"] # CORS configuration at virtual host level cors: allow_origin_string_match: - prefix: "*" allow_methods: GET, PUT, DELETE, POST, OPTIONS allow_headers: keep-alive,user-agent,cache-control,content-type,content-transfer-encoding,custom-header-1,x-accept-content-transfer-encoding,x-accept-response-streaming,x-user-agent,x-grpc-web,grpc-timeout max_age: "1728000" expose_headers: custom-header-1,grpc-status,grpc-message routes: - match: prefix: "/" route: cluster: edge_cluster host_rewrite_literal: "http.edgecompute.app" http_filters: # CORS filter to handle cross-origin requests - name: envoy.filters.http.cors typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.cors.v3.Cors # External processor filter calls the NGWAF agent via gRPC - name: envoy.filters.http.ext_proc typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.ext_proc.v3.ExternalProcessor grpc_service: envoy_grpc: cluster_name: sigsci-agent-grpc timeout: 0.2s failure_mode_allow: true message_timeout: 0.2s # Request attributes sent to the external processor request_attributes: - "connection.tls_version" - "request.host" - "request.path" - "request.scheme" - "source.address" processing_mode: request_header_mode: SEND response_header_mode: SEND request_body_mode: BUFFERED response_body_mode: NONE request_trailer_mode: SKIP response_trailer_mode: SKIP # Router filter (must be last) - name: envoy.filters.http.router typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router clusters: # Cluster for forwarding requests to the upstream service - name: edge_cluster connect_timeout: 0.25s type: LOGICAL_DNS lb_policy: ROUND_ROBIN dns_lookup_family: V4_ONLY # Force IPv4-only DNS resolution load_assignment: cluster_name: edge_cluster endpoints: - lb_endpoints: - endpoint: address: socket_address: address: http.edgecompute.app port_value: 443 # TLS configuration for upstream HTTPS connection transport_socket: name: envoy.transport_sockets.tls typed_config: "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext sni: "http.edgecompute.app" # Cluster used by the external processor filter to contact the NGWAF agent - name: sigsci-agent-grpc connect_timeout: 0.25s type: STATIC lb_policy: ROUND_ROBIN http2_protocol_options: {} # Enable HTTP/2 for gRPC communication load_assignment: cluster_name: sigsci-agent-grpc endpoints: - lb_endpoints: - endpoint: address: socket_address: # Both containers share the same network namespace address: 127.0.0.1 port_value: 9999 --- # Deployment: Combines the Envoy proxy and the Next‑Gen WAF Agent sidecar apiVersion: apps/v1 kind: Deployment metadata: name: envoy-waf-deployment spec: replicas: 1 selector: matchLabels: app: envoy-waf template: metadata: labels: app: envoy-waf spec: containers: # Envoy proxy container - name: envoy image: envoyproxy/envoy:v1.31-latest args: - "-c" - "/etc/envoy/envoy.yaml" - "-l" - "debug" # Change to "trace" for even more verbosity ports: - containerPort: 10000 volumeMounts: - name: envoy-config mountPath: /etc/envoy # Next‑Gen WAF Agent container (sigsci-agent) - name: sigsci-agent image: signalsciences/sigsci-agent:latest imagePullPolicy: IfNotPresent env: - name: SIGSCI_ACCESSKEYID valueFrom: secretKeyRef: name: sigsci.test key: accesskeyid - name: SIGSCI_SECRETACCESSKEY valueFrom: secretKeyRef: name: sigsci.test key: secretaccesskey # Configure agent for Envoy external processor integration - name: SIGSCI_ENVOY_EXTPROC_ENABLED value: "true" - name: SIGSCI_ENVOY_GRPC_ADDRESS value: "localhost:9999" - name: SIGSCI_DEBUG_LOG_VERBOSITY value: "3" - name: SIGSCI_SERVER_FLAVOR value: "envoy-sidecar" ports: - containerPort: 9999 securityContext: # The sigsci-agent container should run with its root filesystem read only readOnlyRootFilesystem: true volumeMounts: - name: sigsci-tmp mountPath: /sigsci/tmp volumes: - name: envoy-config configMap: name: envoy-config # Define a volume where sigsci-agent will write temp data and share the socket file, # which is required with the root filesystem is mounted read only - name: sigsci-tmp emptyDir: {} --- # Service: Exposes the Envoy listener on port 10000 apiVersion: v1 kind: Service metadata: name: envoy spec: selector: app: envoy-waf ports: - protocol: TCP port: 10000 targetPort: 10000 ``` ## Related content - [Kubernetes installation overview](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/kubernetes-intro) - [Kubernetes agent scaling](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/kubernetes-agent-scaling)