Skip to main content

Traefik

CrowdSec

📚 Documentation 💠 Hub 💬 Discourse

ModeStream only
MetricsUnsupported
MTLSUnsupported
PrometheusSupported

Enable the CrowdSec plugin​

Before you create the middleware, Traefik must load the CrowdSec plugin from its experimental plugins catalog. Pick one of the following approaches and ensure the plugin name (bouncer) matches the key used later in the middleware examples.

Direct configuration​

Add the plugin to the static configuration that Traefik reads at startup:

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

Restart Traefik after updating the static configuration. To enable the plugin through arguments instead, pass the matching flags (or their environment variable counterparts) when starting Traefik:

traefik \
  --experimental.plugins.bouncer.modulename=github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin \
  --experimental.plugins.bouncer.version=v1.5.4

Helm chart values​

When you deploy Traefik with the official Helm chart, define the plugin under experimental.plugins:

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

Apply the updated values (for example with helm upgrade) so Traefik restarts with the plugin enabled. Check the plugin page for the latest available version to pin here.

Traefik on kubernetes​

Traefik expects a resource of "Middleware" type named "bouncer", which we will create now.

Here is bouncer-middleware.yaml:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: bouncer
  namespace: traefik
spec:
  plugin:
    bouncer:
      enabled: true
      crowdsecMode: stream
      crowdsecLapiScheme: https
      crowdsecLapiHost: crowdsec-service.crowdsec:8080
      crowdsecLapiKey: mysecretkey12345

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: "/"
      crowdsecLapiTLSInsecureVerify: true

You can see all the configuration options in the bouncer documentation. You can also refer to a full traefik and CrowdSec stack on kubernetes

Now, you can install the remediation component:

kubectl apply -f bouncer-middleware.yaml

Treafik Behind an Upstream Proxy or Load Balancer​

When Traefik operates behind another proxy (such as a load balancer, CDN, etc ...), the source IP seen by Traefik may be the wrong one instead of the real client. To ensure Crowdsec applies decisions correctly based on the real client IP, it's crucial to properly forward and trust headers.

First you configure Treafik to trust the upstream forwarded headers. Traefik has forwardedHeaders.trustedIPs and proxyProtocol.trustedIPs directives.

Then, you need to configure the middleware to trust as well the IP:

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

When using proxyProtocol.trustedIPs Traefik replaces X-Real-Ip, you can also add :

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