KubeRay splits Ray across three CRDs with three different jobs to do

RayJob owns a cluster it can delete, RayService owns a deployment graph

The core is three custom resource definitions, and they do not overlap in what they manage. RayCluster is the one the operator drives directly: creation and deletion, autoscaling, and fault tolerance are all described as fully managed lifecycle work. Nothing above it decides when the cluster should exist.

RayJob sits above that and takes the timing decision away. It creates a RayCluster and submits a job once the cluster is ready, and it can be configured to delete the RayCluster again when the job finishes, so a batch workload leaves nothing behind. RayService is the long-running shape: a RayCluster plus a Ray Serve deployment graph, offering zero-downtime upgrades for the cluster and high availability. Choosing between them is mostly a question of whether the workload has an end.

Plugin Beta, API server Alpha, dashboard not production-ready

The optional parts of the ecosystem carry three different labels and they are not interchangeable. The kubectl plugin has been Beta since KubeRay v1.3.0 and provides the kubectl ray command, aimed squarely at people who are not already familiar with Kubernetes, since the framing is that the plugin simplifies running Ray there rather than requiring the manifests to be written by hand.

The KubeRay APIServer is Alpha and provides a layer of simplified configuration for KubeRay resources. Its stated purpose is narrow: some organizations use it internally to back user interfaces for resource management, which is a description of a private control plane rather than a general client.

The KubeRay Dashboard arrived in v1.4.0 and is marked Experimental, for viewing and managing KubeRay resources. It is the only one of the three the README rules out of production outright, saying it is not yet production-ready while still asking for feedback.

User documentation left the repository in September 2023

From September 2023 all user-facing KubeRay documentation is hosted on the Ray documentation site, and the repository is left with documentation about the development and maintenance of KubeRay itself. The README is mostly links out as a result: the three quickstart links for RayCluster, RayJob and RayService point at docs.ray.io, and the examples section says examples are hosted there too, covering training, LLM online inference and batch inference.

What remains in the tree is developer-facing. mkdocs.yml and a docs/ directory are still here, along with kuberay.code-workspace, and they cover working on the operator rather than running it. So the first thing an adopter needs is outside the repository, and the second thing they need, an example to copy, is also outside it.

The root go.mod requires the nested ray-operator module at v0.0.0

The dependency picture starts with an oddity. The root module is github.com/ray-project/kuberay, it declares go 1.26.0, and among its direct requirements it lists github.com/ray-project/kuberay/ray-operator v0.0.0, which is the repository's own nested module rather than an external dependency. The tree confirms the split: ray-operator/, kubectl-plugin/, apiserver/, apiserversdk/, dashboard/, podpool/, historyserver/, clients/ and proto/ are separate directories alongside a single go.mod and go.sum at the root.

The Kubernetes side is pinned tightly and uniformly: k8s.io/api, apimachinery, cli-runtime, client-go and kubectl are all at v0.37.0, with sigs.k8s.io/controller-runtime at v0.25.0 and klog at v2.140.0. Interface plumbing comes from grpc v1.82.1 with grpc-gateway v2.29.0 and go-grpc-prometheus v1.2.0. The indirect block is long, and it stops partway, on a line beginning github.com/chai2010/ge.

Four testing libraries ship together, one of them a release candidate

Testing is carried by four separate libraries rather than one. Onsi ginkgo/v2 at v2.32.0 and gomega at v1.40.0 are the pair a Kubernetes operator would normally reach for, stretchr/testify is there at v1.11.1, and github.com/golang/mock appears at v1.7.0-rc.1. That last one is a release candidate sitting in the direct requirement list, not a tagged stable version, which makes the mocking layer the least settled dependency in the file.

Other direct requirements hint at what the operator generates and reports with: golang-petname for random names, prometheus/client_golang v1.24.0 for metrics, zerolog with the logr bridge for logging, spf13/cobra and pflag for command lines, go-shlex for splitting argument strings, and pkg/errors alongside dustinkirkland's parser for container images. Several dependencies are pinned to commits rather than releases.

Three dependencies are pinned to untagged commits dated in 2026

The go.mod mixes tagged versions with pseudo-versions, and the pseudo-versions carry a timestamp in the string. google.golang.org/protobuf is written as v1.36.12-0.20260120151049-f2248ac996af, which pins it to a commit from 2026-01-20. Both genproto googleapis modules, api and rpc, sit at v0.0.0-20260526163538, dated 2026-05-26. k8s.io/utils is v0.0.0-20260626114624-be93311217bd, dated 2026-06-26. The same style appears on golang-petname and on github.com/google/shlex.

So a build of the operator is not reproducible from tagged releases alone, and the reason is not obvious from a version number: those entries mean somebody needed a fix or a feature that had not been cut as a release at the time the module was updated. The k8s libraries proper are all tagged, so this pattern is aimed at the supporting cast rather than at the framework.

The kubectl plugin ships through a krew index, not through the README

There is a .krew.yaml at the repository root, which is the manifest format for distributing kubectl plugins through krew, and kubectl-plugin/ is the directory holding the command the README refers to as kubectl ray. That pairing is how the Beta component reaches a cluster: through the krew plugin index, not through a binary named in the documentation.

The README does not spell the installation out. Its plugin paragraph links to the kubectl-plugin section of the Ray documentation site for details, which is the same pattern as the quickstart links: the repository names the component, the site carries the procedure. For the operator itself the tree offers install/, config/ and helm-chart/ at the root, and helm-chart is what the related search terms for this project keep pointing at, along with a dashboard term and an api server term matching the two Alpha and Experimental components.

Every talk in the README is from 2024, and the list ends mid-entry

The talks section is a wall of conference links: one from KubeCon 2024 NA and a long run of Ray Summit 2024 sessions from Anyscale, Google, Apple, Microsoft, AWS, Roblox, Airbnb, eBay, Spotify, Reddit and IBM. That is the entire dated material in the README, and it stops in 2024, well behind the releases. The blog list above it is a similar wall, and the entries carrying dates are DoorDash in June 2023 and Spotify in February 2023.

The last talk entry begins Exploring Hinge's ML Platform Evolution and stops there, with the link and speaker left off. Compare that with the release record: v1.7.1 on 2026-09-21, v1.7.0 on 2026-08-20 and v1.7.0-rc.0 on 2026-08-14, with the last push on 2026-10-02. The project is moving; its own list of conference appearances is not.

Editorial conclusion

KubeRay fits teams already running Kubernetes who want Ray's scheduling and autoscaling without hand-writing operator logic, and RayJob is the one to reach for when a job should bring its own cluster and take it away again. Before committing, check the maturity label of whichever component you want: the kubectl plugin has been Beta since v1.3.0, the API server is Alpha, and the dashboard has been Experimental since v1.4.0 and is called not production-ready in the project's own words. Read the operator's go.mod if you care about dependency pinning, since several entries are dated pseudo-versions rather than tagged releases. Releases are current: v1.7.1 shipped on 2026-09-21 and the last push was on 2026-10-02.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes