[cherry-pick][2.58.0][docs] Backport KubeRay v1.7 feature docs

doc/source/cluster/kubernetes/getting-started/kuberay-operator-installation.md

@@ -14,26 +14,29 @@ kind create cluster --image=kindest/node:v1.26.0
 
 ### Method 1: Helm (Recommended)
 
+Install the operator into a dedicated `ray-system` namespace rather than `default` to isolate the operator's service account from workload pods.
+
 ```sh
 helm repo add kuberay https://ray-project.github.io/kuberay-helm/
 helm repo update
-# Install both CRDs and KubeRay operator v1.6.0.
-helm install kuberay-operator kuberay/kuberay-operator --version 1.6.0
+kubectl create namespace ray-system
+helm install kuberay-operator kuberay/kuberay-operator --version 1.6.0 -n ray-system
 ```
 
 ### Method 2: Kustomize
 
 ```sh
-# Install CRD and KubeRay operator.
-kubectl create -k "github.com/ray-project/kuberay/ray-operator/config/default?ref=v1.6.0"
+# Install CRD and KubeRay operator into the ray-system namespace.
+kubectl create namespace ray-system
+kubectl create -k "github.com/ray-project/kuberay/ray-operator/config/default?ref=v1.6.0" -n ray-system
 ```
 
 ## Step 3: Validate Installation
 
