Skip to content

Commit

Permalink
[Release] Update docs for release v0.4.0 (ray-project#779)
Browse files Browse the repository at this point in the history 
Update a few pages of documentation for release v0.4.0
  • Loading branch information
@kevin85421
kevin85421 authored Dec 3, 2022
1 parent 6d88823 commit 251c527
Show file tree
Hide file tree
Showing 5 changed files with 108 additions and 135 deletions.
2 changes: 1 addition & 1 deletion docs/deploy/docker.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
35 changes: 25 additions & 10 deletions docs/deploy/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 -
```
51 changes: 9 additions & 42 deletions docs/development/development.md
View file
Original file line number Diff line number Diff line change
@@ -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
```

Expand Down
69 changes: 39 additions & 30 deletions helm-chart/kuberay-operator/README.md
View file
Original file line number Diff line number Diff line change
@@ -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).
Expand Down
86 changes: 34 additions & 52 deletions helm-chart/ray-cluster/README.md
View file
Original file line number Diff line number Diff line change
@@ -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
```

0 comments on commit 251c527

Please sign in to comment.