From 9360edd717b8324e2afb7a9a21b2017a143d6fb1 Mon Sep 17 00:00:00 2001 From: Leandro Beretta Date: Mon, 3 Nov 2025 14:10:35 -0300 Subject: [PATCH 1/4] slash commands for setup dev environment and debugging of the operator locally --- .claude/commands/debug-operator.md | 143 +++++++++++++++++++++++++++++ .claude/commands/setup-dev-env.md | 103 +++++++++++++++++++++ .vscode/launch.json | 16 ++++ 3 files changed, 262 insertions(+) create mode 100644 .claude/commands/debug-operator.md create mode 100644 .claude/commands/setup-dev-env.md create mode 100644 .vscode/launch.json diff --git a/.claude/commands/debug-operator.md b/.claude/commands/debug-operator.md new file mode 100644 index 000000000..c079d890c --- /dev/null +++ b/.claude/commands/debug-operator.md @@ -0,0 +1,143 @@ +# Debug NetObserv Operator Locally + +This command prepares the environment for debugging the operator locally. + +**Prerequisites:** You must have already set up the development environment using `/setup-dev-env` before running this command. + +## Steps + +### 1. Scale down the in-cluster operator + +To debug locally, scale down the operator running in the cluster: + +```bash +kubectl scale deployment netobserv-controller-manager -n netobserv --replicas=0 +``` + +### 2. Remove the validating webhook for local development + +```bash +kubectl delete validatingwebhookconfiguration netobserv-validating-webhook-configuration +``` + +This allows you to freely modify the FlowCollector CR while running the operator locally. + +### 3. Run the operator locally + +**Now ask the user which option they prefer:** + +- **Option A: Run with go run** (simple execution without debugging) +- **Option B: Run with delve** (interactive debugging in terminal with dlv commands) +- **Option C: Run with delve headless + VSCode** (debugging with VSCode UI and breakpoints) + +**After the user responds:** + +#### If Option A (go run): +Execute this command: +```bash +go run ./main.go \ + -ebpf-agent-image=quay.io/netobserv/netobserv-ebpf-agent:main \ + -flowlogs-pipeline-image=quay.io/netobserv/flowlogs-pipeline:main \ + -console-plugin-image=quay.io/netobserv/network-observability-console-plugin:main \ + -namespace=netobserv +``` + +#### If Option B (delve interactive): +Execute this command: +```bash +dlv debug ./main.go -- \ + -ebpf-agent-image=quay.io/netobserv/netobserv-ebpf-agent:main \ + -flowlogs-pipeline-image=quay.io/netobserv/flowlogs-pipeline:main \ + -console-plugin-image=quay.io/netobserv/network-observability-console-plugin:main \ + -namespace=netobserv +``` + +This will start an interactive delve session where you can use commands like: +- `break main.main` - set breakpoint +- `continue` - continue execution +- `next` - step to next line +- `print variable` - inspect variables + +#### If Option C (delve headless + VSCode): +**Step 1:** Execute this command to start Delve in headless mode: +```bash +dlv debug ./main.go --headless --listen=:2345 --api-version=2 --accept-multiclient -- \ + -ebpf-agent-image=quay.io/netobserv/netobserv-ebpf-agent:main \ + -flowlogs-pipeline-image=quay.io/netobserv/flowlogs-pipeline:main \ + -console-plugin-image=quay.io/netobserv/network-observability-console-plugin:main \ + -namespace=netobserv +``` + +**Step 2:** Then inform the user: +"Delve is now running in headless mode on port 2345. To connect from VSCode: +1. Open the Debug view (Ctrl+Shift+D / Cmd+Shift+D) +2. Select 'Connect to Delve (Remote - Port 2345)' from the dropdown +3. Press F5 or click 'Start Debugging' + +You can now set breakpoints in VSCode and debug the operator!" + +### 4. Setting your first breakpoint - FlowCollector Reconcile + +**Example: Set a breakpoint in the FlowCollector reconciler** + +The FlowCollector reconciliation logic is located in: +`internal/controller/flowcollector/flowcollector_controller.go` + +**In VSCode:** +1. Open the file `internal/controller/flowcollector/flowcollector_controller.go` +2. Find the `Reconcile` function (around line 100-150) +3. Click on the left margin next to the line number where you want to pause (e.g., the first line inside the Reconcile function) +4. A red dot will appear indicating the breakpoint is set + +**To trigger the reconciliation:** +Execute this command in a terminal to modify the FlowCollector CR: +```bash +kubectl patch flowcollector cluster --type=merge -p '{"spec":{"processor":{"logLevel":"debug"}}}' +``` + +This will trigger a reconciliation and the debugger will pause at your breakpoint, allowing you to: +- Inspect the FlowCollector object +- Step through the reconciliation logic +- See how the operator processes changes +- Debug any issues in the reconciliation loop + +## Using Custom Images + +To debug with your own component builds: + +```bash +# Build and push your custom images first +cd ../netobserv-ebpf-agent +USER=myuser VERSION=dev make images + +cd ../flowlogs-pipeline +USER=myuser VERSION=dev make images + +# Then run the operator with your custom images +cd ../network-observability-operator + +dlv debug ./main.go --headless --listen=:2345 --api-version=2 --accept-multiclient -- \ + -ebpf-agent-image=quay.io/myuser/netobserv-ebpf-agent:dev \ + -flowlogs-pipeline-image=quay.io/myuser/flowlogs-pipeline:dev \ + -console-plugin-image=quay.io/netobserv/network-observability-console-plugin:main \ + -namespace=netobserv +``` + +## Cleanup + +When you're done debugging: + +1. Stop the local operator (Ctrl+C in terminal, or stop debugging in VSCode) + +2. Scale the in-cluster operator back up: +```bash +kubectl scale deployment netobserv-controller-manager -n netobserv --replicas=1 +``` + +**Note:** The validating webhook will be automatically recreated by the operator when it starts back up, so you don't need to manually restore it. + +## Troubleshooting + +- **"Manager already exists" error**: The in-cluster operator is still running. Scale it to 0 replicas. +- **"Connection refused" in VSCode**: Make sure Delve is running first (step 1 of Option C). +- **Permission errors**: Ensure your kubeconfig has proper RBAC permissions. diff --git a/.claude/commands/setup-dev-env.md b/.claude/commands/setup-dev-env.md new file mode 100644 index 000000000..511621620 --- /dev/null +++ b/.claude/commands/setup-dev-env.md @@ -0,0 +1,103 @@ +# Setup NetObserv Development Environment + +This command sets up a complete development environment for NetObserv. + +**First, check if the user specified custom images:** +- Did the user provide a **USER** (quay.io username/repo)? +- Did the user provide a **VERSION** (image tag)? + +If the user specified custom images (e.g., "usando la imagen de mi repo, leandroberetta con el tag v1.2.3"), extract those values. Otherwise, use the defaults: `USER=netobserv` and `VERSION=main`. + +**Next, determine your platform:** +- Are you using **OpenShift** or **vanilla Kubernetes**? + +This will determine whether to run `make set-release-kind-downstream` in step 2. + +## Steps + +### 1. Deploy the operator to the cluster + +Deploy the operator with the specified or default images: + +**If custom USER and VERSION were provided:** +```bash +USER= VERSION= make deploy +``` + +**If using defaults (no custom images specified):** +```bash +USER=netobserv make deploy +``` + +**Note:** +- Using `USER=netobserv` (default) ensures the operator uses public images from `quay.io/netobserv` without authentication. +- Custom USER values like `USER=leandroberetta` will use images from `quay.io/leandroberetta/`. +- The VERSION parameter controls the image tag (e.g., `VERSION=v1.2.3` or `VERSION=main`). + +### 2. Configure for OpenShift (if applicable) + +**Only if you're using OpenShift**, run: + +```bash +make set-release-kind-downstream +``` + +**If you're using vanilla Kubernetes**, skip this step entirely. + +### 3. Deploy Loki + +```bash +make deploy-loki +``` + +This will deploy Loki and make it available at http://localhost:3100 + +### 4. Deploy sample FlowCollector CR + +```bash +make deploy-sample-cr +``` + +### 5. Verify deployment + +Check that all components are running: + +```bash +kubectl get pods -n netobserv +kubectl get flowcollector cluster -o yaml +``` + +## Cleanup + +To clean up the entire environment: + +```bash +make undeploy +``` + +## Building Custom Component Images (Optional) + +If you want to build custom images for the other NetObserv components (eBPF agent, flowlogs-pipeline, console plugin), you can do so before deploying: + +```bash +# Example: Build custom eBPF agent +cd ../netobserv-ebpf-agent +USER= VERSION= make images + +# Example: Build custom flowlogs-pipeline +cd ../flowlogs-pipeline +USER= VERSION= make images + +# Return to operator directory +cd ../network-observability-operator +``` + +Then, when deploying the operator in step 1, use the same USER and VERSION values so the operator uses your custom component images. + +**Note:** The operator deployment uses the USER and VERSION to determine which component images to reference in the FlowCollector CR it creates. + +## Troubleshooting + +- **Permission errors**: Ensure your kubeconfig has proper RBAC permissions. +- **Pod not starting**: Check logs with `kubectl logs -n netobserv `. +- **Image authentication issues**: Make sure you used `USER=netobserv` in step 1 to use public images. diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 000000000..1095b46be --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,16 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Connect to Delve (Operator Debug)", + "type": "go", + "request": "attach", + "mode": "remote", + "remotePath": "${workspaceFolder}", + "port": 2345, + "host": "localhost", + "showLog": true, + "trace": "verbose" + } + ] +} From 12d73159b367c9be7228b1bb990f988f2e3d4132 Mon Sep 17 00:00:00 2001 From: Leandro Beretta Date: Mon, 3 Nov 2025 14:24:41 -0300 Subject: [PATCH 2/4] fix --- .claude/commands/setup-dev-env.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/commands/setup-dev-env.md b/.claude/commands/setup-dev-env.md index 511621620..22e88913d 100644 --- a/.claude/commands/setup-dev-env.md +++ b/.claude/commands/setup-dev-env.md @@ -6,7 +6,7 @@ This command sets up a complete development environment for NetObserv. - Did the user provide a **USER** (quay.io username/repo)? - Did the user provide a **VERSION** (image tag)? -If the user specified custom images (e.g., "usando la imagen de mi repo, leandroberetta con el tag v1.2.3"), extract those values. Otherwise, use the defaults: `USER=netobserv` and `VERSION=main`. +If the user specified custom images (e.g., "using the image from my repo, leandroberetta with tag v1.2.3"), extract those values. Otherwise, use the defaults: `USER=netobserv` and `VERSION=main`. **Next, determine your platform:** - Are you using **OpenShift** or **vanilla Kubernetes**? From 5928a620aa5e256caeae0ebfc7b48649918439b3 Mon Sep 17 00:00:00 2001 From: Leandro Beretta Date: Mon, 3 Nov 2025 14:26:00 -0300 Subject: [PATCH 3/4] fix --- .claude/commands/setup-dev-env.md | 29 +---------------------------- 1 file changed, 1 insertion(+), 28 deletions(-) diff --git a/.claude/commands/setup-dev-env.md b/.claude/commands/setup-dev-env.md index 22e88913d..edef70deb 100644 --- a/.claude/commands/setup-dev-env.md +++ b/.claude/commands/setup-dev-env.md @@ -73,31 +73,4 @@ To clean up the entire environment: ```bash make undeploy -``` - -## Building Custom Component Images (Optional) - -If you want to build custom images for the other NetObserv components (eBPF agent, flowlogs-pipeline, console plugin), you can do so before deploying: - -```bash -# Example: Build custom eBPF agent -cd ../netobserv-ebpf-agent -USER= VERSION= make images - -# Example: Build custom flowlogs-pipeline -cd ../flowlogs-pipeline -USER= VERSION= make images - -# Return to operator directory -cd ../network-observability-operator -``` - -Then, when deploying the operator in step 1, use the same USER and VERSION values so the operator uses your custom component images. - -**Note:** The operator deployment uses the USER and VERSION to determine which component images to reference in the FlowCollector CR it creates. - -## Troubleshooting - -- **Permission errors**: Ensure your kubeconfig has proper RBAC permissions. -- **Pod not starting**: Check logs with `kubectl logs -n netobserv `. -- **Image authentication issues**: Make sure you used `USER=netobserv` in step 1 to use public images. +``` \ No newline at end of file From 9ef7e3159b14250c910e9fadceaff0255a32f338 Mon Sep 17 00:00:00 2001 From: Leandro Beretta Date: Mon, 3 Nov 2025 14:27:25 -0300 Subject: [PATCH 4/4] fix --- .claude/commands/debug-operator.md | 28 ---------------------------- 1 file changed, 28 deletions(-) diff --git a/.claude/commands/debug-operator.md b/.claude/commands/debug-operator.md index c079d890c..bfc00fe9d 100644 --- a/.claude/commands/debug-operator.md +++ b/.claude/commands/debug-operator.md @@ -101,28 +101,6 @@ This will trigger a reconciliation and the debugger will pause at your breakpoin - See how the operator processes changes - Debug any issues in the reconciliation loop -## Using Custom Images - -To debug with your own component builds: - -```bash -# Build and push your custom images first -cd ../netobserv-ebpf-agent -USER=myuser VERSION=dev make images - -cd ../flowlogs-pipeline -USER=myuser VERSION=dev make images - -# Then run the operator with your custom images -cd ../network-observability-operator - -dlv debug ./main.go --headless --listen=:2345 --api-version=2 --accept-multiclient -- \ - -ebpf-agent-image=quay.io/myuser/netobserv-ebpf-agent:dev \ - -flowlogs-pipeline-image=quay.io/myuser/flowlogs-pipeline:dev \ - -console-plugin-image=quay.io/netobserv/network-observability-console-plugin:main \ - -namespace=netobserv -``` - ## Cleanup When you're done debugging: @@ -135,9 +113,3 @@ kubectl scale deployment netobserv-controller-manager -n netobserv --replicas=1 ``` **Note:** The validating webhook will be automatically recreated by the operator when it starts back up, so you don't need to manually restore it. - -## Troubleshooting - -- **"Manager already exists" error**: The in-cluster operator is still running. Scale it to 0 replicas. -- **"Connection refused" in VSCode**: Make sure Delve is running first (step 1 of Option C). -- **Permission errors**: Ensure your kubeconfig has proper RBAC permissions.