From 0a19c87ae91355eb68f2497c311ec92ac0a69eda Mon Sep 17 00:00:00 2001 From: Ivo Gosemann Date: Mon, 17 Aug 2026 10:42:48 +0200 Subject: [PATCH] Add debug support for Tiltfile and Makefile This allows to debug against the KIND cluster from the IDE Add a sample section to show how to use this to debug the operator with VSCode Signed-off-by: Ivo Gosemann --- Makefile | 4 ++ Tiltfile | 10 +++- docs/.vitepress/config.mts | 7 +++ docs/developer-guide/index.md | 5 ++ .../local-debug-environment.md | 56 +++++++++++++++++++ 5 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 docs/developer-guide/index.md create mode 100644 docs/developer-guide/local-debug-environment.md diff --git a/Makefile b/Makefile index d1d223278..b912d241e 100644 --- a/Makefile +++ b/Makefile @@ -415,3 +415,7 @@ kind-delete: kind ## Destroys the kind cluster. .PHONY: tilt-up tilt-up: $(KUSTOMIZE) kind-create ## Start tilt and create the kind cluster if needed tilt up --context kind-$(KIND_CLUSTER_NAME) + +.PHONY: tilt-debug-up +tilt-debug-up: export DEBUG = true +tilt-debug-up: tilt-up diff --git a/Tiltfile b/Tiltfile index 712e3f20b..fcec4d795 100644 --- a/Tiltfile +++ b/Tiltfile @@ -46,6 +46,11 @@ provider = os.getenv('PROVIDER', 'openconfig') manager = kustomize('config/develop') manager = str(manager).replace('--provider=openconfig', '--provider={}'.format(provider)) +debug = os.getenv('DEBUG', '') == 'true' +if debug: + # Scale the in-cluster manager to 0 so it can be run locally in a debugger. + manager = str(manager).replace('replicas: 1', 'replicas: 0') + k8s_yaml(blob(manager)) k8s_resource('network-operator-controller-manager', resource_deps=['controller-gen'], labels=['operator']) @@ -57,7 +62,10 @@ def device_yaml(): decoded[0]['spec']['endpoint']['address'] = ip+':9339' return encode_yaml_stream(decoded) -k8s_yaml(device_yaml()) +if debug: + k8s_yaml('./config/samples/v1alpha1_device.yaml') +else: + k8s_yaml(device_yaml()) k8s_resource(new_name='leaf1', objects=['leaf1:device', 'secret-basic-auth:secret'], trigger_mode=TRIGGER_MODE_MANUAL, auto_init=False, labels=['samples']) k8s_yaml('./config/samples/v1alpha1_interface.yaml') diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index b92092f59..34e11a44d 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -92,6 +92,13 @@ export default withMermaid({ { text: 'EVPN/VXLAN Fabric', link: '/tutorials/evpn-vxlan-fabric' }, ], }, + { + text: 'Developer Guide', + items: [ + { text: 'Index', link: '/developer-guide/' }, + { text: 'Local Debug Environment', link: '/developer-guide/local-debug-environment' }, + ], + }, { text: 'Design Documents', items: [ diff --git a/docs/developer-guide/index.md b/docs/developer-guide/index.md new file mode 100644 index 000000000..a71a23888 --- /dev/null +++ b/docs/developer-guide/index.md @@ -0,0 +1,5 @@ +# Developer Guide + +This section covers workflows for contributing to and developing the Network Operator. + +- [Local Debug Environment](./local-debug-environment.md) — Run and debug the controller locally against a Kind cluster from your IDE. diff --git a/docs/developer-guide/local-debug-environment.md b/docs/developer-guide/local-debug-environment.md new file mode 100644 index 000000000..3424b891b --- /dev/null +++ b/docs/developer-guide/local-debug-environment.md @@ -0,0 +1,56 @@ +# Local Debug Environment + +The Tilt setup can scale the in-cluster controller to zero replicas so you can run the manager locally in a debugger, attached to the same Kind cluster. This lets you set breakpoints and step through reconciliation while all other resources (CRDs, cert-manager, Prometheus, sample CRs) still live in the cluster. + +## Prerequisites + +- [Kind](https://kind.sigs.k8s.io/), [Tilt](https://tilt.dev/), and `kubectl` installed +- An IDE with a Go debugger (the repo ships a VS Code `launch.json`) + +## Starting Tilt in debug mode + +```bash +make tilt-debug-up +``` + +This sets `DEBUG=true` and runs `make tilt-up`, which creates the Kind cluster if needed. In debug mode the `Tiltfile`: + +- Scales the `network-operator-controller-manager` Deployment to `replicas: 0`, freeing the cluster to be reconciled by your locally running manager instead. +- Applies the `Device` sample verbatim (skipping the `host.docker.internal` address rewrite used by the normal in-cluster flow). +- Update the `config/samples/device_v1alpha1_device.yaml` file to point to a real device on your network to test against a real device. + +Everything else — CRDs, cert-manager, Prometheus, and the manually triggered sample resources — is deployed exactly as in a normal `make tilt-up` run. + +## Launching the debugger + +With Tilt running, start the manager from your IDE. In VS Code, add a launch configuration to `.vscode/launch.json`: + +```json +{ + "name": "Kind Debug", + "type": "go", + "request": "launch", + "mode": "debug", + "program": "${workspaceFolder}/cmd", + "env": { + "KUBECONFIG": "${workspaceFolder}/.vscode/network-kind.kubeconfig", + "ENABLE_WEBHOOKS": "false" + }, + "args": [ + "--max-concurrent-reconciles", + "10", + "--provider", + "openconfig", + "--requeue-interval", + "30s" + ] +} +``` + +Key settings: + +- `KUBECONFIG` points at the Kind cluster (export the kubeconfig with `kind get kubeconfig --name network-operator > .vscode/network-kind.kubeconfig`). +- `ENABLE_WEBHOOKS=false` — webhooks require the in-cluster certificate setup, so they are disabled when debugging locally. +- `--provider`, `--max-concurrent-reconciles`, and `--requeue-interval` match the flags the in-cluster manager runs with. Adjust `--provider` to the platform you are targeting. + +Pick this configuration in the **Run and Debug** view and start it. Set breakpoints in the controller or provider code and trigger a sample resource in the Tilt UI to hit them.