[YUNIKORN-2693] Add a example doc of ray service & componentize dupli…

…cated block (#447)
apache · Jul 3, 2024 · 62ea469 · 62ea469
1 parent a9750bc
commit 62ea469
Show file tree

Hide file tree

Showing 12 changed files with 121 additions and 57 deletions.
diff --git a/docs/assets/run-ray-service-kuberay-dashboard-ui.png b/docs/assets/run-ray-service-kuberay-dashboard-ui.png
diff --git a/docs/assets/run-ray-service-kuberay-service-api-testing.png b/docs/assets/run-ray-service-kuberay-service-api-testing.png
diff --git a/docs/assets/run-ray-service-kuberay-service-pod.png b/docs/assets/run-ray-service-kuberay-service-pod.png
diff --git a/docs/assets/run-ray-service-yunikorn-ui.png b/docs/assets/run-ray-service-yunikorn-ui.png
diff --git a/docs/user_guide/workloads/kuberay/_ray_crd_yunikorn_config.mdx b/docs/user_guide/workloads/kuberay/_ray_crd_yunikorn_config.mdx
@@ -0,0 +1,11 @@
+### Configure your Ray CRD(optional)
+If you disable admission controller, you need to add the schedulerName: yunikorn in [raycluster labels](https://github.com/ray-project/kuberay/blob/fd9c90cad28a1460d4472abbb2b5db43a5e4a813/helm-chart/ray-cluster/templates/raycluster-cluster.yaml#L108). 
+```
+#example
+metadata:
+  labels:
+    applicaionId: ray-<service_type>-0001
+    queue: root.ray.<specific_queue_name>
+spec:
+  schedulerName: yunikorn # k8s will inform yunikorn based on this
+```
diff --git a/docs/user_guide/workloads/kuberay/_ray_operator.mdx b/docs/user_guide/workloads/kuberay/_ray_operator.mdx
@@ -0,0 +1,8 @@
+## Setup a KubeRay operator
+```
+helm repo add kuberay https://ray-project.github.io/kuberay-helm/
+helm repo update
+helm install kuberay-operator kuberay/kuberay-operator --version 1.1.1
+```
+- The result should be as shown below
+![ray_cluster_operator](../../../assets/ray_cluster_operator.png)
diff --git a/docs/user_guide/workloads/run_ray_cluster.md b/docs/user_guide/workloads/run_ray_cluster.md
@@ -1,11 +1,15 @@
 ---
 id: run_ray_cluster
-title: Run Ray Cluster
+title: Run RayCluster
 description: How to run Ray Cluster jobs with YuniKorn
 keywords:
  - Ray_crd
 ---
 
+import RayOperator from './kuberay/_ray_operator.mdx';
+import RayCRDYunikornConfig from './kuberay/_ray_crd_yunikorn_config.mdx';
+import YunikornConfigMapPatch from './utils/_yunikorn_configmap_patch.mdx';
+
 <!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
@@ -25,46 +29,25 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-## Note
-This example demonstrates how to set up [KubeRay](https://docs.ray.io/en/master/cluster/kubernetes/getting-started.html) and run a [Ray Cluster](https://docs.ray.io/en/master/cluster/kubernetes/getting-started/raycluster-quick-start.html) with the YuniKorn scheduler. It relies on an admission controller to configure the default applicationId and queue name. If you want more details, please refer to [Yunikorn supported labels](https://yunikorn.apache.org/docs/user_guide/labels_and_annotations_in_yunikorn) and [Yunikorn queue setting](https://yunikorn.apache.org/docs/user_guide/queue_config).
-
-## Modify YuniKorn settings
-Follow [YuniKorn install guide](https://yunikorn.apache.org/docs/) and modify YuniKorn configmap "yunikorn-defaults" to allow ray operator based on k8s service account.
-```
-kubectl patch configmap yunikorn-defaults -n yunikorn --patch '{"data":{"admissionController.accessControl.systemUsers": "^system:serviceaccount:kube-system:,^system:serviceaccount:default:"}}' 
-```
+:::info[Note]
+This example demonstrates how to set up [KubeRay](https://docs.ray.io/en/master/cluster/kubernetes/getting-started.html) and run a [RayCluster](https://docs.ray.io/en/master/cluster/kubernetes/getting-started/raycluster-quick-start.html) with the YuniKorn scheduler. It relies on an admission controller to configure the default applicationId and queue name. If you want more details, please refer to [Yunikorn supported labels](https://yunikorn.apache.org/docs/user_guide/labels_and_annotations_in_yunikorn) and [Yunikorn queue setting](https://yunikorn.apache.org/docs/user_guide/queue_config).
+:::
 
-## Setup a KubeRay operator
-```
-helm repo add kuberay https://ray-project.github.io/kuberay-helm/
-helm repo update
-helm install kuberay-operator kuberay/kuberay-operator --version 1.1.1
-```
-- The result should be as shown below
-![ray_cluster_operator](../../assets/ray_cluster_operator.png)
+<YunikornConfigMapPatch />
+<RayOperator/>
 
-## Create Ray Cluster 
+## Create RayCluster 
 ```
 helm install raycluster kuberay/ray-cluster --version 1.1.1
 ```
-- Ray Cluster result
+- RayCluster result
   ![ray_cluster_cluster](../../assets/ray_cluster_cluster.png)
 - YuniKorn UI
   ![ray_cluster_on_ui](../../assets/ray_cluster_on_ui.png)
 
-### Configure your Ray Cluster(optional)
-If you disable admission controller, you need to add the schedulerName: yunikorn in [raycluster spec](https://github.com/ray-project/kuberay/blob/master/helm-chart/ray-cluster/templates/raycluster-cluster.yaml#L40). 
-```
-#example
-metadata:
-  labels:
-    applicaionId: ray-cluster-0001
-    queue: root.ray.clusters
-spec:
-  schedulerName: yunikorn # k8s will inform yunikorn based on this
-```
+<RayCRDYunikornConfig />
 
-## Submit a RayJob to Ray Cluster
+## Submit a RayJob to RayCluster
 ```
 export HEAD_POD=$(kubectl get pods --selector=ray.io/node-type=head -o custom-columns=POD:metadata.name --no-headers)
 echo $HEAD_POD

diff --git a/docs/user_guide/workloads/run_ray_job.md b/docs/user_guide/workloads/run_ray_job.md
@@ -6,6 +6,10 @@ keywords:
  - Ray_crd
 ---
 
+import RayOperator from './kuberay/_ray_operator.mdx';
+import RayCRDYunikornConfig from './kuberay/_ray_crd_yunikorn_config.mdx';
+import YunikornConfigMapPatch from './utils/_yunikorn_configmap_patch.mdx';
+
 <!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
@@ -25,33 +29,13 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-## Note
+:::info[Note]
 This example is how to setup [KubeRay](https://docs.ray.io/en/master/cluster/kubernetes/getting-started.html) and run [Ray Job](https://docs.ray.io/en/master/cluster/kubernetes/getting-started/rayjob-quick-start.html) with YuniKorn scheduler. It relies on an admission controller to configure the default applicationId and queue name. If you want more details, please refer to [Yunikorn supported labels](https://yunikorn.apache.org/docs/user_guide/labels_and_annotations_in_yunikorn) and [Yunikorn queue setting](https://yunikorn.apache.org/docs/user_guide/queue_config).
+:::
 
-## Modify YuniKorn settings
-Follow [YuniKorn install](https://yunikorn.apache.org/docs/) and modify YuniKorn configmap "yunikorn-defaults"
-```
-kubectl patch configmap yunikorn-defaults -n yunikorn --patch '{"data":{"admissionController.accessControl.systemUsers": "^system:serviceaccount:kube-system:,^system:serviceaccount:default:"}}' 
-```
-
-## Setup a KubeRay operator
-```
-helm repo add kuberay https://ray-project.github.io/kuberay-helm/
-helm repo update
-helm install kuberay-operator kuberay/kuberay-operator --version 1.1.1
-```
-
-### Configure your Ray Cluster(optional)
-If you disable admission controller, you need to add the schedulerName: yunikorn in [raycluster spec](https://github.com/ray-project/kuberay/blob/master/helm-chart/ray-cluster/templates/raycluster-cluster.yaml#L40). By using applicationId label, pods with the same applicationId are marked under the same application .
-```
-#example
-metadata:
-  labels:
-    applicaionId: ray-cluster-0001
-    queue: root.ray.clusters
-spec:
-  schedulerName: yunikorn # k8s will inform yunikorn based on this
-```
+<YunikornConfigMapPatch />
+<RayOperator/>
+<RayCRDYunikornConfig />
 
 ## Run a RayJob
 ```

diff --git a/docs/user_guide/workloads/run_ray_service.md b/docs/user_guide/workloads/run_ray_service.md
@@ -0,0 +1,71 @@
+---
+id: run_ray_service
+title: Run RayService
+description: How to run RayService jobs with YuniKorn
+keywords:
+ - Ray_crd
+---
+
+import RayOperator from './kuberay/_ray_operator.mdx';
+import RayCRDYunikornConfig from './kuberay/_ray_crd_yunikorn_config.mdx';
+import YunikornConfigMapPatch from './utils/_yunikorn_configmap_patch.mdx';
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+:::info[Note]
+This example demonstrates how to set up [KubeRay](https://docs.ray.io/en/master/cluster/kubernetes/getting-started.html) and run a [RayService](https://docs.ray.io/en/master/cluster/kubernetes/getting-started/rayservice-quick-start.html) with the YuniKorn scheduler. It relies on an admission controller to configure the default applicationId and queue name. If you want more details, please refer to [Yunikorn supported labels](https://yunikorn.apache.org/docs/user_guide/labels_and_annotations_in_yunikorn) and [Yunikorn queue setting](https://yunikorn.apache.org/docs/user_guide/queue_config).
+:::
+
+<YunikornConfigMapPatch />
+<RayOperator/>
+<RayCRDYunikornConfig />
+
+## Run a RayService
+```
+kubectl apply -f https://raw.githubusercontent.com/ray-project/kuberay/v1.1.1/ray-operator/config/samples/ray-service.sample.yaml
+```
+
+- RayService result
+  ![ray_service_pod](../../assets/run-ray-service-kuberay-service-pod.png)
+- YuniKorn UI
+  ![ray_service_on_ui](../../assets/run-ray-service-yunikorn-ui.png)
+
+## Verify the status of the Ray Serve applications
+
+Services in Kubernetes aren't directly accessible by default. However, you can use port-forwarding to connect to them locally.
+```
+kubectl port-forward svc/rayservice-sample-head-svc 8265:8265
+```
+After port-forward set up, you can access serve page in Ray dashboard by going to `http://localhost:8265/#/serve` in your web browser.
+
+![kuberay-dashboard-ui](../../assets/run-ray-service-kuberay-dashboard-ui.png)
+
+## Send requests to the RayService for testing
+
+```
+kubectl run curl --image=radial/busyboxplus:curl -i --tty
+
+curl -X POST -H 'Content-Type: application/json' rayservice-sample-serve-svc:8000/fruit/ -d '["MANGO", 2]'
+
+curl -X POST -H 'Content-Type: application/json' rayservice-sample-serve-svc:8000/calc/ -d '["MUL", 3]'
+```
+
+Example:
+![kuberay-service-api-testing](../../assets/run-ray-service-kuberay-service-api-testing.png)
diff --git a/docs/user_guide/workloads/utils/_yunikorn_configmap_patch.mdx b/docs/user_guide/workloads/utils/_yunikorn_configmap_patch.mdx
@@ -0,0 +1,5 @@
+## Modify YuniKorn settings
+Follow [YuniKorn install guide](https://yunikorn.apache.org/docs/) and modify YuniKorn configmap "yunikorn-defaults" to allow ray operator based on k8s service account.
+```
+kubectl patch configmap yunikorn-defaults -n yunikorn --patch '{"data":{"admissionController.accessControl.systemUsers": "^system:serviceaccount:kube-system:,^system:serviceaccount:default:"}}' 
+```
diff --git a/docs/user_guide/workloads/workload_overview.md b/docs/user_guide/workloads/workload_overview.md
@@ -60,3 +60,4 @@ Examples of more advanced use cases can be found here:
 * [Run MPI Jobs](run_mpi)
 * [Run Ray Cluster](run_ray_cluster)
 * [Run RayJob](run_ray_job)
+* [Run Ray Service Jobs](run_ray_service)
diff --git a/sidebars.js b/sidebars.js
@@ -48,7 +48,8 @@ module.exports = {
                     'user_guide/workloads/run_tf',
                     'user_guide/workloads/run_mpi',
                     'user_guide/workloads/run_ray_cluster',
-                    'user_guide/workloads/run_ray_job'
+                    'user_guide/workloads/run_ray_job',
+                    'user_guide/workloads/run_ray_service',
                 ],
             },
             {