-Confirm that the operator is running in the namespace `default`.
+Confirm that the operator is running. If you installed into `ray-system`, pass `-n ray-system`:
 
 ```sh
-kubectl get pods
+kubectl get pods -n ray-system
 ```
 
 ```text

doc/source/cluster/kubernetes/getting-started/rayjob-quick-start.md

@@ -53,14 +53,15 @@ To understand the following content better, you should understand the difference
     * `K8sJobMode`: The KubeRay operator creates a submitter Kubernetes Job to submit the Ray job.
     * `HTTPMode`: The KubeRay operator sends a request to the RayCluster to create a Ray job.
     * `InteractiveMode`: The KubeRay operator waits for the user to submit a job to the RayCluster. This mode is currently in alpha and the [KubeRay kubectl plugin](kubectl-plugin) relies on it.
-    * `SidecarMode`: The KubeRay operator injects a container into the Ray head Pod to submit the Ray job. This mode does not support `clusterSelector`, `submitterPodTemplate`, and `submitterConfig`, and requires the head Pod's restart policy to be `Never`.
+    * `SidecarMode`: The KubeRay operator injects a container into the Ray head Pod to submit the Ray job. This mode does not support `clusterSelector` and `submitterPodTemplate`, and requires the head Pod's restart policy to be `Never`. When the `SidecarSubmitterRestart` feature gate is enabled **(requires KubeRay v1.7+, Ray v2.54.0+, and Kubernetes v1.35+)**, `submitterConfig.backoffLimit` is used to cap the submitter sidecar's restart count.
   * `submitterPodTemplate` (Optional): Defines the Pod template for the submitter Kubernetes Job. This field is only effective when `submissionMode` is "K8sJobMode".
     * `RAY_DASHBOARD_ADDRESS` - The KubeRay operator injects this environment variable to the submitter Pod. The value is `$HEAD_SERVICE:$DASHBOARD_PORT`.
     * `RAY_JOB_SUBMISSION_ID` - The KubeRay operator injects this environment variable to the submitter Pod. The value is the `RayJob.Status.JobId` of the RayJob.
     * Example: `ray job submit --address=http://$RAY_DASHBOARD_ADDRESS --submission-id=$RAY_JOB_SUBMISSION_ID ...`
     * See [ray-job.sample.yaml](https://github.com/ray-project/kuberay/blob/master/ray-operator/config/samples/ray-job.sample.yaml) for more details.
-  * `submitterConfig` (Optional): Additional configurations for the submitter Kubernetes Job.
-    * `backoffLimit` (Optional, added in version 1.2.0): The number of retries before marking the submitter Job as failed. The default value is 2.
+  * `submitterConfig` (Optional): Additional configurations for the submitter. Used in `K8sJobMode` (always). `SidecarMode` also honors `backoffLimit` internally when `SidecarSubmitterRestart` is enabled, but the field currently can't be set via the RayJob custom resource for `SidecarMode`. See {ref}`kuberay-rayjob-sidecar-submitter-restart`.
+    * `backoffLimit` (Optional, added in version 1.2.0): The number of retries before marking the submitter as failed. The default value is 2.
+  * `SidecarSubmitterRestart` (alpha in v1.7, disabled by default): Lets the submitter container restart in place on transient failures, independent of the head Pod's pod-level `restartPolicy: Never`. Requires Kubernetes v1.35+ and Ray v2.54.0+. See {ref}`kuberay-rayjob-sidecar-submitter-restart` for the full walkthrough, restart/reattach behavior, and version-skew caveats.
 * Automatic resource cleanup
   * `preRunningDeadlineSeconds` (Optional): If the RayJob doesn't transition the `JobDeploymentStatus` to `Running` within `preRunningDeadlineSeconds` seconds, the KubeRay operator transitions the `JobDeploymentStatus` to `Failed` with reason `PreRunningDeadlineExceeded`. The default value is 0 (no pre-running deadline is enforced).
   * `shutdownAfterJobFinishes` (Optional): Determines whether to recycle the RayCluster after the Ray job finishes. The default value is false.

doc/source/cluster/kubernetes/k8s-ecosystem/ingress.md

@@ -4,6 +4,7 @@
 
 The following examples show how to use Ingress or Gateway to access your Ray clusters:
 
+  * [KubeRay built-in Ingress](kuberay-builtin-ingress)
   * [AWS Application Load Balancer (ALB) Ingress support on AWS EKS](kuberay-aws-alb)
   * [GKE Ingress support](kuberay-gke-ingress)
   * [GKE Gateway API support](kuberay-gke-gateway)
@@ -16,6 +17,53 @@ The following examples show how to use Ingress or Gateway to access your Ray clu
 **Only expose Ingresses or Gateways to authorized users.** The Ray Dashboard provides read and write access to the Ray Cluster. Anyone with access to this Ingress or Gateway can execute arbitrary code on the Ray Cluster.
 ```
 
+(kuberay-builtin-ingress)=
+## KubeRay built-in Ingress
+
+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.
+
+### Prerequisites
+
+- 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.
+
+### Configure `ingressOptions`
+
+Set `enableIngress` to `true` and add `ingressOptions` to `headGroupSpec`:
+
+```yaml
+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.
+
+Every field under `ingressOptions` is optional:
+
+| Field      | Description                                                                                                                                                                         | Default                         |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `host`     | Fully qualified domain name that routes external traffic to the Ray head dashboard.                                                                                                 | Unset, which matches any host.  |
+| `path`     | HTTP path that routes to the dashboard.                                                                                                                                             | `/`                             |
+| `pathType` | Path matching mode for `path`. One of `Exact`, `Prefix`, or `ImplementationSpecific`.                                                                                               | `Prefix`                        |
+| `tls`      | TLS termination for the generated Ingress, using the Kubernetes [IngressTLS](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/ingress-v1/#IngressSpec) schema. | Unset, which serves plain HTTP. |
+
+If you set only `enableIngress: true`, KubeRay generates an Ingress that matches any host and routes `/` to the dashboard. If you update `ingressOptions` on an existing RayCluster, KubeRay updates the generated Ingress to match.
 
 (kuberay-aws-alb)=
 ## AWS Application Load Balancer (ALB) Ingress support on AWS EKS

doc/source/cluster/kubernetes/user-guides.md

@@ -29,6 +29,7 @@ user-guides/tpu
 user-guides/pod-command
 user-guides/helm-chart-rbac
 user-guides/tls
+user-guides/network-policy
 user-guides/k8s-autoscaler
 user-guides/kubectl-plugin
 user-guides/kuberay-auth
@@ -39,6 +40,7 @@ user-guides/kuberay-dashboard
 user-guides/resource-isolation-with-writable-cgroups
 user-guides/kuberay-history-server
 user-guides/k8s-events
+user-guides/rayjob-sidecar-submitter-restart
 ```
 
 
@@ -67,6 +69,7 @@ To learn the basics of Ray on Kubernetes, we recommend taking a look at the {ref
 * {ref}`kuberay-pod-command`
 * {ref}`kuberay-helm-chart-rbac`
 * {ref}`kuberay-tls`
+* {ref}`kuberay-network-policy`
 * {ref}`kuberay-gke-bucket`
 * {ref}`ray-k8s-autoscaler-comparison`
 * {ref}`kubectl-plugin`
@@ -78,3 +81,4 @@ To learn the basics of Ray on Kubernetes, we recommend taking a look at the {ref
 * {ref}`resource-isolation-with-writable-cgroups`
 * {ref}`kuberay-history-server`
 * {ref}`kuberay-k8s-events`
+* {ref}`kuberay-rayjob-sidecar-submitter-restart`

doc/source/cluster/kubernetes/user-guides/k8s-events.md

@@ -13,7 +13,7 @@ This guide describes how to enable and use platform events in the Ray Dashboard
 ## Prerequisites
 
 * **Ray version**: Ray 2.56.0 or later.
-* **Kubernetes Python client**: Install the `kubernetes` Python package in the Ray head pod's Python environment. The official `rayproject/ray` images include it. Add it to custom images.
+* **Kubernetes Python client**: Install the `kubernetes` Python package (`pip install kubernetes`) in the Ray head pod's Python environment. The official `rayproject/ray` images don't include it.
 * **Kubernetes cluster**: A Kubernetes cluster where you can deploy Ray workloads.
 
 ## Configure RBAC permissions

doc/source/cluster/kubernetes/user-guides/kuberay-gcs-rocksdb-ft.md

@@ -30,11 +30,8 @@ For the officially supported, Redis-backed setup, see
 
 ## Prerequisites
 
-* A KubeRay version with embedded RocksDB support. This backend is only on KubeRay master
-  (nightly) at the time of writing; it isn't in a stable KubeRay release yet. Once a release
-  ships with it, use that version.
-* A Ray image that contains the embedded RocksDB backend. It isn't in a stable Ray release
-  yet, so the manifest below uses `rayproject/ray:nightly`.
+* KubeRay v1.7 or later, which is the first release that supports the embedded RocksDB backend.
+* Ray 2.57.0 or later, which is the first release that contains the embedded RocksDB backend.
 * Linux worker nodes (the RocksDB backend is Linux only).
 * A `StorageClass` that provisions a durable volume which can reattach to the node that runs
   the recovered head Pod.
@@ -114,7 +111,7 @@ spec:
       spec:
         containers:
         - name: ray-head
-          image: rayproject/ray:nightly
+          image: rayproject/ray:2.57.0
   workerGroupSpecs:
   - groupName: small-group
     replicas: 1
@@ -125,7 +122,7 @@ spec:
       spec:
         containers:
         - name: ray-worker
-          image: rayproject/ray:nightly
+          image: rayproject/ray:2.57.0
 ```
 
 ```{admonition} Storage options