Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 18579b2

Browse files
kevin85421kevin85421
authoredJun 13, 2025··
[doc] Improve APIServer v2 doc (#3773) (#3777)
1 parent 768a9c6 commit 18579b2

File tree

6 files changed

+449
-1
lines changed

6 files changed

+449
-1
lines changed
 

‎apiserver/README.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
<!-- markdownlint-disable MD013 -->
2-
# KubeRay APIServer
2+
# KubeRay APIServer V1 (deprecated)
3+
4+
> [!WARNING]
5+
> KubeRay APIServer V1 is deprecated and will be removed in the future.
6+
> Please use [KubeRay APIServer V2](../apiserversdk/README.md) instead.
37
48
The KubeRay APIServer offers gRPC and HTTP APIs to manage KubeRay resources.
59

‎apiserversdk/README.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# KubeRay APIServer V2 (alpha)
2+
3+
KubeRay APIServer V2 is the successor to the original [KubeRay APIServer V1](../apiserver/README.md).
4+
There are two ways to use KubeRay APIServer V2 as an HTTP proxy server to manage Ray resources:
5+
6+
1. Use it as a Go module to build your own HTTP proxies with custom middleware functions.
7+
2. Use the container image provided by the KubeRay community to run a proxy server.
8+
9+
KubeRay APIServer V2 provides an HTTP proxy to the Kubernetes APIServer with the same
10+
interface defined in the Kubernetes OpenAPI Spec and KubeRay CRD.
11+
Therefore, it is compatible with existing Kubernetes clients and API interfaces.
12+
13+
## When to use KubeRay APIServer V2
14+
15+
Consider using KubeRay APIServer V2 if:
16+
17+
- You want to manage Ray clusters in Kubernetes via HTTP/REST (e.g., from a UI, SDK, or CLI).
18+
- You want to create templates or default values to simplify configuration setup.
19+
20+
For brevity, "KubeRay APIServer V2" will be referred to as "KubeRay APIServer" throughout this documentation.
21+
22+
## Installation
23+
24+
Please follow the [installation guide](docs/installation.md) to install the APIServer, and
25+
port-forward the HTTP endpoint to local port 31888.
26+
27+
## Quick Start
28+
29+
- [RayCluster Quickstart](./docs/raycluster-quickstart.md)
30+
- [RayJob Quickstart](./docs/rayjob-quickstart.md)
31+
- [RayService Quickstart](./docs/rayservice-quickstart.md)
32+
33+
## Usage
34+
35+
The KubeRay APIServer exposes a RESTful API that mirrors the Kubernetes APIServer. You
36+
can interact with it using Kubernetes-style endpoints and request patterns to create,
37+
retrieve, update, and delete custom resources such as `RayCluster` and `RayJob`.
38+
39+
### API Structure
40+
41+
The KubeRay API follows standard Kubernetes conventions. The structure of the endpoint
42+
path depends on whether you are interacting with custom resources (e.g., `RayCluster`) or
43+
core Kubernetes resources.
44+
45+
#### Custom Resources
46+
47+
For custom resources defined by CRDs (e.g., `RayCluster`, `RayJob`, etc.), the endpoint format is:
48+
49+
```sh
50+
<baseURL>/apis/ray.io/v1/namespaces/<namespace>/<resourceType>/<resourceName>
51+
```
52+
53+
- `namespace`: Your target Kubernetes namespace (e.g., `default`)
54+
- `resourceType`: Custom resource type (e.g., `rayclusters`, `rayjobs`, `rayservices`)
55+
- `resourceName`: Name of the resource.
56+
57+
### Label and Field Selectors
58+
59+
When listing resources (using `GET` on a collection endpoint), you can filter results using selectors:
60+
61+
- Label selector: filters resources by their labels.
62+
63+
```sh
64+
# Get all RayClusters with the label key=value
65+
GET /apis/ray.io/v1/namespaces/default/rayclusters?labelSelector=key%3Dvalue
66+
```
67+
68+
- Field selector: Filters resources based on the value of their resource
69+
fields (e.g., `metadata.name`, `status.phase`).
70+
71+
```sh
72+
# Retrieve the RayCluster where the name is raycluster-prod
73+
GET /apis/ray.io/v1/namespaces/default/rayclusters?fieldSelector=metadata.name%3Draycluster-prod
74+
```
75+
76+
- Combined selectors: You can combine label and field selectors using `&`
77+
78+
```sh
79+
# Get the RayCluster named raycluster-prod that also has the label env=prod.
80+
GET /apis/ray.io/v1/namespaces/default/rayclusters?labelSelector=env%3Dprod&fieldSelector=metadata.name%3Draycluster-prod
81+
```

‎apiserversdk/docs/installation.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# KubeRay APIServer Installation
2+
3+
## Step 1: Create a Kubernetes cluster
4+
5+
This step creates a local Kubernetes cluster using [Kind](https://kind.sigs.k8s.io/). If you already have a Kubernetes
6+
cluster, you can skip this step.
7+
8+
```sh
9+
kind create cluster --image=kindest/node:v1.26.0
10+
```
11+
12+
## Step 2: Deploy a KubeRay operator
13+
14+
Follow [this
15+
document](https://docs.ray.io/en/latest/cluster/kubernetes/getting-started/kuberay-operator-installation.html#kuberay-operator-deploy)
16+
to install the latest stable KubeRay operator from the Helm repository.
17+
18+
## Step 3: Install APIServer with Helm
19+
20+
* For v1.4.0, the following Helm chart will launch both KubeRay APIServer V1 and V2 simultaneously in the APIServer Pod.
21+
For v1.5.0, only KubeRay APIServer V2 will be launched, and V1 will be removed.
22+
23+
* The security proxy is an optional feature that is still experimental.
24+
Therefore, the documentation is written without the security proxy.
25+
26+
### Without security proxy
27+
28+
* Install a stable version via Helm repository
29+
30+
```sh
31+
helm repo add kuberay https://ray-project.github.io/kuberay-helm/
32+
helm repo update
33+
# Install KubeRay APIServer without security proxy
34+
helm install kuberay-apiserver kuberay/kuberay-apiserver --version 1.4.0 --set security=null
35+
```
36+
37+
* Install the nightly version
38+
39+
```sh
40+
# Step1: Clone KubeRay repository
41+
42+
# Step2: Navigate to `helm-chart/kuberay-apiserver`
43+
cd helm-chart/kuberay-apiserver
44+
45+
# Step3: Install the KubeRay apiserver
46+
helm install kuberay-apiserver . --set security=null
47+
```
48+
49+
### With security proxy
50+
51+
* Install a stable version via Helm repository
52+
53+
```sh
54+
helm repo add kuberay https://ray-project.github.io/kuberay-helm/
55+
helm repo update
56+
# Install KubeRay APIServer
57+
helm install kuberay-apiserver kuberay/kuberay-apiserver --version 1.4.0
58+
```
59+
60+
* Install the nightly version
61+
62+
```sh
63+
# Step1: Clone KubeRay repository
64+
65+
# Step2: Navigate to `helm-chart/kuberay-apiserver`
66+
cd helm-chart/kuberay-apiserver
67+
68+
# Step3: Install the KubeRay apiserver
69+
helm install kuberay-apiserver .
70+
```
71+
72+
> [!IMPORTANT]
73+
> You may receive an "Unauthorized" error when making a request if you install the
74+
> APIServer with security proxy. Please try the APIServer without a security proxy.
75+
76+
## Step 4: Port-forwarding the APIServer service
77+
78+
Use the following command for port-forwarding to access the APIServer through port 31888:
79+
80+
```sh
81+
kubectl port-forward service/kuberay-apiserver-service 31888:8888
82+
```
83+
84+
## Step 5: Validate installation
85+
86+
Check that the KubeRay APIServer is running in the "default" namespace.
87+
88+
```sh
89+
kubectl get pods
90+
# NAME READY STATUS RESTARTS AGE
91+
# kuberay-apiserver-xxxxxx 1/1 Running 0 17s
92+
```

‎apiserversdk/docs/raycluster-quickstart.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# RayCluster QuickStart
2+
3+
This document explains how to manage and interact with RayCluster using the KubeRay APIServer.
4+
See [this guide](https://docs.ray.io/en/latest/cluster/kubernetes/getting-started/raycluster-quick-start.html) for more details.
5+
6+
## Step 1: Create a Kubernetes cluster
7+
8+
This step creates a local Kubernetes cluster using [Kind](https://kind.sigs.k8s.io/).
9+
If you already have a Kubernetes cluster, you can skip this step.
10+
11+
```sh
12+
kind create cluster --image=kindest/node:v1.26.0
13+
```
14+
15+
## Step 2: Install KubeRay operator and APIServer
16+
17+
Follow the [Installation Guide](installation.md) to install the latest stable KubeRay
18+
operator and APIServer (without the security proxy) from the Helm repository, and
19+
port-forward the HTTP endpoint to local port 31888.
20+
21+
## Step 3: Deploy a RayCluster custom resource
22+
23+
Once the KubeRay operator is running, you are ready to deploy a RayCluster. While we are using APIServer, we can do this
24+
with curl. The following command will create a RayCluster CR named `raycluster-kuberay` in your current cluster:
25+
26+
```sh
27+
curl -s https://raw.githubusercontent.com/ray-project/kuberay/master/ray-operator/config/samples/ray-cluster.sample.yaml | \
28+
curl -X POST http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters \
29+
-H "Content-Type: application/yaml" \
30+
--data-binary @-
31+
```
32+
33+
Once the RayCluster CR has been created, you can view its details by executing the following command:
34+
35+
```sh
36+
curl http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay
37+
```
38+
39+
## Step 4: Modify Created RayCluster
40+
41+
To modify the created RayCluster, we can use the `PATCH` method of the KubeRay APIServer.
42+
The following command adds an `annotation` to the raycluster-kuberay resource:
43+
44+
```sh
45+
curl -X PATCH 'http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay' \
46+
-H 'Content-Type: application/merge-patch+json' \
47+
--data '{
48+
"metadata": {
49+
"annotations": {
50+
"example.com/purpose": "model-training"
51+
}
52+
}
53+
}'
54+
```
55+
56+
You can verify if the `annotation` is added with the following command. You should see the
57+
annotations you added in the output:
58+
59+
```sh
60+
curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay \
61+
| jq '.metadata.annotations'
62+
63+
# [Expected Output]
64+
# {
65+
# "example.com/purpose": "model-training"
66+
# }
67+
```
68+
69+
## Step 5: Delete the RayCluster
70+
71+
To delete the RayCluster with KubeRay APIServer, execute the following command. The `raycluster-kuberay` is the name of
72+
the RayCluster that we created earlier:
73+
74+
```sh
75+
curl -X DELETE 'localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay'
76+
```
77+
78+
You can then verify if the RayCluster is removed. The following command should return 404:
79+
80+
```sh
81+
curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay
82+
```
83+
84+
## Clean up
85+
86+
```sh
87+
kind delete cluster
88+
```

‎apiserversdk/docs/rayjob-quickstart.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# RayJob QuickStart
2+
3+
This document explains how to manage and interact with RayJob using KubeRay APIServer.
4+
See [this guide](https://docs.ray.io/en/latest/cluster/kubernetes/getting-started/rayjob-quick-start.html) for more details.
5+
6+
## Step 1: Create a Kubernetes cluster
7+
8+
This step creates a local Kubernetes cluster using [Kind](https://kind.sigs.k8s.io/). If you already have a Kubernetes
9+
cluster, you can skip this step.
10+
11+
```sh
12+
kind create cluster --image=kindest/node:v1.26.0
13+
```
14+
15+
## Step 2: Install KubeRay operator and APIServer
16+
17+
Follow the [Installation Guide](installation.md) to install the latest stable KubeRay
18+
operator and APIServer (without the security proxy) from the Helm repository, and
19+
port-forward the HTTP endpoint to local port 31888.
20+
21+
## Step 3: Install a RayJob
22+
23+
Once the KubeRay operator is running, we can install a RayJob through APIServer with
24+
following command. This will create a RayJob named `rayjob-interactive-mode`:
25+
26+
```sh
27+
curl -s https://raw.githubusercontent.com/ray-project/kuberay/master/ray-operator/config/samples/ray-job.interactive-mode.yaml \
28+
| curl -X POST http://localhost:31888/apis/ray.io/v1/namespaces/default/rayjobs \
29+
-H "Content-Type: application/yaml" \
30+
--data-binary @-
31+
```
32+
33+
## Step 4: Check RayJob Status
34+
35+
You can check the detail of the submitted RayJob by executing following command:
36+
37+
```sh
38+
curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayjobs/rayjob-interactive-mode
39+
```
40+
41+
## Step 5: Delete the RayJob
42+
43+
To delete the RayJob with KubeRay APIServer, execute the following command. The `rayjob-interactive-mode` is the name of
44+
the RayJob we created.
45+
46+
```sh
47+
curl -X DELETE 'localhost:31888/apis/ray.io/v1/namespaces/default/rayjobs/rayjob-interactive-mode'
48+
```
49+
50+
You can then verify if the RayJob is removed. The following command should return 404:
51+
52+
```sh
53+
curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayjobs/rayjob-interactive-mode
54+
```
55+
56+
## Clean up
57+
58+
```sh
59+
kind delete cluster
60+
```

‎apiserversdk/docs/rayservice-quickstart.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# RayService QuickStart
2+
3+
This document explains how to manage and interact with RayService using KubeRay APIServer.
4+
See [this guide](https://docs.ray.io/en/latest/cluster/kubernetes/getting-started/rayservice-quick-start.html) for more details.
5+
6+
## Step 1: Create a Kubernetes cluster
7+
8+
This step creates a local Kubernetes cluster using [Kind](https://kind.sigs.k8s.io/). If you already have a Kubernetes
9+
cluster, you can skip this step.
10+
11+
```sh
12+
kind create cluster --image=kindest/node:v1.26.0
13+
```
14+
15+
## Step 2: Install KubeRay operator and APIServer
16+
17+
Follow the [Installation Guide](installation.md) to install the latest stable KubeRay
18+
operator and APIServer (without the security proxy) from the Helm repository, and
19+
port-forward the HTTP endpoint to local port 31888.
20+
21+
## Step 3: Install a RayService
22+
23+
The RayService can be created with follow curl command. This will create a RayService
24+
named `rayservice-sample`:
25+
26+
```sh
27+
curl -s https://raw.githubusercontent.com/ray-project/kuberay/master/ray-operator/config/samples/ray-service.sample.yaml | \
28+
curl -X POST http://localhost:31888/apis/ray.io/v1/namespaces/default/rayservices \
29+
-H "Content-Type: application/yaml" \
30+
--data-binary @-
31+
```
32+
33+
Once the RayService CR has been created, you can view its detail by executing following command:
34+
35+
```sh
36+
curl http://localhost:31888/apis/ray.io/v1/namespaces/default/rayservices/rayservice-sample
37+
```
38+
39+
You can also see RayCluster being created:
40+
41+
```sh
42+
curl http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters
43+
```
44+
45+
## Step 4: Check the status of RayService
46+
47+
To check if the RayService is ready, use following command and check if the `status` field
48+
is `True`:
49+
50+
```sh
51+
curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayservices/rayservice-sample | jq -r '.status.conditions[] | select(.type=="Ready") | to_entries[] | "\(.key): \(.value)"'
52+
53+
# lastTransitionTime: 2025-05-19T13:19:26Z
54+
# message: Number of serve endpoints is greater than 0
55+
# observedGeneration: 1
56+
# reason: NonZeroServeEndpoints
57+
# status: True
58+
# type: Ready
59+
```
60+
61+
## Step 5: Zero downtime upgrade for RayCluster
62+
63+
RayService enables a zero downtime upgrades for RayCluster. That is, if you modify
64+
`spec.rayClusterConfig` in the RayService config, it triggers a zero downtime upgrade for
65+
Ray clusters. RayService temporarily creates a new RayCluster and waits for it to be
66+
ready, then switches traffic to the new RayCluster by updating the selector of the head
67+
service managed by RayService `rayservice-sample-head-svc` and terminates the old one.
68+
69+
As an example, we will modify `rayVersion` in `rayClusterConfig` to `2.100.0`. Let's have
70+
a look at the original `rayVersion`. Execute the following command:
71+
72+
```sh
73+
curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayservices/rayservice-sample \
74+
| jq -r '.spec.rayClusterConfig.rayVersion'
75+
76+
# Expected output
77+
# 2.46.0
78+
```
79+
80+
Now, use the following for modifying the `rayVersion` for RayCluster managed by RayService.
81+
82+
```sh
83+
curl -X PATCH http://localhost:31888/apis/ray.io/v1/namespaces/default/rayservices/rayservice-sample \
84+
-H "Content-Type: application/merge-patch+json" \
85+
--data '{
86+
"spec": {
87+
"rayClusterConfig": {
88+
"rayVersion": "2.100.0"
89+
}
90+
}
91+
}'
92+
```
93+
94+
After the execution, you can see the `rayVersion` has been modifie:
95+
96+
```sh
97+
curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayservices/rayservice-sample \
98+
| jq -r '.spec.rayClusterConfig.rayVersion'
99+
100+
# Expected output
101+
# 2.100.0
102+
```
103+
104+
## Step 6: Delete the RayService
105+
106+
To delete the RayService with KubeRay APIServer, execute the following command. The `rayservice-sample` is the name of
107+
the RayService we created earlier.
108+
109+
```sh
110+
curl -X DELETE 'localhost:31888/apis/ray.io/v1/namespaces/default/rayservices/rayservice-sample'
111+
```
112+
113+
You can then verify if the RayService is removed. The following command should return 404:
114+
115+
```sh
116+
curl http://localhost:31888/apis/ray.io/v1/namespaces/default/rayservices/rayservice-sample
117+
```
118+
119+
## Clean up
120+
121+
```sh
122+
kind delete cluster
123+
```

0 commit comments

Comments
 (0)
Please sign in to comment.