From b7ec8f4efcf6516b6f7fb3f80bebc0ee69ff8223 Mon Sep 17 00:00:00 2001
From: Ali <alliasgher123@gmail.com>
Date: Sun, 19 Apr 2026 12:19:53 +0500
Subject: [PATCH] docs: add debugging tips to DEVELOPMENT.md

Expand the local development guide with concrete tips for debugging
controller issues, as requested in #666:

- RUNTIME_NAMESPACE env var to limit watched namespaces
- --concurrent=1 flag to serialise reconcile loops
- HOSTNAME env var for leader election identity
- How to suspend irrelevant Flux objects to reduce log noise
- How to scale down the in-cluster deployment to avoid conflicts

Signed-off-by: Ali <alliasgher123@gmail.com>
---
 DEVELOPMENT.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 11d05ad83..b1ca2fcb9 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -54,6 +54,62 @@ Run the controller locally:
 make run
 ```
 
+### Debugging tips
+
+**Limit watched namespaces**
+
+Set `RUNTIME_NAMESPACE` to restrict the controller to a single namespace,
+which reduces noise when debugging a specific issue:
+
+```sh
+export RUNTIME_NAMESPACE=flux-system
+make run
+```
+
+**Decrease concurrency**
+
+Lower `--concurrent` to `1` so that reconcile loops run sequentially,
+making it easier to follow logs and reproduce ordering issues:
+
+```sh
+make run ARGS="--concurrent=1"
+```
+
+**Set the controller hostname**
+
+The controller uses the `HOSTNAME` environment variable as its identity
+for leader election. When running locally, set it to match the
+in-cluster deployment name to avoid lease conflicts:
+
+```sh
+export HOSTNAME=source-controller
+make run
+```
+
+**Suspend irrelevant objects**
+
+Suspend Flux objects that are unrelated to the issue you are
+investigating so that their reconciliation does not add log noise:
+
+```sh
+kubectl -n flux-system patch gitrepository <name> \
+  --type=merge -p '{"spec":{"suspend":true}}'
+```
+
+Replace `gitrepository` with `helmrepository`, `ocirepository`, or
+`bucket` as appropriate.
+
+**Scale down the in-cluster controller**
+
+If `source-controller` is already running in your cluster, scale it
+down before running locally to avoid competing reconciliations:
+
+```sh
+kubectl -n flux-system scale deployment/source-controller --replicas=0
+# restore when done:
+kubectl -n flux-system scale deployment/source-controller --replicas=1
+```
+
 ## How to install the controller
 
 ### Building the container image