Add debug support for Tiltfile and Makefile

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

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')

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: [

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.

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.