Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
264 lines (202 loc) · 6.59 KB

DEPLOYMENT.md

File metadata and controls

264 lines (202 loc) · 6.59 KB
Raw

Deployment Guide

Table of Contents

Binary Installation

Install from Go

go install github.com/kdwils/envoy-proxy-bouncer@v<tag>

Download Pre-built Binary

Check the releases page for pre-built binaries.

Running the Binary

# Start the bouncer
envoy-proxy-bouncer serve --config config.yaml

# Check if an IP should be bounced
envoy-proxy-bouncer bounce -i 192.168.1.1,10.0.0.1

# Show version
envoy-proxy-bouncer version

Docker

Docker Run

docker run -d \
  --name envoy-proxy-bouncer \
  -p 8080:8080 \
  -p 8081:8081 \
  -e ENVOY_BOUNCER_BOUNCER_APIKEY=your-api-key \
  -e ENVOY_BOUNCER_BOUNCER_LAPIURL=http://crowdsec:8080 \
  ghcr.io/kdwils/envoy-proxy-bouncer:latest

Docker Compose

version: '3.8'

services:
  envoy-proxy-bouncer:
    image: ghcr.io/kdwils/envoy-proxy-bouncer:latest
    container_name: envoy-proxy-bouncer
    ports:
      - "8080:8080"  # gRPC port
      - "8081:8081"  # HTTP port (CAPTCHA)
    environment:
      ENVOY_BOUNCER_BOUNCER_APIKEY: your-api-key
      ENVOY_BOUNCER_BOUNCER_LAPIURL: http://crowdsec:8080
      ENVOY_BOUNCER_SERVER_LOGLEVEL: info
    restart: unless-stopped
    networks:
      - crowdsec

  crowdsec:
    image: crowdsecurity/crowdsec:latest
    container_name: crowdsec
    environment:
      COLLECTIONS: "crowdsecurity/linux crowdsecurity/nginx"
    volumes:
      - ./crowdsec/config:/etc/crowdsec
      - ./crowdsec/data:/var/lib/crowdsec/data
    networks:
      - crowdsec

networks:
  crowdsec:

Kubernetes

Manifest File

See examples/deploy/README.md for a flat YAML deployment example.

You can also reference this homelab manifest for a complete example.

Helm

The chart is available via OCI at oci://ghcr.io/kdwils/charts/envoy-proxy-bouncer.

Basic Installation

helm install bouncer oci://ghcr.io/kdwils/charts/envoy-proxy-bouncer \
  --namespace envoy-gateway-system \
  --create-namespace \
  --set config.bouncer.apiKey=<lapi-key> \
  --set config.bouncer.lapiURL=http://crowdsec.monitoring:8080

Installation with Values File

For complete chart configuration options and values, see the Helm Chart README.

Install with values:

helm install bouncer oci://ghcr.io/kdwils/charts/envoy-proxy-bouncer \
  --namespace envoy-gateway-system \
  --create-namespace \
  -f values.yaml

Upgrade

helm upgrade bouncer oci://ghcr.io/kdwils/charts/envoy-proxy-bouncer \
  --namespace envoy-gateway-system \
  -f values.yaml

Uninstall

helm uninstall bouncer --namespace envoy-gateway-system

Envoy Gateway Integration

The bouncer integrates with Envoy Gateway using SecurityPolicies that reference the ext_authz filter. SecurityPolicies must be created at the HTTPRoute level, not at the Gateway level, and in the same namespace as your HTTPRoutes:

SecurityPolicy Configuration

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: media-security
  namespace: media
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: plex
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: overseerr
  extAuth:
    grpc:
      backendRefs:
        - group: ""
          kind: Service
          name: envoy-proxy-bouncer
          port: 8080
          namespace: envoy-gateway-system

Request Body Forwarding

By default, Envoy does not forward the request body to the external authorization service. To enable WAF inspection of POST payloads (e.g., SQL injection, XSS in JSON bodies), you must configure bodyToExtAuth:

 apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: SecurityPolicy
 metadata:
   name: media-security
   namespace: media
 spec:
   targetRefs:
     - group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: plex
   extAuth:
+    bodyToExtAuth:
+      maxRequestBytes: 65536
     grpc:
       backendRefs:
         - group: ""
           kind: Service
           name: envoy-proxy-bouncer
           port: 8080
           namespace: envoy-gateway-system

The maxRequestBytes field controls the maximum body size Envoy will buffer and forward. A value of 65536 (64KB) covers most API requests and form submissions while keeping memory usage manageable. Without this configuration, the WAF can only inspect URL-based attacks (query strings, paths) and will miss attacks embedded in request bodies.

ReferenceGrant Configuration

When SecurityPolicies reference services in different namespaces, a ReferenceGrant is required.

Using Helm

The Helm chart can automatically create ReferenceGrants. For configuration details, see the Helm Chart README.

Manual ReferenceGrant

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: bouncer-access
  namespace: envoy-gateway-system
spec:
  from:
  - group: gateway.envoyproxy.io
    kind: SecurityPolicy
    namespace: media
  - group: gateway.envoyproxy.io
    kind: SecurityPolicy
    namespace: blog
  - group: gateway.envoyproxy.io
    kind: SecurityPolicy
    namespace: argocd
  to:
  - group: ""
    kind: Service
    name: envoy-proxy-bouncer

Health Checks

The bouncer does not currently expose health check endpoints. Monitor the service using:

Kubernetes Readiness

Check pod status:

kubectl get pods -n envoy-gateway-system -l app=envoy-proxy-bouncer

Check logs:

kubectl logs -n envoy-gateway-system -l app=envoy-proxy-bouncer -f

gRPC Health Check

Use grpcurl to test the ext_authz endpoint:

# Install grpcurl
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# Test connection
grpcurl -plaintext localhost:8080 list

See Also