Automated debug environment #10054

sylvainsf · 2025-07-24T01:35:57Z

Description

This branch introduces a comprehensive local debugging environment for Radius, designed to streamline the development workflow by running core Go components as local OS processes. Instead of deploying services like UCP and the various resource providers into a Kubernetes cluster, the make debug-start command compiles them with debug symbols and runs them directly on your machine. This approach provides developers with the powerful ability to attach a debugger, such as Delve, to any running Radius component, enabling live code inspection, breakpoint debugging, and rapid iteration without the overhead of container builds and deployments. Additionally it has a fully-integrated VS Code debugging experience for Radius development. Just run make debug-start set your breakpoints, and attach the debugger to whichever component you're working on. The system still leverages a lightweight k3d cluster for Kubernetes-native dependencies, providing a hybrid environment that combines the fidelity of a real cluster with the convenience of local process debugging.

The debug environment is engineered to be fully automated and idempotent, ensuring a consistent and clean state with every run. The debug-start target handles all setup, from creating the k3d cluster and building binaries to starting processes and initializing the Radius environment. Furthermore it creates an alias drad to the debugger compiled CLI in order to not interfere with your installed rad CLI. To guarantee a pristine workspace, the make debug-stop command completely tears down all components, including the cluster and its associated data, preventing state-related bugs between debugging sessions. This repeatable and reliable workflow significantly enhances productivity by providing a fast and simple "inner loop" for development and testing. For detailed usage instructions see local debugging

Type of change

This pull request is a minor refactor, code cleanup, test improvement, or other maintenance task and doesn't change the functionality of Radius (issue link optional).

An overview of proposed schema changes is included in a linked GitHub issue.
- Yes
- Not applicable
A design document PR is created in the design-notes repository, if new APIs are being introduced.
- Yes
- Not applicable
The design document has been reviewed and approved by Radius maintainers/approvers.
- Yes
- Not applicable
A PR for the samples repository is created, if existing samples are affected by the changes in this PR.
- Yes
- Not applicable
A PR for the documentation repository is created, if the changes in this PR affect the documentation or any user facing updates are made.
- Yes
- Not applicable
A PR for the recipes repository is created, if existing recipes are affected by the changes in this PR.
- Yes
- Not applicable

radius-functional-tests · 2025-07-24T01:46:06Z

Radius functional test overview

🔍 Go to test action run

Name	Value
Repository	sylvainsf/radius
Commit ref	`62abb83`
Unique ID	func6a67d24bc6
Image tag	pr-func6a67d24bc6

Click here to see the list of tools in the current test run

gotestsum 1.12.0
KinD: v0.29.0
Dapr:
Azure KeyVault CSI driver: 1.4.2
Azure Workload identity webhook: 1.3.0
Bicep recipe location ghcr.io/radius-project/dev/test/testrecipes/test-bicep-recipes/<name>:pr-func6a67d24bc6
Terraform recipe location http://tf-module-server.radius-test-tf-module-server.svc.cluster.local/<name>.zip (in cluster)
applications-rp test image location: ghcr.io/radius-project/dev/applications-rp:pr-func6a67d24bc6
dynamic-rp test image location: ghcr.io/radius-project/dev/dynamic-rp:pr-func6a67d24bc6
controller test image location: ghcr.io/radius-project/dev/controller:pr-func6a67d24bc6
ucp test image location: ghcr.io/radius-project/dev/ucpd:pr-func6a67d24bc6
deployment-engine test image location: ghcr.io/radius-project/deployment-engine:latest

Test Status

⌛ Building Radius and pushing container images for functional tests...
✅ Container images build succeeded
⌛ Publishing Bicep Recipes for functional tests...
✅ Recipe publishing succeeded
⌛ Starting corerp-cloud functional tests...
⌛ Starting ucp-cloud functional tests...
✅ ucp-cloud functional tests succeeded
✅ corerp-cloud functional tests succeeded

codecov · 2025-07-24T15:09:23Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 50.44%. Comparing base (a45fc2f) to head (47f9824).

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #10054   +/-   ##
=======================================
  Coverage   50.43%   50.44%           
=======================================
  Files         672      672           
  Lines       42057    42057           
=======================================
+ Hits        21213    21217    +4     
+ Misses      18788    18786    -2     
+ Partials     2056     2054    -2

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

brooke-hamilton

