[doc][KubeRay] document ingressOptions for the built-in Ingress - #65483
Open
wuallen57730 wants to merge 3 commits into
Open
[doc][KubeRay] document ingressOptions for the built-in Ingress#65483wuallen57730 wants to merge 3 commits into
wuallen57730 wants to merge 3 commits into
Conversation
Signed-off-by: wuallen57730 <yuwu11926@gmail.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request adds documentation for the KubeRay built-in Ingress feature, including prerequisites, a sample RayCluster manifest, and configuration options. The review feedback suggests restoring a blank line before a list to prevent Markdown rendering issues, and updating the Ray version and image tags in the sample manifest from the non-existent version '2.52.0' to a valid version like '2.30.0' to avoid image pull failures.
ray-gardener
Bot
added
docs
Signed-off-by: wuallen57730 <yuwu11926@gmail.com>
win5923
self-requested a review
August 14, 2026 19:04
win5923
reviewed
Aug 16, 2026
Comment on lines
+33
to
+35
| * An Ingress controller running in your cluster, for example the [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/). See [Manually setting up NGINX Ingress on Kind](kuberay-nginx) for a Kind-based setup. | ||
|
|
||
| * KubeRay 1.7 or later. |
Member
There was a problem hiding this comment.
Suggested change
| * An Ingress controller running in your cluster, for example the [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/). See [Manually setting up NGINX Ingress on Kind](kuberay-nginx) for a Kind-based setup. | |
| * KubeRay 1.7 or later. | |
| - KubeRay operator v1.7 or later installed. | |
| - An Ingress controller running in your cluster. See the [Kubernetes Ingress Controllers documentation](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) for more information. | |
Comment on lines
+41
to
+51
| ```yaml | ||
| apiVersion: ray.io/v1 | ||
| kind: RayCluster | ||
| metadata: | ||
| name: raycluster-ingress | ||
| annotations: | ||
| # KubeRay sets `spec.ingressClassName` on the generated Ingress from this annotation, and | ||
| # copies every other RayCluster annotation to the Ingress unchanged. | ||
| kubernetes.io/ingress.class: nginx | ||
| spec: | ||
| rayVersion: "2.52.0" # should match the Ray version in the image of the containers |
Member
There was a problem hiding this comment.
You don't need to include the entire RayCluster YAML here. We can just say that users need to set enableIngress to true and add ingressOptions to headGroupSpec, then show the relevant snippet:
### Configure `ingressOptions`
Set `enableIngress` to `true` and add `ingressOptions` to `headGroupSpec`:
```
apiVersion: ray.io/v1
kind: RayCluster
metadata:
name: raycluster-ingress
annotations:
kubernetes.io/ingress.class: nginx
spec:
headGroupSpec:
enableIngress: true
ingressOptions:
host: ray-dashboard.example.com
path: /
pathType: Prefix
tls:
- hosts:
- ray-dashboard.example.com
secretName: ray-dashboard-tls
```
The operator generates an Ingress named `<raycluster-name>-head-ingress` that routes to the head service on the dashboard port.
Comment on lines
+84
to
+105
| ``` | ||
| Now run the following commands: | ||
|
|
||
| ```bash | ||
| # Step 1: Install KubeRay operator and CRD | ||
| helm repo add kuberay https://ray-project.github.io/kuberay-helm/ | ||
| helm repo update | ||
| helm install kuberay-operator kuberay/kuberay-operator --version 1.7.0 | ||
|
|
||
| # Step 2: Create the RayCluster. KubeRay creates an Ingress named | ||
| # `<raycluster-name>-head-ingress` that points at the dashboard port of the head | ||
| # service, which is 8265 by default. | ||
| kubectl apply -f ray-cluster-builtin-ingress.yaml | ||
|
|
||
| # Step 3: Check the ingress created in Step 2. | ||
| kubectl describe ingress raycluster-ingress-head-ingress | ||
|
|
||
| # Step 4: Check the Ray Dashboard at the host you configured in `ingressOptions.host`. | ||
|
|
||
| # Step 5: Delete the RayCluster. KubeRay deletes the generated Ingress along with it. | ||
| kubectl delete -f ray-cluster-builtin-ingress.yaml | ||
| ``` |
Comment on lines
+118
to
+120
| ```{note} | ||
| KubeRay only manages the Ingress it creates. It doesn't modify an Ingress that it doesn't own, even if the name matches. On OpenShift, KubeRay creates a Route instead of an Ingress, and `ingressOptions` doesn't apply. | ||
| ``` |
win5923
reviewed
Aug 16, 2026
| (kuberay-builtin-ingress)= | ||
| ## KubeRay built-in Ingress | ||
|
|
||
| Instead of writing an Ingress manifest yourself, you can let KubeRay create and manage the Ingress for the Ray head service. Set `enableIngress` to `true` in `headGroupSpec`, and customize the generated Ingress with `ingressOptions`. KubeRay 1.7.0 and later support `ingressOptions`. |
Member
There was a problem hiding this comment.
Suggested change
| Instead of writing an Ingress manifest yourself, you can let KubeRay create and manage the Ingress for the Ray head service. Set `enableIngress` to `true` in `headGroupSpec`, and customize the generated Ingress with `ingressOptions`. KubeRay 1.7.0 and later support `ingressOptions`. | |
| KubeRay 1.7.0 adds `ingressOptions`, which lets the operator generate and manage an Ingress for the Ray head service. You can configure the Ingress directly in the RayCluster using `ingressOptions`. The operator creates the corresponding Ingress, updates it when the configuration changes, and deletes it when the RayCluster is deleted. |
Signed-off-by: wuallen57730 <yuwu11926@gmail.com>
Author
|
Thanks for the detailed review @win5923, applied all of it! |
win5923
approved these changes
Aug 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
KubeRay 1.7 added
ingressOptionsonheadGroupSpec(ray-project/kuberay#4901), which lets theoperator generate the head-service Ingress with a custom host, path, path type, and TLS
configuration. The feature landed without documentation, and this page currently only covers
writing Ingress and Gateway manifests by hand.
This adds a "KubeRay built-in Ingress" section covering
enableIngress, theingressOptionsfields and their defaults, and the fact that the ingress class comes from the
kubernetes.io/ingress.classannotation on the RayCluster rather than fromingressOptions.Related issues
Closes ray-project/kuberay#5127
Additional information
ingressOptionsisn't in KubeRay v1.6.0, and v1.7.0 isn't tagged yet (latest release isv1.6.2), so the helm command pins
1.7.0on the assumption this doc lands with the 1.7.0release. Happy to change the pin if you'd prefer otherwise.