improved docs

Author: sabban

crowdsec-docs/unversioned/getting_started/installation/kubernetes.mdx

@@ -12,14 +12,16 @@ import CodeBlock from '@theme/CodeBlock';
 
 # Kubernetes Deployment
 
-Before getting started, it is advised to read the [introduction](/unversioned/getting_started/introduction.mdx) page to understand the prerequisites and concepts for running CrowdSec.
+Before getting started, it is advised to read the
+[introduction](/unversioned/getting_started/introduction.mdx) page to understand
+the prerequisites and concepts for running CrowdSec.
 
 ## Requirements
 
 - [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
 - [Helm](https://helm.sh/docs/intro/install/)
 
-Even if an installation could be possible without Helm, it's not supported for now.
+Even if an installation could be possible without Helm, it's not documented for now.
 
 ## Helm Repository Installation
 
@@ -60,7 +62,32 @@ lapi:
       value: "k8s linux test"
 ```
 
-If you want more information about the configuration, you can check the default [values.yaml](https://artifacthub.io/packages/helm/crowdsec/crowdsec#values)
+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.
+
+<detail>
+    <summary>Why `program` and not `type` ?</summary>
+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.
+</details>
+
+<detail>
+    <summary>How collection fit in kubernetes environment?</summary>
+
+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.
+</details>
+
+If you want more information about the configuration, you can check the default
+[values.yaml](https://artifacthub.io/packages/helm/crowdsec/crowdsec#values)
 
 Then, you can install the Security Engine with the following command:
 
@@ -82,6 +109,18 @@ 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
@@ -91,8 +130,12 @@ remediation can only happen at ingress level.
 
 For now, we support:
 
-* [Ingress Nginx](u/bouncers/ingress-nginx/)
-* [Traefik Kubernetes Ingress (Third party development)](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin)
+* [Ingress Nginx](/u/bouncers/ingress-nginx/)
+* [Traefik Ingress](/u/bouncers/traefik/)
+
+Please note that the [Traefik Kubernetes Ingress (Third party
+development)](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin))
+is maintained outside CrowdSec
 
 Before installing the remediation component, you need to generate API key to communicate with the LAPI.