[Release] Update docs for release v0.4.0

docs/deploy/docker.md

@@ -3,7 +3,7 @@
 Find the Docker images for various KubeRay components on [Dockerhub](https://hub.docker.com/u/kuberay).
 
 #### Stable versions
-For stable releases, use version tags (e.g. `kuberay/operator:v0.3.0`).
+For stable releases, use version tags (e.g. `kuberay/operator:v0.4.0`).
 
 #### Master commits
 The first seven characters of the git SHA specify images built from specific commits

docs/deploy/installation.md

@@ -2,34 +2,49 @@
 
 Make sure your Kubernetes cluster and Kubectl are both at version at least 1.19.
 
-#### Nightly version
+### Nightly version
 
-```
+```sh
 export KUBERAY_VERSION=master
+
+# Install CRDs
 kubectl create -k "github.com/ray-project/kuberay/manifests/cluster-scope-resources?ref=${KUBERAY_VERSION}&timeout=90s"
+
+# Install KubeRay operator
 kubectl apply -k "github.com/ray-project/kuberay/manifests/base?ref=${KUBERAY_VERSION}&timeout=90s"
 ```
 
-#### Stable version
+### Stable version
+#### Method 1: Install charts from Helm repository
+```sh
+helm repo add kuberay https://ray-project.github.io/kuberay-helm/
 
+# Install both CRDs and KubeRay operator
+helm install kuberay-operator kuberay/kuberay-operator
 ```
+
+#### Method 2: Kustomize
+```sh
+# Install CRDs
 kubectl create -k "github.com/ray-project/kuberay/manifests/cluster-scope-resources?ref=v0.3.0"
+
+# Install KubeRay operator
 kubectl apply -k "github.com/ray-project/kuberay/manifests/base?ref=v0.3.0"
 ```
 
 > Observe that we must use `kubectl create` to install cluster-scoped resources.
 > The corresponding `kubectl apply` command will not work. See [KubeRay issue #271](https://github.com/ray-project/kuberay/issues/271).
 
-#### Single Namespace version
+### Single Namespace version
 
-It is possible that the user can only access one single namespace while deploying KubeRay. To deploy KubeRay in a single namespace, the user
-can use following commands.
+Users can use the following commands to deploy KubeRay operator in a specific namespace.
 
-```
-# Nightly version
+```sh
 export KUBERAY_NAMESPACE=<my-awesome-namespace>
-# executed by cluster admin
+
+# Install CRDs (Executed by cluster admin)
 kustomize build "github.com/ray-project/kuberay/manifests/overlays/single-namespace-resources" | envsubst | kubectl create -f -
-# executed by user
+
+# Install KubeRay operator (Executed by user)
 kustomize build "github.com/ray-project/kuberay/manifests/overlays/single-namespace" | envsubst | kubectl apply -f -
 ```

docs/development/development.md

@@ -1,59 +1,26 @@
 ## KubeRay Development Guidance
 
-Download this repo locally
-
-```
-mkdir -p $GOPATH/src/github.com/ray-project
-cd $GOPATH/src/github.com/ray-project
-git clone https://github.com/ray-project/kuberay.git
-```
-
-### Develop proto and OpenAPI
-
-Generate go clients and swagger file
-
-```
-make generate
-```
-
 ### Develop KubeRay Operator
 
-```
-cd ray-operator
-
-# Build codes
-make build
-
-# Run test
-make test
-
-# Build container image
-make docker-build
-```
+See [ray-operator/DEVELOPMENT.md](https://github.com/ray-project/kuberay/blob/master/ray-operator/DEVELOPMENT.md) for more details.
 
 ### Develop KubeRay APIServer
 
-```
-cd apiserver
-
-# Build code
-go build cmd/main.go
-```
+See [apiserver/DEVELOPMENT.md](https://github.com/ray-project/kuberay/blob/master/apiserver/DEVELOPMENT.md) for more details.
 
 ### Develop KubeRay CLI
 
-```
-cd cli
-go build -o kuberay -a main.go
-./kuberay help
-```
+See [cli/README.md](https://github.com/ray-project/kuberay/blob/master/cli/README.md) for more details.
+
+### Develop proto and OpenAPI
+
+See [proto/README.md](https://github.com/ray-project/kuberay/blob/master/proto/README.md) for more details.
 
 ### Deploy Docs locally
 
-We don't need to configure `mkdocs` environment. To check the static website locally, run
-the following command from the root of your clone of the KubeRay repo:
+Run the following command in the root directory of your KubeRay repo to deploy Docs locally:
 
-```
+```sh
 docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
 ```
 

helm-chart/kuberay-operator/README.md

@@ -1,52 +1,61 @@
 # KubeRay Operator
 
-Kuberay-operator: A simple Helm chart
-
-Run a deployment of Ray Operator.
-
-Deploy ray operator first, then deploy ray cluster.
+This document provides instructions to install both CRDs (RayCluster, RayJob, RayService) and KubeRay operator with a Helm chart.
 
 ## Helm
 
-Make sure helm version is v3+
-```console
-$ helm version
-version.BuildInfo{Version:"v3.6.2", GitCommit:"ee407bdf364942bcb8e8c665f82e15aa28009b71", GitTreeState:"dirty", GoVersion:"go1.16.5"}
+Make sure the version of Helm is v3+. Currently, [existing CI tests](https://github.com/ray-project/kuberay/blob/master/.github/workflows/helm-lint.yaml) are based on Helm v3.4.1 and v3.9.4.
+
+```sh
+helm version
 ```
 
-## Installing the Chart
+## Install CRDs and KubeRay operator
 
-To avoid duplicate CRD definitions in this repo, we reuse CRD config in `ray-operator`:
-```console
-$ kubectl create -k "github.com/ray-project/kuberay/ray-operator/config/crd?ref=v0.3.0&timeout=90s"
-```
-> Note that we must use `kubectl create` to install the CRDs.
-> The corresponding `kubectl apply` command will not work. See [KubeRay issue #271](https://github.com/ray-project/kuberay/issues/271).
+* Install a stable version via Helm repository (only supports KubeRay v0.4.0+)
+  ```sh
+  helm repo add kuberay https://ray-project.github.io/kuberay-helm/
 
-Use the following command to install the chart:
-```console
-$ helm install kuberay-operator --namespace ray-system --create-namespace $(curl -s https://api.github.com/repos/ray-project/kuberay/releases/tags/v0.3.0 | grep '"browser_download_url":' | sort | grep -om1 'https.*helm-chart-kuberay-operator.*tgz')
-```
+  # Install both CRDs and KubeRay operator v0.4.0.
+  helm install kuberay-operator kuberay/kuberay-operator --version 0.4.0
 
-## List the Chart
+  # Check the KubeRay operator Pod in `default` namespace
+  kubectl get pods
+  # NAME                                READY   STATUS    RESTARTS   AGE
+  # kuberay-operator-6fcbb94f64-mbfnr   1/1     Running   0          17s
+  ```
+
+* Install the nightly version
+  ```sh
+  # Step1: Clone KubeRay repository
+
+  # Step2: Move to `helm-chart/kuberay-operator`
+
+  # Step3: Install KubeRay operator
+  helm install kuberay-operator .
+  ```
+
+## List the chart
 
 To list the `my-release` deployment:
 
-```console
-$ helm list -n ray-system
+```sh
+helm ls
+# NAME                    NAMESPACE       REVISION        UPDATED                                   STATUS          CHART                   # APP VERSION
+# kuberay-operator        default         1               2022-12-02 02:13:37.514445313 +0000 UTC   deployed        kuberay-operator-0.4.0  1.0
 ```
 
-## Uninstalling the Chart
+## Uninstall the Chart
 
-To uninstall/delete the `my-release` deployment:
+```sh
+# Uninstall the `kuberay-operator` release
+helm uninstall kuberay-operator
 
-```console
-$ helm delete kuberay-operator -n ray-system
+# The operator Pod should be removed.
+kubectl get pods
+# No resources found in default namespace.
 ```
 
-The command removes nearly all the Kubernetes components associated with the
-chart and deletes the release.
-
 ## Working with Argo CD
 
 If you are using [Argo CD](https://argoproj.github.io) to manage the operator, you will encounter the issue which complains the CRDs too long. Same with [this issue](https://github.com/prometheus-operator/prometheus-operator/issues/4439).

helm-chart/ray-cluster/README.md

@@ -1,67 +1,49 @@
-# Ray Cluster
+# RayCluster
 
-Make sure ray-operator has been deployed.
+RayCluster is a custom resource definition (CRD). **KubeRay operator** will listen to the resource events about RayCluster and create related Kubernetes resources (e.g. Pod & Service). Hence, **KubeRay operator** installation and **CRD** registration are required for this guide.
 
-[Ray](https://ray.io/) is a unified framework for scaling AI and Python applications. Ray consists of a core distributed runtime and a toolkit of libraries (Ray AIR) for simplifying ML compute.
+## Prerequisites
+See [kuberay-operator/README.md](https://github.com/ray-project/kuberay/blob/master/helm-chart/kuberay-operator/README.md) for more details.
+* Helm
+* Install custom resource definition and KubeRay operator (covered by the following end-to-end example.)
 
-## Helm
+## End-to-end example
 
-```console
-$ helm version
-version.BuildInfo{Version:"v3.6.2", GitCommit:"ee407bdf364942bcb8e8c665f82e15aa28009b71", GitTreeState:"dirty", GoVersion:"go1.16.5"}
-```
-
-## TL;DR;
-
-```bash
-# Because the ray-cluster chart in release 0.3.0 has some bugs, we need to clone the KubeRay repo and install the latest ray-cluster chart until release 0.4.0.
-cd helm-chart/ray-cluster
-helm install ray-cluster --namespace ray-system --create-namespace .
-```
+```sh
+# Step 1: Create a KinD cluster 
+kind create cluster
 
-## Installing the Chart
+# Step 2: Register a Helm chart repo
+helm repo add kuberay https://ray-project.github.io/kuberay-helm/
 
-To install the chart with the release name `my-release`:
-```bash
-# Because the ray-cluster chart in release 0.3.0 has some bugs, we need to clone the KubeRay repo and install the latest ray-cluster chart until release 0.4.0.
-cd helm-chart/ray-cluster
-helm install my-release --namespace ray-system --create-namespace .
-```
+# Step 3: Install both CRDs and KubeRay operator v0.4.0.
+helm install kuberay-operator kuberay/kuberay-operator --version 0.4.0
 
-> note: The chart will submit a RayCluster.
+# Step 4: Install a RayCluster custom resource
+helm install raycluster kuberay/ray-cluster --version 0.4.0
 
+# Step 5: Verify the installation of KubeRay operator and RayCluster 
+kubectl get pods
+# NAME                                          READY   STATUS    RESTARTS   AGE
+# kuberay-operator-6fcbb94f64-gkpc9             1/1     Running   0          89s
+# raycluster-kuberay-head-qp9f4                 1/1     Running   0          66s
+# raycluster-kuberay-worker-workergroup-2jckt   1/1     Running   0          66s
 
-## Uninstalling the Chart
+# Step 6: Forward the port of Dashboard
+kubectl port-forward --address 0.0.0.0 svc/raycluster-kuberay-head-svc 8265:8265
 
-To uninstall/delete the `my-release` deployment:
+# Step 7: Check ${YOUR_IP}:8265 for the Dashboard (e.g. 127.0.0.1:8265)
 
-```console
-helm delete my-release -n ray-system
-```
-
-The command removes nearly all the Kubernetes components associated with the
-chart and deletes the release.
-
-## Check Cluster status
-
-### Get Service
-
-```console
-$ kubectl get svc -l ray.io/cluster=ray-cluster
-NAME                       TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)                       AGE
-ray-cluster-head-svc   ClusterIP   10.103.36.68   <none>        10001/TCP,6379/TCP,8265/TCP   9m24s
-```
+# Step 8: Log in to Ray head Pod and execute a job.
+kubectl exec -it ${RAYCLUSTER_HEAD_POD} -- bash
+python -c "import ray; ray.init(); print(ray.cluster_resources())" # (in Ray head Pod)
 
-## Forward to dashboard
+# Step 9: Check ${YOUR_IP}:8265/#/job. The status of the job should be "SUCCEEDED".
 
-```console
-$ kubectl get pod -o wide
-NAME                                       READY   STATUS    RESTARTS   AGE    IP            NODE             NOMINATED NODE   READINESS GATES
-ray-cluster-head-sd77l                 1/1     Running   0          8h     10.1.61.208   docker-desktop   <none>           <none>
-ray-cluster-worker-workergroup-czxd6   1/1     Running   0          8h     10.1.61.207   docker-desktop   <none>           <none>
-kuberay-operator-687785b964-jgfhv          1/1     Running   6          3d4h   10.1.61.196   docker-desktop   <none>           <none>
+# Step 10: Uninstall RayCluster
+helm uninstall raycluster
 
-$ kubectl port-forward ray-cluster-head-sd77l 8265
-Forwarding from 127.0.0.1:8265 -> 8265
-Forwarding from [::1]:8265 -> 8265
+# Step 11: Verify that RayCluster has been removed successfully
+# NAME                                READY   STATUS    RESTARTS   AGE
+# kuberay-operator-6fcbb94f64-gkpc9   1/1     Running   0          9m57s
 ```