Design note: refresh the rad init experience - #12684
Conversation
Signed-off-by: Zach Casper <zachcasper@microsoft.com>
Radius functional test overviewClick here to see the test run details
Test Status⌛ Building Radius and pushing container images for functional tests... |
Functional Tests - corerp-cloud30 tests ±0 27 ✅ - 2 20m 25s ⏱️ - 3m 40s For more details on these failures, see this check. Results for commit cbedb22. ± Comparison against base commit aeb5292. |
Signed-off-by: Zach Casper <zachcasper@microsoft.com>
zachcasper
changed the title
There was a problem hiding this comment.
Pull request overview
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Adds a design note describing a proposed refresh of the preview rad init --preview experience, focusing on making the default flow zero-question and improving the --full interactive flow.
Changes:
- Introduces goals/scope and an as-is vs to-be UX walkthrough for
rad init --previewand--full - Specifies six detailed design changes (bicepconfig behavior, extensions, prompt removal/reorder, recipe pack selection, improved error rendering)
- Adds a test plan and CI impact analysis for the proposed changes
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…nd error-message wording Signed-off-by: Zach Casper <zachcasper@microsoft.com>
| - Kubernetes namespace: prod | ||
| - Recipe pack: azure-aks | ||
| ✅ Update local configuration | ||
| - /home/user/my-project/bicepconfig.json |
There was a problem hiding this comment.
I wonder if we could remove the dependency for bicepconfig.json on the filesystem. what if we could point to it like github.com/radius-project/radius/bicepconfig.json@main
| ```json | ||
| { | ||
| "extensions": { | ||
| "radius": "br:biceptypes.azurecr.io/radius:latest" |
There was a problem hiding this comment.
will soon be something like
br:ghcr.io/radius-project/radius/types:latest
There was a problem hiding this comment.
Something to consider when making that change: https://github.com/zachcasper/radius/blob/bicep-extension-refactor/eng/design-notes/bicep/2026-05-dynamic-bicep-extensions.md
| **Sample Input:** | ||
|
|
||
| ```bash | ||
| rad init --preview |
There was a problem hiding this comment.
Should this be rad init --full?
There was a problem hiding this comment.
No, this is the default path with no --full. The --full output is the next section.
|
|
||
| ### Goals | ||
|
|
||
| - Make the default `rad init` a zero-question command that always produces a working Radius installation and a valid `bicepconfig.json`. |
There was a problem hiding this comment.
This is really great because we currently cannot use rad init in a script because it has interactive questions.
| - Stop producing artifacts the getting-started flow no longer needs: the sample `app.bicep` file and the stub application resource. | ||
| - Only register the `radius` Bicep extension in the generated `bicepconfig.json`, dropping the `aws` extension. | ||
| - Render initialization errors (especially the missing-namespace error) as concise, human-readable messages that do not corrupt the terminal. | ||
| - Keep `rad init --full` as the interactive path for platform engineers, and add a recipe-pack selection step sourced from `defaults.yaml` / `resource-types-contrib`. |
There was a problem hiding this comment.
In addition to the --full option, which is purely interactive, could we add arguments for each option asked by the --full workflow so that we could use rad init in a script and specify all available options exposed by rad init --full?
There was a problem hiding this comment.
That could get very long. We may consider a values file instead. rad init -f my-values.yaml.
| - [#12587: Confusing user prompt on `rad init`](https://github.com/radius-project/radius/issues/12587) | ||
| - [#12418: Sample `app.bicep` should define an application resource rather than an `application` parameter](https://github.com/radius-project/radius/issues/12418) | ||
| - [#12568: Malformed error message when Kubernetes namespace does not exist during `rad init`](https://github.com/radius-project/radius/issues/12568) | ||
| - [#12414: Remove AWS Bicep extension from `bicepconfig.json` scaffolded by `rad init`](https://github.com/radius-project/radius/issues/12414) |
There was a problem hiding this comment.
This links to an unrelated issue - can you share the correct link?
There was a problem hiding this comment.
This is the underlying issue for Change 6: Human-readable initialization errors (fix #12568).
|
|
||
| This change closes a usability gap in `--full`: there is no way to choose a recipe pack, so every environment is created with the hardcoded default pack. | ||
|
|
||
| In default mode the environment is created with the `kubernetes` pack (unchanged behavior); it is the default pack, and its `recipePacks` resource is named `default` in the contrib file (hence the `Recipe pack: default` line in the output). In `--full` mode, present a list built from the `recipePacks` entries in [`defaults.yaml`](../../../deploy/manifest/defaults.yaml) (today: `azure`, `kubernetes`, after [PR #12662](https://github.com/radius-project/radius/pull/12662): `azure-aci`, `azure-aks`, `kubernetes`). |
There was a problem hiding this comment.
If someone picks azure-aks but answered "no" to the cloud provider prompt, what happens? Now that cloud provider setup comes first, we could filter the pack list or warn. Can we say what the intended behavior is?
| ```text | ||
| cluster (kube context) | ||
| → cloud providers (moved earlier) | ||
| → environment name |
There was a problem hiding this comment.
the provider would be updated in an environment, so wouldnt the earlier ordering make sense?
Summary
Adds a design note proposing a refresh of the preview
rad init --previewexperience: make the default command zero-question and always produce a working setup, and extend the interactive--fullflow. Docs-only; no code changes.The note specifies six changes, scoped to the preview (
Radius.*) init path only (the stableApplications.*path is unchanged):bicepconfig.json; never writeapp.bicep(No bicepconfig.json created after rad init #12588, rad init creates an unnecessary stub application resource #12649, Sampleapp.bicepscaffolded byrad initshould define an application resource rather than anapplicationparameter #12418)radiusBicep extension (Malformed error message when Kubernetes namespace does not exist duringrad init#12414)--fullso cloud-provider setup precedes the environment promptsdefaults.yaml(depends on resource-types-contrib#296)rad init#12568)It also records the CI-impact analysis (existing CI provisions Radius with
rad install kubernetes, notrad init, so it is unaffected) and a getting-started tutorial smoke-test plan to guard the on-ramp now that the localapp.bicepscaffold is removed.Reason for change
rad initis the product's on-ramp, and small regressions have compounded into a rough first run: a vague scaffold prompt, a missingbicepconfig.jsonwhen declined, an unnecessary stub application resource, an unwantedawsBicep extension, and initialization errors that corrupt the terminal. This note captures the design before implementation.Design proposal for #12588, #12649, #12587, #12418, #12414, and #12568. Implementation PRs will close these; this design note does not.
How to test
Docs-only. Review
eng/design-notes/cli/2026-08-rad-init-refresh.mdand run the Markdown linters: