Skip to main content

Install on Kubernetes

New to CrowdSec? Start with the introduction to understand the components and prerequisites.

This page installs the Security Engine (detection). For blocking, install a Remediation Component after the engine is running.

Requirements​

You can install without Helm, but it is not documented yet.

Helm Repository Installation​

Add the CrowdSec helm repository to your Helm installation:

helm repo add crowdsec https://crowdsecurity.github.io/helm-charts
helm repo update

Install the Security Engine​

Once the Helm repository is added, create a crowdsec-values.yaml file. You can start with this example:

# for raw logs format: json or cri (docker|containerd)
container_runtime: containerd
agent:
  # Specify each pod whose logs you want to process
  acquisition:
    # The namespace where the pod is located
    - namespace: traefik
      # The pod name
      podName: traefik-*
      # as in crowdsec configuration, we need to specify the program name to find a matching parser
      program: traefik
  env:
    - name: COLLECTIONS
      value: "crowdsecurity/traefik"
lapi:
  env:
    # To enroll the Security Engine to the console
    - name: ENROLL_KEY
      value: "<enroll-key>"
    - name: ENROLL_INSTANCE_NAME
      value: "my-k8s-cluster"
    - name: ENROLL_TAGS
      value: "k8s linux test"

Acquisition is done by reading logs directly from pods. You select which pods to watch thanks to namespace and podName, and you have to tag the logs with a program so CrowdSec knows which parser should handle them. For example, if you set program: nginx, the nginx parser will pick them up. CrowdSec will automatically attach to the right pods and feed the logs into the right parsers.

Why program and not type ?

In standard standalone setups, documentation states that the labels should be name type with the type being the parsed log program (eg nginx, traefik). A transformation from type to program is done by the first stage parser crowdsecurity/syslog-logs which is not relevant in a Kubernetes context.

How collections fit in kubernetes environment?

Collections are "recipes" for understanding logs; they don’t find pods on their own. You choose which pods to read, and you tag those logs with a program (like nginx or traefik). When the tag matches what a collection expects, its rules run; if it doesn’t, they stay idle. One log stream can match several collections if the tags fit.

For full configuration options, see the default values.yaml

Then, you can install the Security Engine with the following command:

# Create a namespace for crowdsec
kubectl create ns crowdsec
# Install the helm chart
helm install crowdsec crowdsec/crowdsec -n crowdsec -f crowdsec-values.yaml

Check the installation status:

kubectl -n crowdsec get pods
Command Output
NAME READY STATUS RESTARTS AGE
crowdsec-agent-kf9fr 1/1 Running 0 34s
crowdsec-lapi-777c469947-jbk9q 1/1 Running 0 34s

A word about source IPs​

For CrowdSec to work in Kubernetes, it must see the real client IP. Otherwise every request looks like it came from your ingress controller or load balancer. Make sure the original IP is passed through (for example, proxy-protocol on ingress, externalTrafficPolicy: Local on Services, or real_ip_header and set_real_ip_from with NGINX). The exact steps depend on your stack, but the goal is always the same: CrowdSec needs the real IP, not the proxy's.

A word about Remediation Components​

Installing the Security Engine (LAPI + agent) enables detections, but it does not block anything by itself. To enforce decisions, install a remediation component. In Kubernetes, remediation is currently done at the ingress level.

For now, we support:

Please note that the Traefik Kubernetes Ingress (third-party development)) is maintained outside CrowdSec.

Before installing the remediation component, generate an API key to communicate with the LAPI.

If you have persistentVolumes enabled in values.yaml, you can generate the API key directly from the LAPI pod:

kubectl -n crowdsec exec -it crowdsec-lapi-<pod-id> -- cscli bouncers add my-bouncer-name

If you do not have persistentVolumes enabled, specify your key in the crowdsec helm values.yaml file:

lapi:
  env:
    - name: BOUNCER_KEY_<name>
      value: "<bouncer-key>"

example:

lapi:
  env:
    - name: BOUNCER_KEY_traefik
      value: "mysecretkey12345"

A word about databases​

By default, CrowdSec uses a SQLite database, which does not support replication. In a Kubernetes environment, this limitation prevents the Local API from being replicated.

For production deployments on Kubernetes, we recommend using a database engine that can be deployed in a replicated or highly available way, such as MariaDB or PostgreSQL. You can leverage existing operators to manage these databases:

Configuration those databases is out of scope of this documentation.

SQLite may be suitable for testing or low traffic clusters, but it is not recommended for Kubernetes production deployments. Besides the lack of replication, SQLite can also become a performance bottleneck under heavy load.

Next steps​

Great, you now have CrowdSec installed on your system. Within the post installation steps you will find the next steps to configure and optimize your installation.