This PR creates a /build/scripts folder for scripts used by the Make commands. Let's move all the scripts to that folder as part of this PR so that the pattern is consistently implemented.

Running make debug-start resulted in an error. The end of the console output is below. Is this a side-effect of me not having Postgres set up as a local service? Should we run Postgres in the cluster, or is there an advantage to having it running as a local service?

Starting Radius components as OS processes...
🚀 Starting Radius components...
Checking for existing components and stopping them...
✅ Cleanup complete
🗄️  Initializing PostgreSQL database...
⚠️  psql not available - database may not be properly initialized
Starting UCP with dlv on port 40001...
build/scripts/start-radius.sh: line 108: /workspace/radius-project/pr-10054/debug_files/logs/ucp.pid: No such file or directory
make: *** [build/debug.mk:141: debug-start] Error 1

I added some comments to the files. I will finish reviewing it when I get the debugging process to work.

build/debug.mk

build/configs/rad-debug-config.yaml.lock

.../contributing/contributing-code/contributing-code-debugging/radius-os-processes-debugging.md

build/debug.mk

.vscode/launch.json

sylvainsf · 2025-07-29T09:21:59Z

@brooke-hamilton did a major doc overhaul, cleaned up make targets, answered some questions, I think the doc overhaul answers a lot too as I ended up cutting half of it because I automated away most of the steps I had documented early on.

radius-functional-tests · 2025-07-29T09:23:07Z

Radius functional test overview

🔍 Go to test action run

Name	Value
Repository	sylvainsf/radius
Commit ref	`4d6feb9`
Unique ID	func9f3cf58902
Image tag	pr-func9f3cf58902

Click here to see the list of tools in the current test run

gotestsum 1.12.0
KinD: v0.29.0
Dapr:
Azure KeyVault CSI driver: 1.4.2
Azure Workload identity webhook: 1.3.0
Bicep recipe location ghcr.io/radius-project/dev/test/testrecipes/test-bicep-recipes/<name>:pr-func9f3cf58902
Terraform recipe location http://tf-module-server.radius-test-tf-module-server.svc.cluster.local/<name>.zip (in cluster)
applications-rp test image location: ghcr.io/radius-project/dev/applications-rp:pr-func9f3cf58902
dynamic-rp test image location: ghcr.io/radius-project/dev/dynamic-rp:pr-func9f3cf58902
controller test image location: ghcr.io/radius-project/dev/controller:pr-func9f3cf58902
ucp test image location: ghcr.io/radius-project/dev/ucpd:pr-func9f3cf58902
deployment-engine test image location: ghcr.io/radius-project/deployment-engine:latest

Test Status

⌛ Building Radius and pushing container images for functional tests...
✅ Container images build succeeded
⌛ Publishing Bicep Recipes for functional tests...
✅ Recipe publishing succeeded
⌛ Starting corerp-cloud functional tests...
⌛ Starting ucp-cloud functional tests...
✅ ucp-cloud functional tests succeeded
✅ corerp-cloud functional tests succeeded

brooke-hamilton

🥇 I was able to reliably run make debug-start, make debug-status, and make debug-stop. The drad command works very well. Just a few very minor comments below.

brooke-hamilton · 2025-09-20T18:04:49Z

.../contributing/contributing-code/contributing-code-debugging/radius-os-processes-debugging.md

+
+3. **Code Changes**: 
+   - Make your code changes
+   - Use rebuild/restart tasks: Ctrl+Shift+P → "Tasks: Run Task" → "Rebuild and Restart [Component]"


I don't see a task named "Rebuild and Restart [Component]"

.vscode/launch.json

brooke-hamilton · 2025-09-20T18:38:47Z

.vscode/launch.json

I was able to attach a debugger to the CLI using the configurations in this file, but I was not able to effectively debug any CLI command that has interactive input, like rad init. This may be an issue with the CLI framework we use rather than this particular configuration. (This is just a comment, not a request for a fix.)

brooke-hamilton · 2025-09-20T18:43:17Z

.../contributing/contributing-code/contributing-code-debugging/radius-os-processes-debugging.md

+
+**CLI Debugging Options:**
+- **Use `./drad` for convenience**: When you only need to test CLI commands against the debug environment without debugging the CLI code itself
+- **Use "Debug drad CLI (debug environment)" in VS Code**: When you need to debug CLI code with breakpoints, variable inspection, and step-through debugging


