[Refactor] Improve developer experience of API server e2e-test (#3466)

* refactor: Simplify the API server launch logic

Signed-off-by: jiangjiawei1103 <waynechuang97@gmail.com>

* docs: Polish help msg of local-e2e-test

Signed-off-by: jiangjiawei1103 <waynechuang97@gmail.com>

* docs: Structure apiserver installation with Helm

Signed-off-by: jiangjiawei1103 <waynechuang97@gmail.com>

* docs: Update the API server setup

Signed-off-by: jiangjiawei1103 <waynechuang97@gmail.com>

* docs: Run apiserver smoke test with a health check endpoint

Signed-off-by: jiangjiawei1103 <waynechuang97@gmail.com>

* docs: Add notes for rebuilding and reploying API server

Signed-off-by: jiangjiawei1103 <waynechuang97@gmail.com>

* docs: Teardown the existing API server deployment

Signed-off-by: jiangjiawei1103 <waynechuang97@gmail.com>

* fix: Solve md  lint

Signed-off-by: jiangjiawei1103 <waynechuang97@gmail.com>

---------

Signed-off-by: jiangjiawei1103 <waynechuang97@gmail.com>
Signed-off-by: 江家瑋 <36886416+JiangJiaWei1103@users.noreply.github.com>

Author: JiangJiaWei1103

apiserver/DEVELOPMENT.md

@@ -78,18 +78,28 @@ This will create or update mock files.
 
 #### End to End Testing
 
-There are two `make` targets provide execute the end to end test (integration between Kuberay API server and Kuberay Operator):
+There are two `make` targets provided to execute the end to end test (integration between Kuberay API server and Kuberay Operator):
+
+* `make e2e-test` executes all the tests defined in the [test/e2e package](./test/e2e/). It uses the cluster defined in `~/.kube/config` to submit the workloads. Please make sure you have done the following before running `make e2e-test`:
+    1. Install the KubeRay Operator into the cluster by running `make operator-image load-operator-image deploy-operator`
+    2. Install the KubeRay API server into the cluster by running `make install`
+    3. Verify the setup with a smoke test `curl -I localhost:31888/healthz`, and you should see a response like:
+
+```bash
+> curl -I localhost:31888/healthz
+HTTP/1.1 200 OK
+Date: Tue, 29 Apr 2025 12:36:05 GMT
+```
+
+> [!NOTE]
+> Please rerun `make uninstall && make install` whenever you make changes to the `apiserver/` codebase to ensure the KubeRay API server is rebuilt and redeployed properly. Alternatively, you can simply run `make start-local-apiserver` to spin up the API server within the kind cluster in one single command.
 
-* `make e2e-test` executes all the tests defined in the [test/e2e package](./test/e2e/). It uses the cluster defined in `~/.kube/config` to submit the workloads. Please make sure you have done the following before running this:
-    1. Install the KubeRay Operator into the cluster by `make operator-image load-operator-image deploy-operator`
-    2. Apiserver is running (see [Build](#build))
-    3. Set the `E2E_API_SERVER_URL` environment variable with value `http://localhost:8888`, as the local apiserver will be listening on port `8888`
 * `make local-e2e-test` creates a local kind cluster, builds the Kuberay operator and API server images from the current branch and deploys the operator and API server into the kind cluster. It shuts down the kind cluster upon successful execution of the end to end test. If the tests fail the cluster will be left running and will have to manually be shutdown by executing the `make clean-cluster`
 
 The `e2e` test targets use two variables to control what version of Ray images to use in the end to end tests:
 
 * `E2E_API_SERVER_RAY_IMAGE` -- for the ray docker image. Currently set to `rayproject/ray:2.9.0-py310`. On Apple silicon or arm64 development machines the `-aarch64` suffix is added to the image.
-* `E2E_API_SERVER_URL` -- for the base URL of the deployed KubeRayAPI server. The default value is: `http://localhost:31888`
+* `E2E_API_SERVER_URL` -- for the base URL of the deployed KubeRay API server. The default value is: `http://localhost:31888`
 
 The end to end test targets share the usage of the `GO_TEST_FLAGS`. Overriding the make file variable with a `-v` option allows for both unit and end to end tests to print any output / debug messages. By default, only if there's a test failure those messages are shown.
 

apiserver/Makefile

@@ -57,7 +57,7 @@ help: ## Display this help.
 ##@ Deployment
 
 .PHONY: start-local-apiserver
-start-local-apiserver: operator-image cluster load-operator-image deploy-operator install run ## Build and start apiserver from scratch.
+start-local-apiserver: operator-image cluster load-operator-image deploy-operator install ## Build and start apiserver from scratch.
 
 .PHONY: clear-local-apiserver
 clear-local-apiserver: clean-cluster ## Clear local apiserver.
@@ -110,8 +110,8 @@ test: fmt vet fumpt imports generate ## Run all unit tests.
 e2e-test: ## Run end to end tests using a pre-exiting cluster.
 	go test ./test/e2e/... $(GO_TEST_FLAGS) -timeout 60m -race -coverprofile ray-kube-api-server-e2e-coverage.out -count=1 -parallel 4
 
-.PHONY: local-e2e-test ## Run end to end tests on newly created cluster.
-local-e2e-test: operator-image cluster load-operator-image deploy-operator install load-ray-test-image e2e-test clean-cluster ## Run end to end tests, create a fresh kind cluster will all components deployed.
+.PHONY: local-e2e-test
+local-e2e-test: start-local-apiserver load-ray-test-image e2e-test clean-cluster ## Run end to end tests on a newly created kind cluster with all components deployed.
 
 ##@ Testing Setup
 KIND_CONFIG ?= hack/kind-cluster-config.yaml

apiserver/README.md

@@ -38,15 +38,15 @@ curl --silent -X 'GET' \
     -H 'accept: application/json'
 ```
 
-### Helm
+### Install with Helm
 
 Make sure the version of Helm is v3+. Currently, [existing CI tests](https://github.com/ray-project/kuberay/blob/master/.github/workflows/helm-lint.yaml) are based on Helm v3.4.1 and v3.9.4.
 
 ```sh
 helm version
 ```
 
-### Install KubeRay Operator
+#### Install KubeRay Operator
 
 - Install a stable version via Helm repository (only supports KubeRay v0.4.0+)
 
@@ -63,7 +63,7 @@ helm version
     # kuberay-operator-7456c6b69b-t6pt7                1/1     Running   0          172m
   ```
 
-### Install KubeRay APIServer
+#### Install KubeRay APIServer
 
 ```text
 Please note that examples show here will only work with the nightly builds of the api-server. `v1.0.0` does not yet contain critical fixes
@@ -110,7 +110,7 @@ to the api server that would allow Kuberay Serve endpoints to work properly
   make docker-image cluster load-image deploy
   ```
 
-### List the chart
+#### List the chart
 
 To list the deployments:
 
@@ -121,7 +121,7 @@ helm ls
 # kuberay-operator        default         1               2023-09-25 10:41:48.355831 +0300 EEST   deployed        kuberay-operator-1.0.0
 ```
 
-### Uninstall the Chart
+#### Uninstall the Chart
 
 ```sh
 # Uninstall the `kuberay-apiserver` release