[DOCS] KubeRay APIServer V2 document #3594

machichima · 2025-05-13T15:04:54Z

Add README describe when to use APIServer, and as an entry point to all other docs
Add installation guide to install and start APIServer SDK with helm (currently just a fake one as we do not have helm chart for it yet)
Add examples to create/delete/modify RayCluster, RayJob, and RayService

Why are these changes needed?

Adding documents and examples for user to easily follow when using KubeRay APIServer SDK

Related issue number

Checks

I've made sure the tests are passing.
Testing Strategy
- Unit tests
- Manual tests
- This PR is not tested :(

Signed-off-by: machichima <[email protected]>

machichima · 2025-05-15T14:27:00Z

apiserversdk/docs/raycluster-quickstart.md

+curl -X POST 'localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters' \
+--header 'Content-Type: application/json' \
+--data  @docs/api-example/raycluster.json


Should I directly use link to the json file instead of the path here (see below)? Like what Kuberay docs did.

However, this will make this example currently not available to execute, as the file link does not exists yet.

curl -s https://raw.githubusercontent.com/ray-project/kuberay/v1.4.0/apiserversdk/docs/api-example/raycluster.json | \ curl -X POST 'localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters' \ --header 'Content-Type: application/json' \ --data-binary @-

as the file link does not exists yet

You can use a commit link?

Should I directly use link to the json file instead of the path here (see below)? Like what Kuberay docs did.

Current command looks good to me

I'd like to avoid maintaining new JSON files if possible.

Can we just use the existing yamls https://github.com/ray-project/kuberay/tree/master/ray-operator/config/samples?

curl -s https://raw.githubusercontent.com/ray-project/kuberay/master/ray-operator/config/samples/....yaml | \ curl -X POST localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters \ -H "Content-Type: application/yaml" \ --data-binary @-

Hi @rueian

Sure! However, for rayJob, the yaml contains both ConfigMap and RayJob, which we need to use awk for splitting them. The command will be like so:

# For config map curl -s https://raw.githubusercontent.com/ray-project/kuberay/v1.3.0/ray-operator/config/samples/ray-job.sample.yaml \ | awk 'BEGIN{d=-1} /^---/{d++; next} d==0' \ | kubectl apply -f - # for rayjob curl -s https://raw.githubusercontent.com/ray-project/kuberay/v1.3.0/ray-operator/config/samples/ray-job.sample.yaml \ | awk 'BEGIN{d=-1} /^---/{d++; next} d==-1' \ | curl -X POST http://localhost:31888/apis/ray.io/v1/namespaces/default/rayjobs \ -H "Content-Type: application/yaml" \ --data-binary @-

This makes the command more complex. Do you think this is ok?

machichima · 2025-05-15T14:28:19Z

apiserversdk/Installation.md

+helm repo add kuberay https://ray-project.github.io/kuberay-helm/
+helm repo update
+# Install KubeRay APIServer SDK
+helm install kuberay-apiserver-sdk kuberay/kuberay-apiserver-sdk --version 1.0.0


This is currently not working, while we do not have kuberay-apiserver-sdk helm chart yet. We can modify this afterwards

we will use the same chart and the same container image. see #3603 (review)

Got it! Then I will use kuberay-apiserver directly then
Thanks for the information!

machichima · 2025-05-15T14:31:48Z

Hi @dentiny ,

Would you mind taking a look at this? Thanks!

dentiny

quick first iteration, will continue later today.

dentiny · 2025-05-15T16:53:08Z

apiserversdk/README.md

+# KubeRay APIServer SDK
+
+The KubeRay APIServer SDK is the HTTP proxy to the Kubernetes API server with the same
+interface. User can directly use Kubernetes OpenAPI Spec and CRD for create, delete, and


mention query as well? People usually say "CRUD" together

dentiny · 2025-05-15T16:54:17Z

apiserversdk/README.md

+interface. User can directly use Kubernetes OpenAPI Spec and CRD for create, delete, and
+update Ray resources. It contains following highlight features:
+
+1. Enable creating ComputeTemplate, which support setting default values that can be used


curious do we support compute template in v2 for now? I thought it's in stage-2

No, we don't. Can we remove this statement for now?

Sure! I will remove this

dentiny · 2025-05-15T16:54:54Z

apiserversdk/README.md

+
+## When to use APIServer SDK
+
+KubeRay APIServer SDK featured in simplify Ray resources management by hiding


simplifying

I think "hiding Kubernetes-specific details" isn't correct. Can we just remove it and only keep "You can consider using APIServer SDK if"

No problem!

dentiny · 2025-05-15T16:55:41Z

apiserversdk/README.md

+- You want to interact with Ray clusters via HTTP/REST (e.g., from a UI, SDK, or CLI).
+- Your team prefers a simplified, non-Kubernetes-specific API surface to manage resources
+lifecycles.
+- You want to create templates or defulat values to simplify the configuration setup.


apiserversdk/README.md

rueian · 2025-05-15T18:18:37Z

apiserversdk/README.md

+interface. User can directly use Kubernetes OpenAPI Spec and CRD for create, delete, and
+update Ray resources. It contains following highlight features:
+
+1. Enable creating ComputeTemplate, which support setting default values that can be used


No, we don't. Can we remove this statement for now?

rueian · 2025-05-15T18:20:09Z

apiserversdk/README.md

+
+## When to use APIServer SDK
+
+KubeRay APIServer SDK featured in simplify Ray resources management by hiding


I think "hiding Kubernetes-specific details" isn't correct. Can we just remove it and only keep "You can consider using APIServer SDK if"

rueian · 2025-05-15T18:20:57Z

apiserversdk/README.md

+Kubernetes-specific details. You can considering using APIServer SDK if:
+
+- You want to interact with Ray clusters via HTTP/REST (e.g., from a UI, SDK, or CLI).
+- Your team prefers a simplified, non-Kubernetes-specific API surface to manage resources


Suggested change

- Your team prefers a simplified, non-Kubernetes-specific API surface to manage resources

This is incorrect too.

rueian · 2025-05-15T18:25:31Z

apiserversdk/README.md

+For custom resources defined by CRDs (e.g. `RayCluster`, `RayJob`, etc.), the endpoint format is:
+
+```sh
+<baseURL>/apis/<group>/<version>/namespaces/<namespace>/<resourceType>/<resourceName>


Suggested change

<baseURL>/apis/<group>/<version>/namespaces/<namespace>/<resourceType>/<resourceName>

<baseURL>/apis/ray.io/v1/namespaces/<namespace>/<resourceType>/<resourceName>

rueian · 2025-05-15T18:25:42Z

apiserversdk/README.md

+- `group` = `ray.io`
+- `version` = `v1`


Suggested change

- `group` = `ray.io`

- `version` = `v1`

Just make it simpler by embedding the group and the version to the url.

rueian · 2025-05-15T18:27:10Z

apiserversdk/README.md

+#### Core Kubernetes Resources
+
+For built-in Kubernetes resources (e.g. `ConfigMap`), the endpoint format is:
+
+```sh
+<baseURL>/api/v1/namespaces/<namespace>/<resourceType>/<resourceName>
+```
+
+- `namespace`: The target namespace
+- `resourceType`: Core resource type (e.g. `pods`, `configmaps`, `services`)
+- `resourceName`: Name of the resource


Suggested change

#### Core Kubernetes Resources

For built-in Kubernetes resources (e.g. `ConfigMap`), the endpoint format is:

```sh

<baseURL>/api/v1/namespaces/<namespace>/<resourceType>/<resourceName>

```

- `namespace`: The target namespace

- `resourceType`: Core resource type (e.g. `pods`, `configmaps`, `services`)

- `resourceName`: Name of the resource

We don't provide access to built-in Kubernetes resources by default.

Got it! Will remove this

dentiny · 2025-05-15T18:52:02Z

apiserversdk/docs/rayservice-quickstart.md

@@ -0,0 +1,223 @@
+# RayCluster QuickStart
+
+RayService consists of a RayCluster and Ray Serve deployment graphs. It offers


may I ask what's a "deployment graph"?

I think it's a DAG to describe the deployments. I grab the information from here:
https://docs.ray.io/en/latest/cluster/kubernetes/getting-started.html#custom-resource-definitions-crds

dentiny

question on this PR's scope: this pr is titled "apiserver v2 doc", so I expect only see "apiserversdk" related changes, but not sure why we have ray job/service/cluster's change here?
I thought they're part of your another doc improve pr: #3564

apiserversdk/README.md

Signed-off-by: machichima <[email protected]>

rueian · 2025-05-18T18:29:06Z

But for rayJob we need to use awk while it contains both RayJob and ConfigMap in a single yaml file

Hi @machichima,

Can we use https://github.com/ray-project/kuberay/blob/master/ray-operator/config/samples/ray-job.interactive-mode.yaml which has no config map.

rueian · 2025-05-18T18:38:15Z

apiserversdk/docs/raycluster-quickstart.md

+```sh
+kubectl get rayclusters
+# NAME                 DESIRED WORKERS   AVAILABLE WORKERS   CPUS   MEMORY   GPUS   STATUS   AGE
+# raycluster-kuberay   1                                     2      3G       0               89s
+```
+
+The KubeRay operator detects the RayCluster object and starts your Ray cluster by creating head and worker pods. To view
+Ray cluster’s pods, run the following command:
+
+```sh
+# View the pods in the RayCluster named "raycluster-kuberay"
+kubectl get pods --selector=ray.io/cluster=raycluster-kuberay
+
+# NAME                                          READY   STATUS    RESTARTS   AGE
+# raycluster-kuberay-head-k7rlq                 1/1     Running   0          56s
+# raycluster-kuberay-workergroup-worker-65zl8   1/1     Running   0          56s
+```


I wonder if we really need these kubectl details in this document. I think a curl http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay example for checking the cluster status is enough.

For other kubectl operations, can we just refer them to the ray-operator document?

Sure! That seems better

I copied some of the content from kuberay operator docs to make the example more complete. I will try to make it minimal and focus only on apiserver curl

Hi @rueian
I updated the docs to make it use only curl commands and avoid kubectl. Please have a look and see if it looks good to you.
Thanks!

Signed-off-by: machichima <[email protected]>

dentiny · 2025-05-21T07:09:23Z

@machichima Hmm for these doc related changes, maybe next time we could get copilot / gpt to do a sanity check on spelling and wording.

Signed-off-by: machichima <[email protected]>

machichima · 2025-05-21T12:59:57Z

@machichima Hmm for these doc related changes, maybe next time we could get copilot / gpt to do a sanity check on spelling and wording.

Thanks for the suggestion! I just do the proof reading by copilot to fix the wording issues.
They should be fine now

dentiny

Thanks!

rueian

LGTM

dentiny · 2025-05-23T11:54:25Z

@kevin85421 for a final look, the failed CI seems to be flaky test, and has nothing to do with this PR (which does no function change).

kevin85421 · 2025-05-24T05:09:24Z

In today's sync, I will review this after @troychiu's PR to support API server V2 merged.

…r-v2-docs Signed-off-by: machichima <[email protected]>

Signed-off-by: machichima <[email protected]>

machichima · 2025-05-25T03:47:02Z

Added the following to help users follow the example without confusion:

Guidance to install APIServer without security proxy in Installation.md
Troubleshooting page to show how to get rid of "Unauthorized" when sending request with APIServer

…r-v2-docs Signed-off-by: machichima <[email protected]>

Signed-off-by: machichima <[email protected]>

machichima · 2025-05-30T01:11:21Z

apiserversdk/Installation.md

+Use the following command for port-forwarding to access the APIServer through port 31888:
+
+```sh
+kubectl port-forward service/kuberay-apiserver-service 31888:8888


Added the port-forward here, which requires the changes in PR #3708

Signed-off-by: machichima <[email protected]>

machichima added 9 commits May 13, 2025 23:03

docs: add raycluster example with apiserversdk

b7724d0

Signed-off-by: machichima <[email protected]>

docs: update curl cmd and add modify raycluster section

4a63228

Signed-off-by: machichima <[email protected]>

docs: add rayjob example with apiserver

5199afe

Signed-off-by: machichima <[email protected]>

docs: add usage guide for api format

6047b8c

Signed-off-by: machichima <[email protected]>

docs: add rayservice example docs

36c6980

Signed-off-by: machichima <[email protected]>

docs: update installation guide

a101f8f

Signed-off-by: machichima <[email protected]>

docs: fix some error

4492852

Signed-off-by: machichima <[email protected]>

docs: add quick start links to readme

2836c1b

Signed-off-by: machichima <[email protected]>

docs: update installation guide link

b3653b9

Signed-off-by: machichima <[email protected]>

machichima commented May 15, 2025

View reviewed changes

machichima marked this pull request as ready for review May 15, 2025 14:31

dentiny reviewed May 15, 2025

View reviewed changes

dentiny requested review from rueian and kevin85421 May 15, 2025 16:59

dentiny assigned rueian, kevin85421 and dentiny May 15, 2025

rueian reviewed May 15, 2025

View reviewed changes

dentiny reviewed May 15, 2025

View reviewed changes

apiserversdk/README.md Show resolved Hide resolved

dentiny reviewed May 15, 2025

View reviewed changes