What are the debug configurations "Debug rad CLI" and "Debug rad CLI (prompt for args)" used for?

Those are the legacy launch config I have no idea why there's a non prompt version.

suggestion: If we have something legacy that probably nobody using, lets remove it from the codebase.

brooke-hamilton · 2025-09-20T18:47:36Z

.../contributing/contributing-code/contributing-code-debugging/radius-os-processes-debugging.md

+
+   **Method A: VS Code Process Picker**
+   - Open Debug panel and select "Attach to [Component]"
+   - Press F5 - VS Code will show a process picker


A process picker does not open for me, but VS code appears to be running with the debugger attached.

That's the "Attach to..." with dlv port options, maybe the process picker is a confusing term?

brooke-hamilton · 2025-09-20T19:03:25Z

build/debug.mk

Nit: when running make debug-start there are a few console messages like this:

make[3]: Leaving directory '/mnt/wsl/workspace/radius-project/radius' make[3]: Entering directory '/mnt/wsl/workspace/radius-project/radius'

Adding this to the top of debug.mk would suppress them:

MAKEFLAGS += --no-print-directory

lakshmimsft · 2025-09-22T07:02:53Z

Tested existing debug method: UCP service is started up successfully but the remaining Applications RP, Controller and Dynamic RP all fail at startup with error messages (clipped):
Error: open /Users/lakshmi/repos/radius-mainfork/cmd/controller/controller.yaml: no such file or directory
Error: open /Users/lakshmi/repos/radius-mainfork/cmd/applications-rp/applications-rp.yaml: no such file or directory
Error: failed to read config file /Users/lakshmi/repos/radius-mainfork/cmd/dynamic-rp/dynamic-rp.yaml: open /Users/lakshmi/repos/radius-mainfork/cmd/dynamic-rp/dynamic-rp.yaml: no such file or directory

Co-authored-by: Brooke Hamilton <[email protected]> Signed-off-by: Sylvain Niles <[email protected]>

…o automated-debug-environment

DariuszPorowski

