From ee5f201399e6f5fc6c7219fb030a935b6e305c99 Mon Sep 17 00:00:00 2001
From: alliasgher <alliasgher123@gmail.com>
Date: Sun, 26 Apr 2026 18:54:52 +0500
Subject: [PATCH 1/2] 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 <alliasgher123@gmail.com>
---
 DEVELOPMENT.md | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index a6731190..bb49e138 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -52,4 +52,44 @@ If you made any changes to CRDs API, you can update CRDs API reference doc by
 
 ```bash
 make api-docs
-```
\ 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 `ImageRepository` and `ImagePolicy` 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 image repository <name>
+flux suspend image policy <name>
+```
+
+Resume with `flux resume image repository|policy <name>` when you're done.

From 48d49d9e043aa91afc8fec2b843f4c32022c185e Mon Sep 17 00:00:00 2001
From: Ali <alliasgher123@gmail.com>
Date: Fri, 12 Jun 2026 19:53:09 +0500
Subject: [PATCH 2/2] docs: include --storage-path in --concurrent debugging
 example

main.go defaults --storage-path to /data, which does not exist on a dev
machine. Match the make run target's ./data path so the example works
alongside the rest of the guide.

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

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index bb49e138..a13e970f 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -78,7 +78,7 @@ follow a serial trace; pass `--concurrent=1` so reconciles run one at a
 time:
 
 ```sh
-go run ./main.go --concurrent=1
+go run ./main.go --storage-path=./data --concurrent=1
 ```
 
 ### Suspend unrelated objects