Skip to main content

Kubernetes Deployment

Before getting started, it is advised to read the introduction page to understand the prerequisites and concepts for running CrowdSec.

Requirements​

Even if an installation could be possible without Helm, it's not documented for now.

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 Security Engine​

Once the helm repository is added, first you need to write your crowdsec-values.yaml file. You can use the following 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.

If you want more information about the configuration, you can check 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 do its job in Kubernetes, it needs to see the real client IP. If not, every request will just look like it’s coming from your ingress controller or load balancer, and CrowdSec won’t know who the actual attacker is. To fix this, you need to make sure the original IP gets passed through. Depending on your setup, that could mean turning on the proxy-protocol in your ingress, setting externalTrafficPolicy: Local on Services, or tweaking things like real_ip_header and set_real_ip_from if you’re using NGINX. The exact steps depend on your stack, but the main idea is simple: CrowdSec needs the real IP, not the proxy’s.

A Word About Remediation Component​

Installing the CrowdSec Engine as a local API and log processors is very useful to detect aggressive behaviors, but no remediation action will be taken upon it. To get remediation actions, one has to install remediation component. As of now remediation can only happen at 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, you need to generate 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

Else you don't have persistentVolumes enabled, you need to 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.