[docs][KubeRay] Redirect the Ray docs on Kubernetes deployment to the up-to-date KubeRay docs

[kevin85421]

Description

Currently, we maintain KubeRay documents in both the KubeRay repository and the Ray repository. However, Ray docs on https://docs.ray.io/en/latest/ are only updated with new Ray releases. To summarize, users may access three different versions documents of KubeRay.

1. Docs on KubeRay repo (https://github.com/ray-project/kuberay)
2. Docs on Ray repo (https://github.com/ray-project/ray/tree/master/doc/source/cluster/kubernetes)
3. Docs on https://docs.ray.io/en/latest/

I take some bugs caused by the time difference between the three document sources as examples.

• Example 1: [Feature] Make head serviceType optional kuberay#851 (comment)

  • A user deploys KubeRay operator 0.3.0 via (3) and tries the examples on (1).

• Example 2: A user deploys KubeRay operator 0.3.0 via (3) and tries [autoscaler] Expose autoscaler container security context. kuberay#752 which starts to be supported by 0.4.0.

[Proposed solution]:

• Redirect users from (2) and (3) to (1). Hence, we only need to maintain one version of KubeRay documents.

Link

No response

[kevin85421]

Any thoughts? Thanks! cc. @DmitriGekhtman @architkulkarni @Jeffwan

[kevin85421]

cc @jiwq

[pcmoritz]

Our philosophy here has been to make sure the Ray docs have full information for users to use Kuberay, and everything there should be consistent with current stable release of Kuberay that is referred to from the Ray docs. A Kuberay user should never have go to the Kuberay docs.

This is to make sure we can have the same standard for using Kuberay as we have for the rest of the Ray documentation and a consistent experience.

The Kuberay docs are for more advanced developer information / technical documentation. Users of Kuberay should not need it.

It is possible that there is a better philosophy here going forward / this can be improved, I just want to point out why things are organized the way they are :)

[mihajenko]

We are Ray users, but we have to visit the kuberay docs, because we do not use RayServices CRD.

I don't know how many kuberay users there are like us, but just the migration from ray 1.x.x to 2.x.x has been a bit confusing due to discrepancies between the different versions of kuberay docs. It was hard to estimate how much time it would take to migrate.

[pcmoritz]

@mihajenko I'm curious why the Ray docs didn't work for you / what it has to do with RayServices CRD? I could understand it if you needed that feature, since I think currently it is not documented in the Ray docs (once it stabilizes it probably should).

I also wanted to point out that in order for the above philosophy to work, we need to make sure that the Ray docs really only refer to the latest stable KubeRay release -- e.g. at the moment there are references to kubectl apply -f https://raw.githubusercontent.com/ray-project/kuberay/master/ray-operator/config/samples/ray-cluster.autoscaler.yaml in the docs, which won't work. One possible improvement is to fix these kinds of problems :)

[pcmoritz]

(just for clarity, the Ray docs I'm referring to are https://docs.ray.io/en/latest/cluster/kubernetes/index.html)

[mihajenko]

@pcmoritz RayService is documented as the prefered resource in the Ray Serve section of the Ray docs. We had to do some discovery to realize we can ignore that part of the documentation.

[kevin85421]

Our philosophy here has been to make sure the Ray docs have full information for users to use Kuberay, and everything there should be consistent with current stable release of Kuberay that is referred to from the Ray docs. A Kuberay user should never have go to the Kuberay docs.

@pcmoritz This philosophy can make sure every example in (3) works. However, as I mentioned in Example 1 and Example 2, some users deploy the KubeRay operator via (3) and want to explore other features in (1) and (2).

Note:

• Example 1 is only supported in the nightly version of KubeRay.
• Example 2 has been supported since KubeRay 0.4.0.

Is there any method to avoid these examples?

[architkulkarni]

If we want to maintain the existing philosophy, one way to avoid those examples is the following: In the Kuberay docs, add disclaimers like "this example is supported from Kuberay 0.4.0 on; please ensure your KubeRay operator was deployed with version >0.4.0". (For nightly, we can write 0.5.0.) This is similar to what we do for new Ray features.

The downside is this could be verbose, and we'd need to manually enforce adding these disclaimers for every new feature/example which could be hard.

[DmitriGekhtman]

Documenting version requirements is important.

We should explain that the RayService feature is recommended but not required to run Ray Serve on Kubernetes.

Philipp's suggestion of placing the most basic and important bits in the Ray docs and more advanced stuff in the KubeRay docs makes sense.

We could also consider versioning the KubeRay docs.

[DmitriGekhtman]

Other points we discussed --

• We should backport the Kubernetes section in the master Ray docs to the Ray 2.2.0 docs.
• To avoid having to do this in the future, we should sync each KubeRay release with a Ray release.

[gvspraveen]

We should backport the Kubernetes section in the master Ray docs to the Ray 2.2.0 docs.
@DmitriGekhtman In that case should we also be syncing docs on KubeRay repo with docs on Ray repo master?

[DmitriGekhtman]

@DmitriGekhtman In that case should we also be syncing docs on KubeRay repo with docs on Ray repo master?

Broadly, yep, we need to keep the two doc pages consistent. (Literally unifying the two doc sites would be harder.)

It could help to version the KubeRay docs, so that people see the latest KubeRay release's docs by default. This would be consistent with our handling of the Ray docs. (Currently the KubeRay doc page is built from the KubeRay master branch.)