From 9df6865caec97c1ec233b7987bb66f54c4f871a0 Mon Sep 17 00:00:00 2001 From: Aiden Date: Thu, 10 Jul 2025 14:49:58 +0800 Subject: [PATCH 1/2] docs(module-controller): enhance local development debugging instructions Added detailed steps for remote debugging with minikube, including building a debug image, applying deployments, and configuring IDE for remote debugging. Improved clarity and structure of the documentation for better user guidance. --- .../contribution/local-dev-test.md | 66 ++++++++++++++++++- .../contribution/local-dev-test.md | 64 +++++++++++++++++- 2 files changed, 125 insertions(+), 5 deletions(-) diff --git a/content/en/docs/contribution-guidelines/contribution/local-dev-test.md b/content/en/docs/contribution-guidelines/contribution/local-dev-test.md index d1e3fe68..7944f86c 100644 --- a/content/en/docs/contribution-guidelines/contribution/local-dev-test.md +++ b/content/en/docs/contribution-guidelines/contribution/local-dev-test.md @@ -6,25 +6,85 @@ weight: 100 --- ## SOFAArk and Arklet + SOFAArk is a regular Java SDK project that uses Maven as its dependency management and build tool. You only need to install Maven 3.6 or higher locally to develop code and run unit tests normally, without any other environment preparation.
For details on code submission, please refer to: [Completing the First PR Submission](/docs/contribution-guidelines/contribution/first-pr/). ## ModuleController + ModuleController is a standard K8S Golang Operator component, which includes ModuleDeployment Operator, ModuleReplicaSet Operator, and Module Operator. You can use minikube for local development testing. For details, please refer to [Local Quick Start](/docs/quick-start/module_ops/).
To compile and build, execute the following command in the module-controller directory: + ```bash go mod download # if compile module-controller first time -go build -a -o manager cmd/main.go +go build -a -o manager cmd/main.go ``` + To run unit tests, execute the following command in the module-controller directory: + ```bash make test ``` + You can also use an IDE for compiling, building, debugging, and running unit tests.
-The development approach for module-controller is exactly the same as the standard K8S Operator development approach. You can refer to the [official K8S Operator development documentation](https://kubernetes.io/zh-cn/docs/concepts/extend-kubernetes/operator/)。 +The development approach for module-controller is exactly the same as the standard K8S Operator development approach. You can refer to the [official K8S Operator development documentation](https://kubernetes.io/zh-cn/docs/concepts/extend-kubernetes/operator/). + +If you want to deploy ModuleController via minikube for remote debugging of the Pod code, you can follow these steps: + +1. Build a minikube Debug image in the module-controller project. + +```bash +minikube image build -f debug.Dockerfile -t serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/module-controller-v2:latest . +``` + +2. Apply the Debug deployment. + +```bash +kubectl apply -f example/quick-start/module-controller-test.yaml +``` + +3. Expose the module-controller remote debugging port. + +```bash +kubectl port-forward deployments/module-controller 2345:2345 +``` + +4. Enable remote debugging in your local IDE. Here's a reference for VSCode debug configuration: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Connect to module-controller Pod", + "type": "go", + "request": "attach", + "mode": "remote", + "port": 2345, + "host": "127.0.0.1", + "substitutePath": [ + { + "from": "${cwd}", + "to": "/workspace/module-controller" + } + ], + "showLog": true, + "logOutput": "dap" + } + ] +} +``` + +5. Set breakpoints in your IDE and run the debugger to check if the program successfully pauses at the breakpoints. + +You can use the following command to quickly complete steps 1 and 2 above: + +``` +make minikube-debug +``` ## Arkctl + Arkctl is a regular Golang project, which is a command-line toolset that includes common tools for users to develop and maintain modules locally. [You can refer here](/docs/tutorials/build_and_deploy) -
diff --git a/content/zh-cn/docs/contribution-guidelines/contribution/local-dev-test.md b/content/zh-cn/docs/contribution-guidelines/contribution/local-dev-test.md index f6b2c452..929578aa 100644 --- a/content/zh-cn/docs/contribution-guidelines/contribution/local-dev-test.md +++ b/content/zh-cn/docs/contribution-guidelines/contribution/local-dev-test.md @@ -6,25 +6,85 @@ weight: 100 --- ## SOFAArk 和 Arklet + SOFAArk 是一个普通 Java SDK 项目，使用 Maven 作为依赖管理和构建工具，只需要本地安装 Maven 3.6 及以上版本即可正常开发代码和单元测试，无需其它的环境准备工作。
关于代码提交细节请参考：[完成第一次 PR 提交](/docs/contribution-guidelines/contribution/first-pr)。 ## ModuleController + ModuleController 是一个标准的 K8S Golang Operator 组件，里面包含了 ModuleDeployment Operator、ModuleReplicaSet Operator、Module Operator，在本地可以使用 minikube 做开发测试，具体请参考[本地快速开始](/docs/quick-start/module_ops)。
编译构建请在 module-controller 项目里执行： + ```bash go mod download # if compile module-controller first time -go build -a -o manager cmd/main.go +go build -a -o manager cmd/main.go ``` + 单元测试执行请在 module-controller 项目里执行： + ```bash make test ``` + 您也可以使用 IDE 进行编译构建、开发调试和单元测试执行。
module-controller 开发方式和标准 K8S Operator 开发方式完全一样，您可以参考 K8S Operator 开发[官方文档](https://kubernetes.io/zh-cn/docs/concepts/extend-kubernetes/operator/)。 +如果想要通过 minikube 部署 ModuleController 来对 Pod 远程调试代码，可以参考以下步骤。 + +1. 在 modue-controller 项目里构建 minikube Debug 镜像。 + +```bash +minikube image build -f debug.Dockerfile -t serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/module-controller-v2:latest . +``` + +2. 应用 Debug deployment。 + +```bash +kubectl apply -f example/quick-start/module-controller-test.yaml +``` + +3. 暴露 module-controller 远程调试端口。 + +```bash +kubectl port-forward deployments/module-controller 2345:2345 +``` + +4. 在本地 IDE 上开启远程调试。参考 vscode 调试设置。 + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Connect to module-controller Pod", + "type": "go", + "request": "attach", + "mode": "remote", + "port": 2345, + "host": "127.0.0.1", + "substitutePath": [ + { + "from": "${cwd}", + "to": "/workspace/module-controller" + } + ], + "showLog": true, + "logOutput": "dap" + } + ] +} +``` + +5. 在 ide 打断点后运行调试，看看程序是否成功在断点处暂停。 + +上面的第一步和第二步可以使用下面的命令来快速构建调试。 + +``` +make minikube-debug +``` + ## Arkctl + Arkctl 是一个普通 Golang 项目，他是一个命令行工具集，包含了用户在本地开发和运维模块过程中的常用工具。 [可参考此处](/docs/tutorials/build_and_deploy) -
From 6adc244f6d77b097dcaaa8178f6b1fbfc1490d88 Mon Sep 17 00:00:00 2001 From: Aiden Date: Thu, 10 Jul 2025 16:52:19 +0800 Subject: [PATCH 2/2] docs(contribution-guidelines): update local development testing instructions Enhance the debugging section for module-controller in both English and Chinese documentation. Added commands for building, deploying, and debugging with minikube, and clarified steps for using pre-built images and IDE configurations. --- .../contribution/local-dev-test.md | 57 +++++++++++++++--- .../module-controller-v2/design.md | 58 +------------------ .../contribution/local-dev-test.md | 57 +++++++++++++++--- .../module-controller-v2/design.md | 56 +----------------- 4 files changed, 102 insertions(+), 126 deletions(-) diff --git a/content/en/docs/contribution-guidelines/contribution/local-dev-test.md b/content/en/docs/contribution-guidelines/contribution/local-dev-test.md index 7944f86c..8520b096 100644 --- a/content/en/docs/contribution-guidelines/contribution/local-dev-test.md +++ b/content/en/docs/contribution-guidelines/contribution/local-dev-test.md @@ -26,7 +26,7 @@ make test ``` You can also use an IDE for compiling, building, debugging, and running unit tests.
-The development approach for module-controller is exactly the same as the standard K8S Operator development approach. You can refer to the [official K8S Operator development documentation](https://kubernetes.io/zh-cn/docs/concepts/extend-kubernetes/operator/). +The development approach for module-controller is the same as the standard K8S Operator development approach. You can refer to the [official K8S Operator development documentation](https://kubernetes.io/zh-cn/docs/concepts/extend-kubernetes/operator/). If you want to deploy ModuleController via minikube for remote debugging of the Pod code, you can follow these steps: @@ -36,19 +36,61 @@ If you want to deploy ModuleController via minikube for remote debugging of the minikube image build -f debug.Dockerfile -t serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/module-controller-v2:latest . ``` +Or + +```bash +make minikube-build +``` + +Alternatively, you can directly use a pre-built image, `serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/module-controller-v2:v2.1.4`, which has already been configured with a [go-delve](https://github.com/go-delve/delve) remote debug environment, with debug port 2345. If you use this pre-built image, you need to modify the image pull policy in module-controller-test.yaml from Never to Always. + +```yaml +imagePullPolicy: Always +``` + 2. Apply the Debug deployment. ```bash kubectl apply -f example/quick-start/module-controller-test.yaml ``` -3. Expose the module-controller remote debugging port. +Or + +```bash +make minikube-deploy +``` + +3. Log into the started container. + +```bash +kubectl exec deployments/module-controller -it -- /bin/sh +``` + +4. Inside the container, start delve. + +```bash +dlv --listen=:2345 --headless=true --api-version=2 --accept-multiclient exec ./module_controller +``` + +Steps 3 and 4 can also be quickly executed with the following command. + +```bash +make minikube-debug +``` + +5. Expose the module-controller remote debugging port. ```bash kubectl port-forward deployments/module-controller 2345:2345 ``` -4. Enable remote debugging in your local IDE. Here's a reference for VSCode debug configuration: +Or + +```bash +make minikube-port-forward +``` + +6. Enable remote debugging in your local IDE. Reference VS Code debug configuration: ```json { @@ -74,12 +116,13 @@ kubectl port-forward deployments/module-controller 2345:2345 } ``` -5. Set breakpoints in your IDE and run the debugger to check if the program successfully pauses at the breakpoints. +7. Set breakpoints in your IDE and run the debugger to verify that the program successfully pauses at the breakpoints. -You can use the following command to quickly complete steps 1 and 2 above: +8. When you need your code changes to take effect for debugging, you need to first close the connection, then stop the port forwarding on port 2345, and then run the following commands. -``` -make minikube-debug +```bash +make minikube-restart +make minikube-port-forward ``` ## Arkctl diff --git a/content/en/docs/contribution-guidelines/module-controller-v2/design.md b/content/en/docs/contribution-guidelines/module-controller-v2/design.md index 8a862998..740bf8b0 100644 --- a/content/en/docs/contribution-guidelines/module-controller-v2/design.md +++ b/content/en/docs/contribution-guidelines/module-controller-v2/design.md @@ -144,60 +144,4 @@ Model definition and logical relationships:
-
- -## how to debug - -1. start module-controller test version in minikube, `serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/module-controller-v2:v2.1.4`, the image has been configured with [go-delve](https://github.com/go-delve/delve) remote debug environment, debug port is 2345 - -```yaml - -apiVersion: apps/v1 -kind: Deployment -metadata: - name: module-controller -spec: - replicas: 1 - selector: - matchLabels: - app: module-controller - template: - metadata: - labels: - app: module-controller - spec: - serviceAccountName: virtual-kubelet # 上一步中配置好的 Service Account - containers: - - name: module-controller - image: serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/module-controller-v2:v2.1.4 # 已经打包好的镜像，镜像在 Module-controller 根目录的 debug.Dockerfile - imagePullPolicy: Always - resources: - limits: - cpu: "1000m" - memory: "400Mi" - ports: - - name: httptunnel - containerPort: 7777 - - name: debug - containerPort: 2345 - env: - - name: ENABLE_HTTP_TUNNEL - value: "true" -``` - -2. Log in to the started container -```shell -kubectl exec module-controller-544c965c78-mp758 -it -- /bin/sh -``` - -3. Enter the container and start delve -```shell -dlv --listen=:2345 --headless=true --api-version=2 --accept-multiclient exec ./module_controller -``` - -4. Exit the container and set up port forwarding for port 2345 -```shell -kubectl port-forward module-controller-76bdbcdd8d-fhvfd 2345:2345 -``` - -5. Start remote debugging in Goland or IDEA, with Host as `localhost` and Port as `2345`. + \ No newline at end of file diff --git a/content/zh-cn/docs/contribution-guidelines/contribution/local-dev-test.md b/content/zh-cn/docs/contribution-guidelines/contribution/local-dev-test.md index 929578aa..8da10c21 100644 --- a/content/zh-cn/docs/contribution-guidelines/contribution/local-dev-test.md +++ b/content/zh-cn/docs/contribution-guidelines/contribution/local-dev-test.md @@ -30,25 +30,67 @@ module-controller 开发方式和标准 K8S Operator 开发方式完全一样， 如果想要通过 minikube 部署 ModuleController 来对 Pod 远程调试代码，可以参考以下步骤。 -1. 在 modue-controller 项目里构建 minikube Debug 镜像。 +1. 在 module-controller 项目里构建 minikube Debug 镜像。 ```bash minikube image build -f debug.Dockerfile -t serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/module-controller-v2:latest . ``` +或者 + +```bash +make minikube-build +``` + +也可以直接使用已经构建好的镜像，`serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/module-controller-v2:v2.1.4`，该镜像已经配置了 [go-delve](https://github.com/go-delve/delve) 远程 debug 环境，debug 端口为 2345。如果使用该构建好的镜像，需要修改 module-controller-test.yaml 中的拉取镜像策略从 Never 改为 Always。 + +```yaml +imagePullPolicy: Always +``` + 2. 应用 Debug deployment。 ```bash kubectl apply -f example/quick-start/module-controller-test.yaml ``` -3. 暴露 module-controller 远程调试端口。 +或者 + +```bash +make minikube-deploy +``` + +3. 登录到启动后的容器 + +```bash +kubectl exec deployments/module-controller -it -- /bin/sh +``` + +4. 进入容器内部，启动 delve + +```bash +dlv --listen=:2345 --headless=true --api-version=2 --accept-multiclient exec ./module_controller +``` + +第三步和第四步也可以用下面命令快速启动 delve。 + +```bash +make minikube-debug +``` + +5. 暴露 module-controller 远程调试端口。 ```bash kubectl port-forward deployments/module-controller 2345:2345 ``` -4. 在本地 IDE 上开启远程调试。参考 vscode 调试设置。 +或者 + +```bash +make minikube-port-forward +``` + +6. 在本地 IDE 上开启远程调试。参考 vscode 调试设置。 ```json { @@ -74,12 +116,13 @@ kubectl port-forward deployments/module-controller 2345:2345 } ``` -5. 在 ide 打断点后运行调试，看看程序是否成功在断点处暂停。 +7. 在 IDE 打断点后运行调试，看看程序是否成功在断点处暂停。 -上面的第一步和第二步可以使用下面的命令来快速构建调试。 +8. 当修改代码后需要调试生效时，需要先关闭连接，然后关闭占用 2345 的端口转发，再 make 以下命令。 -``` -make minikube-debug +```bash +make minikube-restart +make minikube-port-forward ``` ## Arkctl diff --git a/content/zh-cn/docs/contribution-guidelines/module-controller-v2/design.md b/content/zh-cn/docs/contribution-guidelines/module-controller-v2/design.md index 2c17d3c5..bbb57708 100644 --- a/content/zh-cn/docs/contribution-guidelines/module-controller-v2/design.md +++ b/content/zh-cn/docs/contribution-guidelines/module-controller-v2/design.md @@ -146,58 +146,4 @@ spec:
-
- -## 如何 debug -1. minikube 中启动 module-controller test 版本，`serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/module-controller-v2:v2.1.4`，该镜像已经配置了 [go-delve](https://github.com/go-delve/delve) 远程 debug 环境，debug 端口为 2345 - -```yaml - -apiVersion: apps/v1 -kind: Deployment -metadata: - name: module-controller -spec: - replicas: 1 - selector: - matchLabels: - app: module-controller - template: - metadata: - labels: - app: module-controller - spec: - serviceAccountName: virtual-kubelet # 上一步中配置好的 Service Account - containers: - - name: module-controller - image: serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/module-controller-v2 # 已经打包好的镜像，镜像在 Module-controller 根目录的 debug.Dockerfile - imagePullPolicy: Always - resources: - limits: - cpu: "1000m" - memory: "400Mi" - ports: - - name: httptunnel - containerPort: 7777 - - name: debug - containerPort: 2345 - env: - - name: ENABLE_HTTP_TUNNEL - value: "true" -``` - -2. 登录到启动后的容器 -```shell -kubectl exec module-controller-544c965c78-mp758 -it -- /bin/sh -``` - -3. 进入容器内部，启动 delve -```shell -dlv --listen=:2345 --headless=true --api-version=2 --accept-multiclient exec ./module_controller -``` -4. 退出容器，打开 2345 端口映射 -```shell -kubectl port-forward module-controller-76bdbcdd8d-fhvfd 2345:2345 -``` -5. goland 或 idea 里启动远程调试，Host 为 localhost，Port 为 2345 - + \ No newline at end of file