From 7d25703811de9ae2e13580eadd92535264f7f2b0 Mon Sep 17 00:00:00 2001 From: alliasgher Date: Sun, 26 Apr 2026 18:54:46 +0500 Subject: [PATCH] docs: add debugging tips to DEVELOPMENT.md Adds a 'Debugging the controller locally' section covering knobs that are not already in 'How to run the controller locally': - RUNTIME_NAMESPACE to scope the watch - --concurrent=1 to serialize reconciles for a clean trace - flux suspend for unrelated objects sharing the cluster Assisted-by: Claude/claude-opus-4-7 Signed-off-by: alliasgher --- DEVELOPMENT.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 4bb0bd7f8..c47990c39 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -77,4 +77,44 @@ Deploy `notification-controller` into the cluster that is configured in the loca ```sh make deploy -``` \ No newline at end of file +``` + +## Debugging the controller locally + +When reproducing an issue or stepping through reconciliation logic, the +following knobs make local runs cheaper and the resulting logs easier to +read. + +### Limit the watched namespace + +The controller watches every namespace by default. To narrow it to a single +namespace, set the `RUNTIME_NAMESPACE` environment variable before invoking +`make run`: + +```sh +RUNTIME_NAMESPACE=flux-system make run +``` + +### Reduce reconcile concurrency + +Each `Alert`, `Provider`, and `Receiver` reconcile is processed concurrently +(default `--concurrent=4`). When debugging it is almost always easier to +follow a serial trace; pass `--concurrent=1` so reconciles run one at a +time: + +```sh +go run ./main.go --concurrent=1 +``` + +### Suspend unrelated objects + +If the controller is sharing a cluster with other Flux objects, suspend +anything not relevant to the test you're running so their reconciles don't +interleave with yours: + +```sh +flux suspend alert +flux suspend receiver +``` + +Resume them with `flux resume` when you're done.