A few comments in the code, and I was unsuccessful to attach/debug :( I tried basic CLI drad version and set the breakpoint the main.go (for rad cmd).

DariuszPorowski · 2025-11-07T19:00:04Z

.vscode/launch.json

nitpick(style): lint/format of this file will cause better readability, now big one-liners are hard to read

DariuszPorowski · 2025-11-07T20:04:55Z

.vscode/tasks.json

praise: Love it!

DariuszPorowski · 2025-11-07T23:25:42Z

.../contributing/contributing-code/contributing-code-debugging/radius-os-processes-debugging.md

+### Setup Commands
+```bash
+# Start all components as OS processes with debugging (Checks prereqs and creates necessary folders)
+make debug-start


question: Have you considered (or maybe even tried?) to skip this manual step? and have "F5" experience only?

I don't want to require contributors to use VS Code.

I do have F5 tasks for stop and start though.

DariuszPorowski · 2025-11-07T23:45:45Z

build/debug.mk

+		echo "   Please ensure:"; \
+		echo "   1. PostgreSQL is running on localhost:5432"; \
+		echo "   2. Either Docker PostgreSQL (postgres/radius_pass) or local user access"; \
+		echo "   3. Quick start: docker run --name radius-postgres -e POSTGRES_PASSWORD=radius_pass -p 5432:5432 -d postgres:15"; \


suggestion: postgres 15 is quite old... (5 years or more?), the current one is 18 - maybe you can consider the latest one if it is compatible with radius. postgres:15, postgres:14 and even postgres:latest exist in a few places in the codebase.

DariuszPorowski · 2025-11-11T02:36:49Z

.../contributing/contributing-code/contributing-code-debugging/radius-os-processes-debugging.md

+
+**CLI Debugging Options:**
+- **Use `./drad` for convenience**: When you only need to test CLI commands against the debug environment without debugging the CLI code itself
+- **Use "Debug drad CLI (debug environment)" in VS Code**: When you need to debug CLI code with breakpoints, variable inspection, and step-through debugging


suggestion: If we have something legacy that probably nobody using, lets remove it from the codebase.

.../contributing/contributing-code/contributing-code-debugging/radius-os-processes-debugging.md

…ironment

Signed-off-by: Sylvain Niles <[email protected]>

…g/radius-os-processes-debugging.md Co-authored-by: Dariusz Porowski <[email protected]> Signed-off-by: Sylvain Niles <[email protected]>

Signed-off-by: Sylvain Niles <[email protected]>

…o automated-debug-environment

Signed-off-by: Sylvain Niles <[email protected]>

radius-functional-tests · 2025-12-10T01:10:53Z

Radius functional test overview

🔍 Go to test action run

Click here to see the test run details

Name	Value
Repository	sylvainsf/radius
Commit ref	`47f9824`
Unique ID	func34b9207bec
Image tag	pr-func34b9207bec

gotestsum 1.13.0
KinD: v0.29.0
Dapr: 1.14.4
Azure KeyVault CSI driver: 1.4.2
Azure Workload identity webhook: 1.3.0
Bicep recipe location ghcr.io/radius-project/dev/test/testrecipes/test-bicep-recipes/<name>:pr-func34b9207bec
Terraform recipe location http://tf-module-server.radius-test-tf-module-server.svc.cluster.local/<name>.zip (in cluster)
applications-rp test image location: ghcr.io/radius-project/dev/applications-rp:pr-func34b9207bec
dynamic-rp test image location: ghcr.io/radius-project/dev/dynamic-rp:pr-func34b9207bec
controller test image location: ghcr.io/radius-project/dev/controller:pr-func34b9207bec
ucp test image location: ghcr.io/radius-project/dev/ucpd:pr-func34b9207bec
deployment-engine test image location: ghcr.io/radius-project/deployment-engine:latest

Test Status

⌛ Building Radius and pushing container images for functional tests...
✅ Container images build succeeded
⌛ Publishing Bicep Recipes for functional tests...
✅ Recipe publishing succeeded
⌛ Starting corerp-cloud functional tests...
⌛ Starting ucp-cloud functional tests...
✅ ucp-cloud functional tests succeeded
✅ corerp-cloud functional tests succeeded
✅ corerp-cloud functional tests succeeded

sylvainsf requested review from a team as code owners July 24, 2025 01:35

sylvainsf force-pushed the automated-debug-environment branch from 63884e3 to 75be672 Compare July 24, 2025 01:43

sylvainsf temporarily deployed to publish-bicep July 24, 2025 01:44 — with GitHub Actions Inactive

sylvainsf temporarily deployed to functional-tests July 24, 2025 01:44 — with GitHub Actions Inactive

sylvainsf had a problem deploying to functional-tests July 24, 2025 01:52 — with GitHub Actions Failure

sylvainsf temporarily deployed to publish-bicep July 24, 2025 01:53 — with GitHub Actions Inactive

sylvainsf force-pushed the automated-debug-environment branch from f30f6b8 to 94e224e Compare July 24, 2025 01:57

sylvainsf requested a review from a team as a code owner July 24, 2025 01:57

sylvainsf force-pushed the automated-debug-environment branch from 94e224e to 3acaa26 Compare July 24, 2025 14:56

sylvainsf had a problem deploying to functional-tests July 24, 2025 14:56 — with GitHub Actions Failure

sylvainsf temporarily deployed to publish-bicep July 24, 2025 14:56 — with GitHub Actions Inactive

brooke-hamilton requested changes Jul 25, 2025

View reviewed changes

sylvainsf had a problem deploying to functional-tests July 29, 2025 08:57 — with GitHub Actions Failure

sylvainsf temporarily deployed to publish-bicep July 29, 2025 08:57 — with GitHub Actions Inactive

sylvainsf force-pushed the automated-debug-environment branch 2 times, most recently from 40cbe4a to f88b8d2 Compare July 29, 2025 09:12

sylvainsf had a problem deploying to functional-tests July 29, 2025 09:12 — with GitHub Actions Failure

sylvainsf temporarily deployed to publish-bicep July 29, 2025 09:12 — with GitHub Actions Inactive

sylvainsf force-pushed the automated-debug-environment branch from f88b8d2 to ac8ad38 Compare July 29, 2025 09:15

sylvainsf had a problem deploying to functional-tests July 29, 2025 09:15 — with GitHub Actions Failure

sylvainsf temporarily deployed to publish-bicep July 29, 2025 09:15 — with GitHub Actions Inactive

sylvainsf force-pushed the automated-debug-environment branch from ac8ad38 to 4d6feb9 Compare July 29, 2025 09:20

sylvainsf temporarily deployed to functional-tests July 29, 2025 09:20 — with GitHub Actions Inactive

sylvainsf temporarily deployed to publish-bicep July 29, 2025 09:21 — with GitHub Actions Inactive

sylvainsf requested a review from brooke-hamilton July 29, 2025 09:22

brooke-hamilton reviewed Sep 20, 2025

View reviewed changes

sylvainsf and others added 3 commits September 22, 2025 10:51

Update .vscode/launch.json for multiple args on cli

03bf912

Co-authored-by: Brooke Hamilton <[email protected]> Signed-off-by: Sylvain Niles <[email protected]>

merge resolution

6415aa2

Merge remote-tracking branch 'origin/automated-debug-environment' int…

47f1b81

…o automated-debug-environment

sylvainsf temporarily deployed to functional-tests October 10, 2025 18:04 — with GitHub Actions Inactive

sylvainsf temporarily deployed to publish-bicep October 10, 2025 18:04 — with GitHub Actions Inactive

DariuszPorowski suggested changes Nov 11, 2025

View reviewed changes

Merge remote-tracking branch 'upstream/main' into automated-debug-env…

57b8b59

…ironment

sylvainsf requested a deployment to functional-tests December 1, 2025 21:38 — with GitHub Actions Waiting

sylvainsf had a problem deploying to publish-bicep December 1, 2025 21:38 — with GitHub Actions Error

fixes port issue for k3d

d5d3818

Signed-off-by: Sylvain Niles <[email protected]>

sylvainsf requested a deployment to functional-tests December 1, 2025 21:39 — with GitHub Actions Waiting

sylvainsf temporarily deployed to publish-bicep December 1, 2025 21:39 — with GitHub Actions Inactive

Update docs/contributing/contributing-code/contributing-code-debuggin…

6a9a2fb

…g/radius-os-processes-debugging.md Co-authored-by: Dariusz Porowski <[email protected]> Signed-off-by: Sylvain Niles <[email protected]>

sylvainsf requested a deployment to functional-tests December 9, 2025 22:40 — with GitHub Actions Waiting

sylvainsf temporarily deployed to publish-bicep December 9, 2025 22:41 — with GitHub Actions Inactive

sylvainsf added 2 commits December 9, 2025 16:46

Cleaned up and fixed all vscode tasks and launch configs

cf5013b

Signed-off-by: Sylvain Niles <[email protected]>

Merge remote-tracking branch 'origin/automated-debug-environment' int…

86a1dc9

…o automated-debug-environment

sylvainsf requested a deployment to functional-tests December 10, 2025 00:47 — with GitHub Actions Waiting

sylvainsf temporarily deployed to publish-bicep December 10, 2025 00:48 — with GitHub Actions Inactive

fixed debian install for correct version

5c98d1c

Signed-off-by: Sylvain Niles <[email protected]>

sylvainsf temporarily deployed to functional-tests December 10, 2025 00:50 — with GitHub Actions Inactive

sylvainsf temporarily deployed to publish-bicep December 10, 2025 00:50 — with GitHub Actions Inactive

sylvainsf requested review from DariuszPorowski and brooke-hamilton December 10, 2025 01:02

Merge branch 'main' into automated-debug-environment

47f9824

sylvainsf temporarily deployed to functional-tests December 10, 2025 01:09 — with GitHub Actions Inactive

sylvainsf temporarily deployed to publish-bicep December 10, 2025 01:09 — with GitHub Actions Inactive

Automated debug environment #10054

Are you sure you want to change the base?

Automated debug environment #10054

Uh oh!

Conversation

sylvainsf commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Uh oh!

radius-functional-tests bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Radius functional test overview

Test Status

Uh oh!

codecov bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

brooke-hamilton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sylvainsf commented Jul 29, 2025

Uh oh!

radius-functional-tests bot commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Radius functional test overview

Test Status

Uh oh!

brooke-hamilton left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lakshmimsft commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DariuszPorowski left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sylvainsf commented Jul 24, 2025 •

edited

Loading

radius-functional-tests bot commented Jul 24, 2025 •

edited

Loading

codecov bot commented Jul 24, 2025 •

edited

Loading

radius-functional-tests bot commented Jul 29, 2025 •

edited

Loading

lakshmimsft commented Sep 22, 2025 •

edited

Loading

radius-functional-tests bot commented Dec 10, 2025 •

edited

Loading