[DOCS] KubeRay APIServer V2 document

[machichima]

• 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 :(

[machichima]

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 @-

[dentiny]

as the file link does not exists yet

You can use a commit link?

[dentiny]

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

[rueian]

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 @-

[machichima]

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]

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

[rueian]

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

[machichima]

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

[machichima]

Hi @dentiny ,

Would you mind taking a look at this? Thanks!

[dentiny]

quick first iteration, will continue later today.

[dentiny]

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

[dentiny]

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

[rueian]

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

[machichima]

Sure! I will remove this

[dentiny]

features

[dentiny]

simplifying

[rueian]

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

[machichima]

No problem!

[dentiny]

default

[rueian]

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

[rueian]

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]

Suggested change

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

[rueian]

This is incorrect too.

[rueian]

Suggested change

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

[rueian]

Suggested change

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

[rueian]

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

[rueian]

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.

[machichima]

Got it! Will remove this

[dentiny]

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

[machichima]

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

[machichima]

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

The docs for ray job/service/cluster in this PR provides the way to setup those Ray Resources with "APIServer V2", where the request url and request json body follows the k8s server interface, which I think is different from V1.

[rueian]

Suggested change

	- `resourceType` = Custom resource type (e.g., `rayclusters`, `rayjobs`, `rayserve`)
	- `resourceType` = Custom resource type (e.g., `rayclusters`, `rayjobs`, `rayservices`)

[rueian]

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

[rueian]

Suggested change

	The KubeRay APIServer SDK is the HTTP proxy to the Kubernetes API server with the same
	The KubeRay APIServer SDK provides an HTTP proxy to the Kubernetes API server with the same

[rueian]

Suggested change

	existing Kubernetes clients to interact with the APIServer SDK.
	existing Kubernetes clients to interact with the proxy provided by APIServer SDK.

[rueian]

Suggested change

	2. Provide APIServer SDK Go library for user to build custom HTTP middleware functions.
	2. Provide APIServer SDK as a Go library for users to build their proxies with custom HTTP middleware functions.

[rueian]

Suggested change

	interface. User can directly use Kubernetes OpenAPI Spec and CRD for create, query,
	interface. Users can directly use Kubernetes OpenAPI Spec and KubeRay CRD to create, query,

[rueian]

Suggested change

	- You want to interact with Ray clusters via HTTP/REST (e.g., from a UI, SDK, or CLI).
	- You want to manage Ray clusters in Kubernetes via HTTP/REST (e.g., from a UI, SDK, or CLI).

[dentiny]

@machichima Feel free to ping me on github / slack when you're ready! (please re-request review if PR ready)

[dentiny]

Thanks!

[dentiny]

why uppercase for "Existing" and "Clients"?

[machichima]

They should be lower case. Just fixed! Thanks!

[dentiny]

Suggested change

	You can considering using APIServer SDK if:
	You can consider using APIServer SDK if:

[dentiny]

Suggested change

	The KubeRay ApiServer exposes a RESTful API that mirrors the Kubernetes API Server. You
	The KubeRay APIServer exposes a RESTful API that mirrors the Kubernetes API Server. You

let's be consistent on wording

[dentiny]

Suggested change

	through how to manage and interact with Ray clusters with KubeRay APIServer.
	through how to manage and interact with Ray clusters via KubeRay APIServer.

[dentiny]

Would it be better if we use doc?

> [!NOTICE]
> All the following guidance require you to switch your working directory to the `apiserversdk/`.

[machichima]

Sure, I use IMPORTANT here so that github can render different color and icon for it

Important

something here

[dentiny]

as the file link does not exists yet

You can use a commit link?

[dentiny]

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

[machichima]

I made some changes:

1. As we do not provide access to built-in Kubernetes resources by default, I use kubectl for creating ConfigMap
2. Align word usage for APIServer (changed APIServer SDK, ApiServer to APIServer)
3. Remove change directory to apiserversdk/ guidance as we use existing yaml for request.
4. Use the existing yamls for request. But for rayJob we need to use awk while it contains both RayJob and ConfigMap in a single yaml file

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 @-

If this is ok, then I will remove all json files here then

[rueian]

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]

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?

[machichima]

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

[machichima]

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!