document Falco alerting secret

deployments/falco/README.md

@@ -0,0 +1,49 @@
+# Falco alerting secret
+
+Falco alert delivery must use a Kubernetes Secret. Do not commit a Slack
+Incoming Webhook URL, Slack token, Discord webhook URL, or generated Secret
+manifest to this repository.
+
+The expected Secret contract for the future alerting configuration is:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: falco-alerting
+  namespace: falco
+type: Opaque
+stringData:
+  webhook-url: https://hooks.slack.com/services/REPLACE/ME
+```
+
+The example value is a placeholder. Create the Secret directly on the cluster
+with the real Slack Incoming Webhook URL:
+
+```bash
+kubectl create namespace falco --dry-run=client -o yaml | kubectl apply -f -
+kubectl create secret generic falco-alerting \
+  --namespace falco \
+  --from-literal=webhook-url='https://hooks.slack.com/services/REPLACE/ME' \
+  --dry-run=client -o yaml | kubectl apply -f -
+```
+
+The `webhook-url` key is the interface that the Falco alerting configuration
+will consume. The Secret is intentionally not included in the Falco
+Kustomization because ArgoCD must not manage or render the credential from
+Git.
+
+Verify only the Secret name and key, never the value:
+
+```bash
+kubectl get secret falco-alerting -n falco \
+  -o jsonpath='{.metadata.name}{" keys: "}{range $key, $value := .data}{$key}{" "}{end}{"\n"}'
+```
+
+Avoid printing Secret data in shared terminals or CI logs. To rotate the
+webhook, update the Secret in place with the creation command and restart the
+Falco workloads after the alerting integration is configured.
+
+The repository currently verifies Falco runtime detections locally. Webhook
+delivery remains a separate configuration step because it requires an
+interactive Slack or Discord credential.