Skip to content

docs: add debugging tips to DEVELOPMENT.md #1646

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alliasgher wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add debugging tips to DEVELOPMENT.md #1646

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 41 additions & 1 deletion DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,4 +91,44 @@ Deploy `kustomize-controller` into the cluster that is configured in the local k
make deploy
```

Running the above will also deploy `source-controller` and its CRDs to the cluster.
Running the above will also deploy `source-controller` and its CRDs to the cluster.

## 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`:
Comment on lines +104 to +106
Copy link
Copy Markdown
Member

@stefanprodan stefanprodan Apr 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Setting RUNTIME_NAMESPACE does not restrict the watchers, it just tells the controller in which namespace it runs. Watching only the flux-system namespace would break debugging so there is no point in having this Limit the watched namespace section.


```sh
RUNTIME_NAMESPACE=flux-system make run
```

### Reduce reconcile concurrency

Each `Kustomization` reconcile is processed concurrently (default
`--concurrent=4`, plus an independent `--concurrent-ssa=4` for server-side
apply). When debugging it is almost always easier to follow a serial
trace; pass `--concurrent=1 --concurrent-ssa=1` so reconciles and SSA
operations run one at a time:
Comment on lines +112 to +118
Copy link
Copy Markdown
Member

@stefanprodan stefanprodan Apr 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How would you debug goroutine leaks, dead locks and other issues that only surface when concurrency is used? Also if you suspend all objects but the one you are debugging, then setting --concurrent=1 has no effect.


```sh
go run ./main.go --concurrent=1 --concurrent-ssa=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 kustomization <name>
Copy link
Copy Markdown
Member

@stefanprodan stefanprodan Apr 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is an --all flag

```

Resume with `flux resume kustomization <name>` when you're done.