Skip to main content

Traefik (Kubernetes)

CrowdSec

📚 Documentation 💠 Hub 💬 Discourse

ModeStream only
MetricsUnsupported
MTLSSupported
PrometheusSupported

Traefik on kubernetes​

This remediation component is community developed and maintained. You can see all the configuration options in the bouncer documentation. You can also refer to a full traefik and CrowdSec stack on kubernetes or our Appsec Traefik Quickstart.

This piece of documentation is rather an howto than a full fledge documentation.

Prerequesites​

Source IPs​

To ensure remediation works correctly, Traefik must receive the actual client IP for every request. When Traefik is deployed behind an upstream proxy or load balancer, the source IP may otherwise be replaced with the proxy’s address. Traefik Behind an Upstream Proxy or Load Balancer

When Traefik operates behind a load balancer, CDN, or any intermediate proxy, proper forwarding and trust of client IP information is required for CrowdSec to apply decisions accurately.

Traefik must first be configured to trust the upstream IP ranges. This is done using the forwardedHeaders.trustedIPs and proxyProtocol.trustedIPs entrypoint settings, depending on whether the environment relies on forwarded headers or the PROXY protocol.

The CrowdSec bouncer middleware then also needs to trust these same ranges:

spec:
  plugin:
    bouncer:
      forwardedHeadersTrustedIps: <trusted-cidr>

In case the header in which the ip is set is not X-Forwarded-For, it can be set with:

spec:
  plugin:
    bouncer:
      forwardedHeadersCustomName: X-Real-Ip

Correctly forwarding and trusting these headers ensures that both Traefik and CrowdSec operate on the real client IP, which is required for IP-based remediation.

Side note about source ip with CrowdSec and Kubernetes

Source IP addresses are essential in a CrowdSec deployment for two reasons. First, the log processor must know which IPs are responsible for triggering scenarios. Second, the remediation component needs to identify the originating IP of incoming requests in order to apply the appropriate action.

In a Kubernetes environment, this requires disabling source NAT on nodes so that the CrowdSec-monitored service pods receive the real client IP. As a consequence, the Service’s externalTrafficPolicy must be set to Local, and the workload (Traefik or any ingress/controller) must run either as a DaemonSet or as a Deployment ensuring one pod per node. This guarantees that no traffic — and therefore no security events — is missed.

Traefik Custom Resources Definition​

Traefik’s CRDs provide the custom resource types (such as Middleware) required for configuring Traefik through the Kubernetes CRD provider. CrowdSec remediation relies on one of these resources to declare the CrowdSec bouncer middleware. Without the CRDs, this middleware cannot be created or used, and Traefik is unable to apply CrowdSec decisions.

Here is the command sequence to install the Traefik CRDs via the Helm chart:

helm repo add traefik https://traefik.github.io/charts
helm repo update
helm upgrade --install traefik-crds traefik/traefik-crds -n traefik --create-namespace

Experimental plugin loading ability​

CrowdSec Bouncer Traefik Plugin can't be enabled via CLI flags alone, one has to enable the experimental plugin load. This can be done by adding this snippet to Traefik helm's chart values:

experimental:
  plugins:
    crowdsec-bouncer-traefik-plugin:
      moduleName: "github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin"
      version: "v1.4.5"

Middleware​

To achieve remediation in a Traefik environment, one has to use a "Middleware" resource.

Here is bouncer-middleware.yaml:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: bouncer
  namespace: traefik
spec:
  plugin:
    bouncer:
      enabled: true
      crowdsecMode: stream
      crowdsecLapiHost: crowdsec-service.default.svc.cluster.local:8080
      crowdsecLapiKey: <YOUR-BOUNCER-KEY>

Now, you can install the remediation component:

kubectl apply -f bouncer-middleware.yaml

Traefik with WAF(appsec) on kubernetes​

We supposed you already have working crowdsec values configuration, basically here is the important configuration to put in crowdsec values :

config:
  config.yaml.local: |
    api:
      server:
        auto_registration:
          enabled: true
          token: "${REGISTRATION_TOKEN}" # /!\ Do not modify this variable (auto-generated and handled by the chart)
          allowed_ranges:
            - "127.0.0.1/32"
            - "192.168.0.0/16"
            - "10.0.0.0/8"
            - "172.16.0.0/12"
appsec:
  enabled: true
  acquisitions:
    - source: appsec
      listen_addr: "0.0.0.0:7422"
      path: /
      appsec_configs:
        - crowdsecurity/appsec-default
        - crowdsecurity/crs
      labels:
        type: appsec
  env:
    - name: COLLECTIONS
      value: "crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-crs crowdsecurity/appsec-generic-rules"
lapi:
  env:
    - name: BOUNCER_KEY_traefik
      value: <YOUR-BOUNCER-KEY>

If you add this config to crowdsec values, don't forget to helm upgrade

Then the configuration for the middleware (bouncer-middleware.yaml) :

kind: Middleware
apiVersion: traefik.io/v1alpha1
metadata:
  name: bouncer
  namespace: traefik
spec:
  plugin:
    bouncer:
      enabled: true
      crowdsecMode: stream
      crowdsecLapiScheme: http
      crowdsecLapiHost: crowdsec-service.default.svc.cluster.local:8080
      crowdsecAppsecEnabled: true
      crowdsecAppsecHost: crowdsec-appsec-service.default.svc.cluster.local:7422
      crowdsecAppsecPath: "/"
      crowdsecAppsecFailureBlock: true
      crowdsecAppsecUnreachableBlock: true
      crowdsecAppsecBodyLimit: 10485760
      crowdsecLapiKey: <YOUR-BOUNCER-KEY>
      crowdsecLapiPath: "/"

Now, you can install or update the remediation component:

kubectl apply -f bouncer-middleware.yaml