Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ray-preview.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

A Ray cluster is a head node plus a set of worker nodes connected to it. The same Ray applications run unchanged on a single laptop, a few VMs, or a fleet of Kubernetes pods — only the cluster setup differs.

​
Pick your environment

Kubernetes (KubeRay)

Production deployment via the KubeRay operator. RayCluster, RayJob, and RayService CRDs.

VMs

Run on AWS, GCP, Azure, or on-premises VMs with the Ray cluster launcher.

​
Local cluster (development)

ray start --head --port=6379
ray start --address=<head-ip>:6379       # on each worker

import ray
ray.init(address="auto")
print(ray.cluster_resources())

​
Architecture

A Ray cluster consists of:
  • Head node: hosts the Global Control Service (GCS), the cluster autoscaler, the dashboard, and (optionally) a worker.
  • Worker nodes: run user tasks and actors. Each node hosts a raylet, a number of Python workers, and a slice of the object store.
  • Driver: the Python process that runs your ray.init() code. Drivers can run on the head node, on a worker, or anywhere with network access to the cluster.

​
Submit work to a cluster

MechanismUse case
ray.init(address="auto") from a script on the headQuick interactive use.
Ray Jobs APIRecommended for batch jobs. Submit code from a client, get logs and status back.
Ray ClientConnect a remote driver to the cluster. Best for interactive notebooks.
RayJob (Kubernetes)Run a job as a Kubernetes resource.
Learn more about Ray Jobs.

​
Autoscaling

Ray clusters can autoscale — adding worker nodes when the workload demands more resources, and removing idle nodes after a configurable timeout. Autoscaling is supported on KubeRay and the VM cluster launcher.

​
Next steps

Key concepts

Head and worker nodes, GCS, raylet, autoscaler.

Kubernetes quickstart

Run a RayCluster on Kubernetes in minutes.