Setting Up KubeRay on Crusoe Managed Kubernetes

Last Updated: Dec 01, 2025

Overview

KubeRay is an open-source Kubernetes operator that simplifies deploying, managing, and scaling Ray clusters on Kubernetes. It automates cluster lifecycle tasks, making it easy to run distributed AI and machine learning workloads in the cloud.

This article guides you through installing the KubeRay operator on a Crusoe Managed Kubernetes (CMK) cluster, configuring a port forward to access the Ray dashboard, and submitting your first Ray job using the Crusoe CLI. 

Pre-requirements 

• Crusoe Cloud Account with CMK cluster configured 

• High level understanding of Kubernetes architecture

• kubectl installed with default config at ~/.kube/config

• Familiarity with Training frameworks such as Pytorch or TensorFlow

• Helm installed (>= v3.4)

Set up KubeRay on CMK

Follow Ray Documentation to set up a KubeRay Cluster. 

1. Deploy KubeRay Operator

   • Add and update KubeRay Helm repository

     $ helm repo add kuberay https://ray-project.github.io/kuberay-helm/
     $ helm repo update

   • Install both CRDs and KubeRay operator. The following installation was tested with --version 1.5.1. Remove --version for installing the latest version. See official docs for latest versions. 

     $ helm install kuberay-operator kuberay/kuberay-operator --version 1.5.1
     
     NAME: kuberay-operator
     LAST DEPLOYED: Sat Dec 20 17:55:23 2025
     NAMESPACE: default
     STATUS: deployed
     REVISION: 1
     TEST SUITE: None 

     Note: This installs the latest version of the operator in the default namespace.

2. Validate Installation. 
   You should see the kuberay-operator pod running in the default namespace. 

   $ kubectl get pods 
   
   NAME                               READY   STATUS    RESTARTS  AGE 
   kuberay-operator-5c7f84f8bc-xh88n   1/1    Running   0         34s

3. Deploy Ray Cluster Custom Resource (CR)
   Once the KubeRay operator is running, you’re ready to deploy a RayCluster.

   • Install the version of RayCluster Custom Resource (CR) in the default namespace. Remove --version for installing the latest version. 

     $ helm install raycluster kuberay/ray-cluster --version 1.5.1
              
     NAME: raycluster
     LAST DEPLOYED: Sat Dec 20 17:56:09 2025
     NAMESPACE: default
     STATUS: deployed
     REVISION: 1
     TEST SUITE: None

   • Verify Installation with kubectl. You should see the Ray Cluster CR available:

     $ kubectl get raycluster
     
     NAME                 DESIRED WORKERS   AVAILABLE WORKERS   CPUS   MEMORY   GPUS   STATUS   AGE
     raycluster-kuberay   1                                     2      3G       0               11s

4. See the active kuberay service

   $ kubectl get services
   
   NAME                                                TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                                         AGE
   kuberay-operator                                    ClusterIP   10.233.42.231   <none>        8080/TCP                                        14d
   kubernetes                                          ClusterIP   10.233.0.1      <none>        443/TCP                                         20d
   raycluster-kuberay-head-svc                         ClusterIP   None            <none>        10001/TCP,8265/TCP,6379/TCP,8080/TCP,8000/TCP   14d

5. Use a local port forward to connect to the Ray dashboard at the default port 8265

   $ kubectl port-forward service/raycluster-kuberay-head-svc 8265:8265
   
   Forwarding from 127.0.0.1:8265 -> 8265
   Forwarding from [::1]:8265 -> 8265
   Handling connection for 8265

   • Open a browser and go to 127.0.0.1:8265

6. Setup Ray CLI locally and export RAY_ADDRESS

   $ pip install "ray[default]" 
   $ export RAY_ADDRESS="http://localhost:8265"

7. Submit a sample job to the cluster to validate connection
   Use the Ray job submission SDK to submit Ray jobs to the RayCluster through the Ray Dashboard port where Ray listens for Job requests. The KubeRay operator configures a Kubernetes service targeting the Ray head Pod.

   # ray job submit --address http://localhost:8265 -- python -c "import pprint; import ray; ray.init(); pprint.pprint(ray.cluster_resources(), sort_dicts=True)"
   
   Job submission server address: http://localhost:8265
   
   -------------------------------------------------------
   Job 'raysubmit_DrAVaWLqDZTV5CCH' submitted successfully
   -------------------------------------------------------
   
   Next steps
     Query the logs of the job:
       ray job logs raysubmit_DrAVaWLqDZTV5CCH
     Query the status of the job:
       ray job status raysubmit_DrAVaWLqDZTV5CCH
     Request the job to be stopped:
       ray job stop raysubmit_DrAVaWLqDZTV5CCH
   
   Tailing logs until the job exits (disable with --no-wait):
   2025-12-20 18:01:44,290	INFO job_manager.py:531 -- Runtime env is setting up.
   2025-12-20 18:01:45,449	INFO worker.py:1554 -- Using address 10.234.2.211:6379 set in the environment variable RAY_ADDRESS
   2025-12-20 18:01:45,449	INFO worker.py:1694 -- Connecting to existing Ray cluster at address: 10.234.2.211:6379...
   2025-12-20 18:01:45,460	INFO worker.py:1879 -- Connected to Ray cluster. View the dashboard at 10.234.2.211:8265
   {'CPU': 2.0,
    'memory': 3000000000.0,
    'node:10.234.0.23': 1.0,
    'node:10.234.2.211': 1.0,
    'node:__internal_head__': 1.0,
    'object_store_memory': 511097240.0}
   
   ------------------------------------------
   Job 'raysubmit_DrAVaWLqDZTV5CCH' succeeded
   ------------------------------------------

Congratulations! You are now set up and ready to get started with submitting Ray jobs to your CMK cluster on Crusoe Cloud. 

Additional Resources

• Ray on Kubernetes
• RayCluster Quick Start
• Observability in CMK Cluster