[DOCS] KubeRay APIServer V2 document

apiserversdk/Installation.md

@@ -0,0 +1,86 @@
+# KubeRay APIServer Installation
+
+## Step 1: Create a Kubernetes cluster
+
+This step creates a local Kubernetes cluster using [Kind](https://kind.sigs.k8s.io/). If you already have a Kubernetes
+cluster, you can skip this step.
+
+```sh
+kind create cluster --image=kindest/node:v1.26.0
+```
+
+## Step 2: Deploy a KubeRay operator
+
+Follow [this
+document](https://docs.ray.io/en/latest/cluster/kubernetes/getting-started/kuberay-operator-installation.html#kuberay-operator-deploy)
+to install the latest stable KubeRay operator from the Helm repository.
+
+## Step 3: Install APIServer with Helm
+
+### Without security proxy
+
+- Install a stable version via Helm repository
+
+```sh
+helm repo add kuberay https://ray-project.github.io/kuberay-helm/
+helm repo update
+# Install KubeRay APIServer without security proxy
+helm install kuberay-apiserver kuberay/kuberay-apiserver --version 1.4.0 --set security=null
+```
+
+- Install the nightly version
+
+```sh
+# Step1: Clone KubeRay repository
+
+# Step2: Navigate to `helm-chart/kuberay-apiserver`
+cd helm-chart/kuberay-apiserver
+
+# Step3: Install the KubeRay apiserver
+helm install kuberay-apiserver . --set security=null
+```
+
+### With security proxy
+
+- Install a stable version via Helm repository
+
+```sh
+helm repo add kuberay https://ray-project.github.io/kuberay-helm/
+helm repo update
+# Install KubeRay APIServer
+helm install kuberay-apiserver kuberay/kuberay-apiserver --version 1.4.0
+```
+
+- Install the nightly version
+
+```sh
+# Step1: Clone KubeRay repository
+
+# Step2: Navigate to `helm-chart/kuberay-apiserver`
+cd helm-chart/kuberay-apiserver
+
+# Step3: Install the KubeRay apiserver
+helm install kuberay-apiserver .
+```
+
+> [!IMPORTANT]
+> You may receive an "Unauthorized" error when making a request if you install the
+> APIServer with security proxy. Please try the APIServer without a security proxy.
+
+## Step 4: Port-forwarding the APIServer service
+
+Use the following command for port-forwarding to access the APIServer through port 31888:
+
+```sh
+kubectl port-forward service/kuberay-apiserver-service 31888:8888
+```
+
+## Step 5: Validate installation
+
+Check that the KubeRay APIServer is running in the "default" namespace.
+
+```sh
+kubectl get pods
+# NAME                            READY   STATUS    RESTARTS   AGE
+# kuberay-apiserver-xxxxxx    1/1     Running   0          17s
+```

apiserversdk/README.md

@@ -0,0 +1,77 @@
+# KubeRay APIServer
+
+The KubeRay APIServer provides an HTTP proxy to the Kubernetes APIServer with the same
+interface. Users can directly use the Kubernetes OpenAPI Spec and KubeRay CRD to create, query,
+update, and delete Ray resources. It contains the following highlighted features:
+
+1. Compatibility with existing Kubernetes clients and API interfaces, allowing users to use
+   existing Kubernetes clients to interact with the proxy provided by the APIServer.
+2. Provides the APIServer as a Go library for users to build their proxies with custom HTTP middleware functions.
+
+## When to use APIServer
+
+Consider using the APIServer if:
+
+- You want to manage Ray clusters in Kubernetes via HTTP/REST (e.g., from a UI, SDK, or CLI).
+- You want to create templates or default values to simplify configuration setup.
+
+## Installation
+
+Please follow the [Installation](./Installation.md) guide to install the APIServer, and
+port-forward the HTTP endpoint to local port 31888.
+
+## Quick Start
+
+- [RayCluster Quickstart](./docs/raycluster-quickstart.md)
+- [RayJob Quickstart](./docs/rayjob-quickstart.md)
+- [RayService Quickstart](./docs/rayservice-quickstart.md)
+
+## Usage
+
+The KubeRay APIServer exposes a RESTful API that mirrors the Kubernetes APIServer. You
+can interact with it using Kubernetes-style endpoints and request patterns to create,
+retrieve, update, and delete custom resources such as `RayCluster` and `RayJob`.
+
+### API Structure
+
+The KubeRay API follows standard Kubernetes conventions. The structure of the endpoint
+path depends on whether you are interacting with custom resources (e.g., `RayCluster`) or
+core Kubernetes resources.
+
+#### Custom Resources
+
+For custom resources defined by CRDs (e.g., `RayCluster`, `RayJob`, etc.), the endpoint format is:
+
+```sh
+<baseURL>/apis/ray.io/v1/namespaces/<namespace>/<resourceType>/<resourceName>
+```
+
+- `namespace`: Your target Kubernetes namespace (e.g., `default`)
+- `resourceType`: Custom resource type (e.g., `rayclusters`, `rayjobs`, `rayservices`)
+- `resourceName`: Name of the resource.
+
+### Label and Field Selectors
+
+When listing resources (using `GET` on a collection endpoint), you can filter results using selectors:
+
+- Label selector: filters resources by their labels.
+
+```sh
+# Get all RayClusters with the label key=value
+GET /apis/ray.io/v1/namespaces/default/rayclusters?labelSelector=key%3Dvalue
+```
+
+- Field selector: Filters resources based on the value of their resource
+fields (e.g., `metadata.name`, `status.phase`).
+
+```sh
+# Retrieve the RayCluster where the name is raycluster-prod
+GET /apis/ray.io/v1/namespaces/default/rayclusters?fieldSelector=metadata.name%3Draycluster-prod
+```
+
+- Combined selectors: You can combine label and field selectors using `&`
+
+```sh
+# Get the RayCluster named raycluster-prod that also has the label env=prod.
+GET /apis/ray.io/v1/namespaces/default/rayclusters?labelSelector=env%3Dprod&fieldSelector=metadata.name%3Draycluster-prod
+```

apiserversdk/Troubleshooting.md

@@ -0,0 +1,10 @@
+# Troubleshooting
+
+This page contains common issues and their solutions for using the APIServer.
+
+## Getting "Unauthorized" when sending a request
+
+If you receive an "Unauthorized" error when making a request, and you installed APIServer
+using the Helm chart, please try the following solution
+
+- Install the APIServer without a security proxy. Refer to the [Installation](./Installation.md) guide.

apiserversdk/docs/raycluster-quickstart.md

@@ -0,0 +1,97 @@
+# RayCluster QuickStart
+
+This document focuses on explaining how to manage and interact with RayCluster using the
+KubeRay APIServer. For a detailed introduction and more advanced usage with Kubernetes,
+please refer to [this
+guide](https://docs.ray.io/en/latest/cluster/kubernetes/getting-started/raycluster-quick-start.html).
+
+> [!IMPORTANT]
+> If you encounter any problems while following this guide, please refer to the [Troubleshooting](../Troubleshooting.md)
+> page.
+
+## Preparation
+
+- Install [Helm](https://helm.sh/docs/intro/install/) (>= v3.4),
+[Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation), and
+[Docker](https://docs.docker.com/engine/install/).
+- KubeRay v1.4.0 or higher and Ray 2.41.0.
+- Make sure your Kubernetes cluster has at least 4 CPU and 4 GB RAM.
+
+## Step 1: Create a Kubernetes cluster
+
+This step creates a local Kubernetes cluster using [Kind](https://kind.sigs.k8s.io/). If you already have a Kubernetes
+cluster, you can skip this step.
+
+```sh
+kind create cluster --image=kindest/node:v1.26.0
+```
+
+## Step 2: Install KubeRay operator and APIServer
+
+Follow the [Installation Guide](../Installation.md) to install the latest stable KubeRay
+operator and APIServer (without the security proxy) from the Helm repository, and
+port-forward the HTTP endpoint to local port 31888.
+
+## Step 3: Deploy a RayCluster custom resource
+
+Once the KubeRay operator is running, you are ready to deploy a RayCluster. While we are using APIServer, we can do this
+with curl. The following command will create a RayCluster CR named `raycluster-kuberay` in your current cluster:
+
+```sh
+curl -s https://raw.githubusercontent.com/ray-project/kuberay/master/ray-operator/config/samples/ray-cluster.sample.yaml | \
+curl -X POST http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters \
+  -H "Content-Type: application/yaml" \
+  --data-binary @-
+```
+
+Once the RayCluster CR has been created, you can view its details by executing the following command:
+
+```sh
+curl http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay
+```
+
+## Step 4: Modify Created RayCluster
+
+To modify the created RayCluster, we can use the `PATCH` method of the KubeRay APIServer.
+The following command adds an `annotation` to the raycluster-kuberay resource:
+
+```sh
+curl -X PATCH 'http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay' \
+-H 'Content-Type: application/merge-patch+json' \
+--data '{
+  "metadata": {
+    "annotations": {
+      "example.com/purpose": "model-training"
+    }
+  }
+}'
+```
+
+You can verify if the `annotation` is added with the following command. You should see the
+annotations you added in the output:
+
+```sh
+curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay \
+  | jq '.metadata.annotations'
+```
+
+## Step 5: Delete the RayCluster
+
+To delete the RayCluster with KubeRay APIServer, execute the following command. The `raycluster-kuberay` is the name of
+the RayCluster that we created earlier:
+
+```sh
+curl -X DELETE 'localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay'
+```
+
+You can then verify if the RayCluster is removed. The following command should return 404:
+
+```sh
+curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayclusters/raycluster-kuberay
+```
+
+## Clean up
+
+```sh
+kind delete cluster
+```

apiserversdk/docs/rayjob-quickstart.md

@@ -0,0 +1,74 @@
+# RayJob QuickStart
+
+RayJob automatically creates the RayCluster, submits the job when ready, and can
+optionally delete the RayCluster after the job finishes. This document focus on explaining
+how to manage and interact with RayJob using the KubeRay APIServer. For detailed
+introduction and more advanced usage with Kubernetes, please refer to [this
+guide](https://docs.ray.io/en/latest/cluster/kubernetes/getting-started/rayjob-quick-start.html).
+
+> [!IMPORTANT]
+> If you encounter any problems while following this guide, please refer to the [Troubleshooting](../Troubleshooting.md)
+> page.
+
+## Preparation
+
+- Install [Helm](https://helm.sh/docs/intro/install/) (>= v3.4),
+[Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation), and
+[Docker](https://docs.docker.com/engine/install/).
+- KubeRay v1.4.0 or higher and Ray 2.41.0.
+
+## Step 1: Create a Kubernetes cluster
+
+This step creates a local Kubernetes cluster using [Kind](https://kind.sigs.k8s.io/). If you already have a Kubernetes
+cluster, you can skip this step.
+
+```sh
+kind create cluster --image=kindest/node:v1.26.0
+```
+
+## Step 2: Install KubeRay operator and APIServer
+
+Follow the [Installation Guide](../Installation.md) to install the latest stable KubeRay
+operator and APIServer (without the security proxy) from the Helm repository, and
+port-forward the HTTP endpoint to local port 31888.
+
+## Step 3: Install a RayJob
+
+Once the KubeRay operator is running, we can install a RayJob through APIServer with
+following command. This will create a RayJob named `rayjob-interactive-mode`:
+
+```sh
+curl -s https://raw.githubusercontent.com/ray-project/kuberay/master/ray-operator/config/samples/ray-job.interactive-mode.yaml \
+  | curl -X POST http://localhost:31888/apis/ray.io/v1/namespaces/default/rayjobs \
+    -H "Content-Type: application/yaml" \
+    --data-binary @-
+```
+
+## Step 4: Check RayJob Status
+
+You can check the detail of the submitted RayJob by executing following command:
+
+```sh
+curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayjobs/rayjob-interactive-mode
+```
+
+## Step 5: Delete the RayJob
+
+To delete the RayJob with KubeRay APIServer, execute the following command. The `rayjob-interactive-mode` is the name of
+the RayJob we created.
+
+```sh
+curl -X DELETE 'localhost:31888/apis/ray.io/v1/namespaces/default/rayjobs/rayjob-interactive-mode'
+```
+
+You can then verify if the RayJob is removed. The following command should return 404:
+
+```sh
+curl -s http://localhost:31888/apis/ray.io/v1/namespaces/default/rayjobs/rayjob-interactive-mode
+```
+
+## Clean up
+
+```sh
+kind delete cluster
+```