From de05fad81a54dc379df190e0b90e5d0708a45348 Mon Sep 17 00:00:00 2001 From: Parthvi Vala Date: Thu, 21 Aug 2025 15:07:00 +0530 Subject: [PATCH] Enhance debugging development doc Signed-off-by: Parthvi Vala --- docs/book/src/04_developer/01_development.md | 51 +++++++++++++++++--- 1 file changed, 44 insertions(+), 7 deletions(-) diff --git a/docs/book/src/04_developer/01_development.md b/docs/book/src/04_developer/01_development.md index 14d1207..dceca6c 100644 --- a/docs/book/src/04_developer/01_development.md +++ b/docs/book/src/04_developer/01_development.md @@ -64,8 +64,9 @@ The following instructions are for development purposes. ```bash kind create cluster --config kind-cluster-with-extramounts.yaml ``` - -10. Now start tilt by running the following command in the directory where you cloned Cluster API repo in step 1: + > NOTE: You can also use your existing kind cluster by using the environment variable `CAPI_KIND_CLUSTER_NAME`. +10. Export `CLUSTER_TOPOLOGY=true` to enable support for managed topologies and ClusterClass. +11. Now start tilt by running the following command in the directory where you cloned Cluster API repo in step 1: ```bash tilt up @@ -79,8 +80,11 @@ This section explains how to attach debugger to the CAPRKE2 process running in a connecting a debugger to this process, you would be able to step through the code through your IDE. This guide covers two popular IDEs - IntelliJ GoLand and VS Code. -On the Tilt web UI and confirm the port on which `caprke2_controller` is exposed. By default, it should be -localhost:30001. +On the Tilt web UI and confirm the port on which `caprke2_controller` is exposed. By default, it should be localhost:30002. + +If you want to debug CAPRKE2 bootstrap controller, find where `capbpr_controller` is exposed. By default, it should be localhost:30001. + +To learn about debugging Core CAPI Controller, refer to [the official doc](https://cluster-api.sigs.k8s.io/developer/core/tilt). ### GoLand @@ -89,6 +93,10 @@ localhost:30001. Remote'. 3. Enter the 'Host' and 'Port' values based on where `caprke2_controller` is exposed. +You can setup a similar debugger for the Bootstrap controller. + +To debug Bootstrap and Control Plane simultaneously, you can add a new configuration as before but select 'Compound' and then select the Go Remote setups for both controllers. + ### VS Code 1. If you don't already have a `launch.json` setup, go to 'Run and Debug' in the Activity Bar and click on 'create a @@ -111,11 +119,11 @@ localhost:30001. ] } ``` - +--- Insert a breakpoint, e.g., in the [`updateStatus`](https://github.com/rancher/cluster-api-provider-rke2/blob/5163e6233301262c5bcfebab58189aa278b1f51e/controlplane/internal/controllers/rke2controlplane_controller.go#L298) method which responsible for updating the status of the `RKE2ControlPlane` resource and run the configuration. To check if you can step into the code, create a workload cluster by using the example provided in the [documentation](../03_examples/03_docker.md). If things were configured correctly, code -execution would halt at the breakpoint and you should be able to step through it. +execution would halt at the breakpoint, and you should be able to step through it. ## Troubleshooting @@ -125,4 +133,33 @@ run `tilt logs` in a separate terminal without stopping the `tilt up` command th ### Common Issues 1. Make sure you run the `kind` and `tilt` commands mentioned above from correct directory. -2. A `go mod vendor` might be required in your clone of CAPI repo. `tilt logs` should make this obvious. \ No newline at end of file +2. A `go mod vendor` might be required in your clone of CAPI repo. `tilt logs` should make this obvious. + +# Unit Testing +Unit tests use envtest, and to ensure you can run them locally, you need to install the envtest binary. + +```shell +go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest +KUBEBUILDER_ASSETS=$(setup-envtest use -p path ) +``` + +Set the envvar `KUBEBUILDER_ASSETS` and its value in your code editor's test configuration. + +# E2E Testing +To run or debug a test from your code editor, you would need to setup the configuration with some environment variables and arguments. +To run an e2e test, we use `make e2e-test` in the CI, we will replicate the same settings in our code editor configuration. + +## Goland +Create a Run/Debug configuration with the following settings: +Environment variables: +1. LOCAL_IMAGES=/path/to/cluster-api-provider-rke2/out/images +2. CAPI_KUSTOMIZE_PATH=/path/to/cluster-api-provider-rke2/hack/tools/bin/kustomize-v5.5.0 + +Go tool arguments: +1. `--tags=e2e` + +Program arguments: +1. `-e2e.artifacts-folder="/path/to/cluster-api-provider-rke2/_artifacts"` +2. `-e2e.config="/path/to/cluster-api-provider-rke2/test/e2e/config/e2e_conf.yaml"` +3. `-e2e.use-existing-cluster=false` +4. `-e2e.skip-resource-cleanup=false` \ No newline at end of file