Docs(contributor): Clarify and improve local development guide #1381
+62
−12
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The previous guide for setting up a local development environment was
confusing for new contributors. It resulted in an incomplete setup
that lacked the ServiceAccount and other resources, causing confusion.
This commit improves the guide in two ways:
1. A warning note is added to the "quick start" flow to clarify its
limitations and explain that it does not create a complete control plane.
2. The section on debugging with a remote environment is rewritten to
provide a full, step-by-step workflow, including the necessary
Helm command to install all required resources.
This provides a clearer and more accurate onboarding experience.
Signed-off-by: Ashvin Bambhaniya <[email protected]>
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
briankane
reviewed
Sep 26, 2025
|
|
||
| :::caution | ||
| Note you will not be able to test features relate with validating/mutating webhooks in this way. | ||
| By removing the webhooks, you will not be able to test features that rely on the admission controller (like some definition validation or pod injection features) in this mode. |
There was a problem hiding this comment.
Have we got documentation on how to webhook testing from the local machine? I was curious about it the other day
There was a problem hiding this comment.
That's a great point; we don't currently have a doc for local webhook testing, but it's a valuable suggestion for future documentation.
| ``` | ||
| This approach creates a complete and realistic development environment. It involves installing the full KubeVela control plane in your cluster via Helm, and then running the controller code locally to connect to it. | ||
|
|
||
| 1. **Install KubeVela using Helm** |
There was a problem hiding this comment.
I often use vela install to quickly setup with the latest code and then scale down
There was a problem hiding this comment.
address in commit b883364
|
|
||
| 3. **Run the Controller Locally** | ||
|
|
||
| Finally, you can use the `make core-run` command to run the controller from your local machine. It will connect to the cluster using your `kubeconfig` and take over from the scaled-down controller. |
There was a problem hiding this comment.
I think it'd be useful to briefly capture how to run it within your IDE with cmd/core/main.go
There was a problem hiding this comment.
add in commit b883364
Refines the code contribution guide to provide a clearer and more comprehensive developer experience for running KubeVela locally. This commit introduces several improvements: - Rewrites the 'Debugging Locally with Remote KubeVela Environment' section into a more detailed, step-by-step process. - Recommends using `vela install` and `vela uninstall` for a more consistent CLI experience. - Adds instructions for running and debugging the controller directly from an IDE. - Includes a caution block to clarify the limitations of the basic `make core-install` setup. Signed-off-by: Ashvin Bambhaniya <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This Pull Request addresses the confusion and incompleteness in the local development guide (
docs/contributor/code-contribute.md), which was causing a suboptimal onboarding experience for new contributors.Specifically, it resolves the issues where:
make core-runmethod led to an incomplete environment (missing ServiceAccount, RBAC) without proper explanation.Debugging Locally with Remote KubeVela Environment) lacked the crucialhelm installcommand.This PR implements the following changes:
:::cautionnote to the "Run Vela Core" section, explicitly warning that themake core-runquick-start method is incomplete and uses localkubeconfigcredentials, not a full in-cluster setup.Debugging Locally with Remote KubeVela Environmentsection into a comprehensive, step-by-step guide. This now includes the necessaryhelm installcommand, instructions for scaling down the in-cluster controller, and removing webhooks, providing a self-contained and realistic development workflow.I have:
sidebar.jsif adding a new page. (Not applicable, existing page modified)yarn startto ensure the changes has taken effect.Related Issue
Special notes for your reviewer
Please pay close attention to the following:
:::cautionnote in the "Run Vela Core" section.helm installcommand and the sequence of operations.kubectl delete ValidatingWebhookConfigurationandMutatingWebhookConfigurationcommands, where the-n vela-systemflag was removed as these are cluster-scoped resources.Summary by cubic
Clarifies the local development guide to prevent incomplete setups. Adds a realistic, step-by-step workflow for running vela-core locally against a Helm-installed cluster.