[KubeRay][Docs] Simplify KubeRay upgrade steps and always upgrade CRD…

…s first (ray-project#44826)

Simplifes the KubeRay upgrade steps and strongly recommends upgrading CRDs first. Also removes recommendation for deleting CRDs as this will result in RayCluster, RayJob and RayService resources being deleted.

Signed-off-by: Andrew Sy Kim <[email protected]>

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

@@ -26,54 +26,37 @@ If you want to understand the reasoning behind the CRD versioning plan, see [ray
 ## Upgrade KubeRay
 
 Upgrading the KubeRay version is the best strategy if you have any issues with KubeRay.
-
-* Because a lot of users are unable to install Kubernetes webhooks due to their security policies, KubeRay doesn't provide a webhook for the CRD upgrade.
-* If you plan to upgrade to KubeRay v1.0.0 or later, you may need to upgrade the `apiVersion` in your custom resource YAML files from `ray.io/v1alpha1` to `ray.io/v1`.
-* Based on [the Helm documentation](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations), there is no support at this time for upgrading or deleting CRDs using Helm.
-  * If you want to install the latest KubeRay release's CRD, you may need to delete the old CRD first.
-  * Note that deleting the CRD causes a cascading deletion of custom resources. See the [Helm documentation](https://github.com/helm/community/blob/main/hips/hip-0011.md#deleting-crds) for more details.
-  * Example 1: Upgrade KubeRay from v0.6.0 to v1.0.0 without deleting the old CRD.
-    ```shell
-    # Install KubeRay v0.6.0 and CRD v1alpha1
-    helm install kuberay-operator kuberay/kuberay-operator --version 0.6.0
-
-    # The following instruction uninstalls only KubeRay v0.6.0. It does not uninstall CRD v1alpha1.
-    helm uninstall kuberay-operator
-
-    # Install KubeRay v1.0.0. Because the CRD already exists, the Helm instruction does not install the new CRD.
-    helm install kuberay-operator kuberay/kuberay-operator --version 1.0.0
-
-    # Check CRD
-    kubectl describe crd rayclusters.ray.io | grep v1
-    # You can only see "Name: v1alpha1", and cannot see "Name: v1".
-
-    # Install RayCluster v1.0.0 which uses CRD v1.
-    helm install raycluster kuberay/ray-cluster --version 1.0.0
-    # Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest:
-    # resource mapping not found for name: "raycluster-kuberay" namespace: "" from "": no
-    # matches for kind "RayCluster" in version "ray.io/v1"
-    # ensure CRDs are installed first
-    ```
-  * Example 2: Upgrade KubeRay from v0.6.0 to v1.0.0 with deleting the old CRD.
-    ```shell
-    # Install KubeRay v0.6.0 and CRD v1alpha1
-    helm install kuberay-operator kuberay/kuberay-operator --version 0.6.0
-
-    # The following instruction uninstalls only KubeRay v0.6.0. It does not uninstall CRD v1alpha1.
-    helm uninstall kuberay-operator
-
-    # Delete CRDs. Note that deleting the CRD causes a cascading deletion of custom resources.
-    kubectl delete crd rayclusters.ray.io
-    kubectl delete crd rayjobs.ray.io
-    kubectl delete crd rayservices.ray.io
-
-    # Install KubeRay v1.0.0 and new CRD including v1.
-    helm install kuberay-operator kuberay/kuberay-operator --version 1.0.0
-
-    # Check CRD
-    kubectl describe crd rayclusters.ray.io | grep v1
-    # You can see both "Name: v1alpha1" and "Name: v1".
-
-    # Install RayCluster v1.0.0 which uses CRD v1.
-    helm install raycluster kuberay/ray-cluster --version 1.0.0
-    ```
+Due to reliability and security implications of webhooks, KubeRay doesn't support a conversion webhook to convert v1alpha1 to v1 APIs.
+
+To upgrade the KubeRay version, follow these steps in order:
+1. Upgrade the CRD manifest, containing new fields added to the v1 CRDs.
+2. Upgrade the kuberay-operator image to the new version.
+3. Verify the success of the upgrade.
+
+The following is an example of upgrading KubeRay from v1.0.0 to v1.1.0:
+```
+# Upgrade the CRD to v1.1.0.
+# Note: This example uses kubectl because Helm doesn't support lifecycle management of CRDs.
+# See the Helm documentation for more details: https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations
+$ kubectl replace -k "github.com/ray-project/kuberay/ray-operator/config/crd?ref=v1.1.0"
+
+# Upgrade kuberay-operator to v1.1.0. This step doesn't upgrade the CRDs.
+$ helm upgrade kuberay-operator kuberay/kuberay-operator --version v1.1.0
+
+# Install a RayCluster using the v1.1.0 helm chart to verify the success of the upgrade.
+$ helm install raycluster kuberay/ray-cluster --version 1.1.0
+```
+
+The following is an example of upgrading KubeRay from v0.6.0 to v1.0.0:
+```
+# Upgrade the CRD to v1.0.0.
+# Note: This example uses kubectl because Helm doesn't support lifecycle management of CRDs.
+# See the Helm documentation for more details: https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations
+$ kubectl replace -k "github.com/ray-project/kuberay/ray-operator/config/crd?ref=v1.0.0"
+
+# Upgrade kuberay-operator to v1.0.0. This step doesn't upgrade the CRDs.
+$ helm upgrade kuberay-operator kuberay/kuberay-operator --version v1.0.0
+
+# Install a RayCluster using the v1.0.0 helm chart to verify the success of the upgrade.
+$ helm install raycluster kuberay/ray-cluster --version 1.0.0
+```