Skip to content

Commit 76a068f

Browse files
Merge pull request #918 from ozRunAI/fix-upgrade-docs
deprecate old versions, improve install & upgrade docs
2 parents fc44a68 + df2a106 commit 76a068f

File tree

6 files changed

+41
-138
lines changed

6 files changed

+41
-138
lines changed
Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,9 @@
11
# Deleting a Cluster Installation
22

3-
To delete a Run:ai Cluster installation while retaining existing running jobs, run the following commands:
3+
To delete a Run:ai Cluster installation run the following commands:
44

5-
=== "Version 2.9 or later"
65
```
76
helm uninstall runai-cluster -n runai
87
```
98

10-
=== "Version 2.8"
11-
```
12-
kubectl delete RunaiConfig runai -n runai
13-
helm uninstall runai-cluster -n runai
14-
```
15-
16-
=== "Version 2.7 or earlier"
17-
```
18-
kubectl patch RunaiConfig runai -n runai -p '{"metadata":{"finalizers":[]}}' --type="merge"
19-
kubectl delete RunaiConfig runai -n runai
20-
helm uninstall runai-cluster runai -n runai
21-
```
22-
23-
The commands will **not** delete existing Jobs submitted by users.
9+
The command will **not** delete existing Projects, Departments, or Workloads submitted by users.

docs/admin/runai-setup/cluster-setup/cluster-install.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,15 @@ Using the cluster wizard:
1717

1818
* Choose a name for your cluster.
1919
* Choose the Run:ai version for the cluster.
20-
* Choose a target Kubernetes distribution (see [table](cluster-prerequisites.md#kubernetes) for supported distributions).
20+
* (v2.13 only) Choose a target Kubernetes distribution.
21+
2122
* (SaaS and remote self-hosted cluster only) Enter a URL for the Kubernetes cluster. The URL need only be accessible within the organization's network. For more informtaion see [here](cluster-prerequisites.md#cluster-url).
2223
* Press `Continue`.
2324

2425
On the next page:
2526

26-
* (SaaS and remote self-hosted cluster only) Install a trusted certificate to the domain entered above.
27+
* (SaaS and remote self-hosted cluster only) Install a [trusted certificate](cluster-prerequisites.md#cluster-url) to the domain entered above.
28+
2729
* Run the [Helm](https://helm.sh/docs/intro/install/) command provided in the wizard.
2830
* In case of a failure, see the [Installation troubleshooting guide](../../troubleshooting/troubleshooting.md#installation).
2931

docs/admin/runai-setup/cluster-setup/cluster-prerequisites.md

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,10 +56,7 @@ Following is a Kubernetes support matrix for the latest Run:ai releases:<a name=
5656

5757
| Run:ai version | Supported Kubernetes versions | Supported OpenShift versions |
5858
|----------------|-------------------------------|--------|
59-
| Run:ai 2.9 | 1.21 through 1.26 | 4.8 through 4.11 |
60-
| Run:ai 2.10 | 1.21 through 1.26 (see note below) | 4.8 through 4.11 |
6159
| Run:ai 2.13 | 1.23 through 1.28 (see note below) | 4.10 through 4.13 |
62-
| Run:ai 2.15 | 1.25 through 1.28 | 4.11 through 4.13 |
6360
| Run:ai 2.16 | 1.26 through 1.28 | 4.11 through 4.14 |
6461
| Run:ai 2.17 | 1.27 through 1.29 | 4.12 through 4.15 |
6562
| Run:ai 2.18 | 1.28 through 1.30 | 4.12 through 4.16 |

docs/admin/runai-setup/cluster-setup/cluster-upgrade.md

Lines changed: 28 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,39 @@
11

22
# Upgrading a Cluster Installation
3+
Below are instructions on how to upgrade a Run:ai cluster.
34

4-
## Find out Run:ai Cluster version
5+
## Upgrade Run:ai cluster
6+
Follow the steps bellow, based on the Run:ai Cluster version you would like to upgrade to:
57

6-
To find the Run:ai cluster version, run:
8+
=== "2.15-latest"
9+
* In the Run:ai interface, navigate to `Clusters`.
10+
* Select the cluster you want to upgrade.
11+
* Click on `Get Installation instructions`.
12+
* Choose the `Run:ai version` to upgrade to.
13+
* Press `Continue`.
14+
* Copy the [Helm](https://helm.sh/docs/intro/install/) command provided in the `Installation Instructions` and run it on in the cluster.
15+
* In the case of a failure, refer to the [Installation troubleshooting guide](../../troubleshooting/troubleshooting.md#installation).
716

8-
```
9-
helm list -n runai -f runai-cluster
10-
```
17+
=== "2.13"
18+
Run:
1119

12-
and record the chart version in the form of `runai-cluster-<version-number>`
13-
14-
## Upgrade Run:ai cluster
15-
16-
### Upgrade from version 2.15+
17-
* In the Run:ai interface, navigate to `Clusters`.
18-
* Select the cluster you want to upgrade.
19-
* Click on `Get Installation instructions`.
20-
* Choose the `Run:ai version` to be installed on the Cluster.
21-
* Press `Continue`.
22-
* Copy the [Helm](https://helm.sh/docs/intro/install/) command provided in the `Installation Instructions` and run it on in the cluster.
23-
* In the case of a failure, refer to the [Installation troubleshooting guide](../../troubleshooting/troubleshooting.md#installation).
24-
25-
### Upgrade from version 2.9, 2.10, 2.11 or 2.12
26-
Run:
27-
28-
```
29-
helm get values runai-cluster -n runai > old-values.yaml
30-
```
31-
32-
1. Review the file `old-values.yaml` and see if there are any changes performed during the last installation.
33-
2. Follow the instructions for [Installing Run:ai](cluster-install.md#install-runai) to download a new values file.
34-
3. Merge the changes from Step 1 into the new values file.
35-
4. Run `helm upgrade` as per the instructions in the link above.
36-
37-
38-
!!! Note
39-
To upgrade to a __specific__ version of the Run:ai cluster, add `--version <version-number>` to the `helm upgrade` command. You can find the relevant version with `helm search repo` as described above.
40-
41-
### Upgrade from version 2.7 or 2.8
42-
43-
The process of upgrading from 2.7 or 2.8 requires [uninstalling](./cluster-delete.md) and then [installing](./cluster-install.md) again. No data is lost during the process.
44-
45-
!!! Note
46-
The reason for this process is that Run:ai 2.9 cluster installation no longer installs pre-requisites. As such ownership of dependencies such as Prometheus will be undefined if a `helm upgrade` is run.
47-
48-
The process:
49-
50-
* Delete the Run:ai cluster installation according to these [instructions](cluster-delete.md) (do not delete the Run:ai cluster __object__ from the user interface).
51-
* The following commands should be executed __after__ running the helm uninstall command
5220
```
53-
kubectl -n runai delete all --all
54-
kubectl -n runai delete cm --all
55-
kubectl -n runai delete secret --all
56-
kubectl -n runai delete roles --all
57-
kubectl -n runai delete rolebindings --all
58-
kubectl -n runai delete ingress --all
59-
kubectl -n runai delete servicemonitors --all
60-
kubectl -n runai delete podmonitors --all
61-
kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io -l app=runai
62-
kubectl delete mutatingwebhookconfigurations.admissionregistration.k8s.io -l app=runai
63-
kubectl delete svc -n kube-system runai-cluster-kube-prometh-kubelet
64-
```
65-
* Install the mandatory Run:ai [prerequisites](cluster-prerequisites.md):
66-
* If you have previously installed the SaaS version of Run:ai version 2.7 or below, you will need to install both [Ingress Controller](cluster-prerequisites.md#ingress-controller) and [Prometheus](cluster-prerequisites.md#prometheus).
67-
* If you have previously installed the SaaS version of Run:ai version 2.8 or any Self-hosted version of Run:ai, you will need to install [Prometheus](cluster-prerequisites.md#prometheus) only.
68-
69-
70-
* Install Run:ai cluster as described [here](cluster-install.md)
71-
72-
## Verify Successful Installation
21+
helm get values runai-cluster -n runai > old-values.yaml
22+
```
7323

24+
* Review the file `old-values.yaml` and see if there are any changes performed during the last installation.
25+
* In the Run:ai interface, navigate to `Clusters`.
26+
* Select the cluster you want to upgrade.
27+
* Click on `Get Installation instructions`.
28+
* Select `Run:ai version: 2.13`.
29+
* Select the `cluster's Kubernetes distribution` and the `Cluster location`
30+
* If the Cluster locaiton is remote to the control plane - Enter a URL for the Kubernetes cluster.
31+
* Press `Continue`.
32+
* Follow the instructions to download a new values file.
33+
* Merge the changes from Step 1 into the new values file.
34+
* Copy the [Helm](https://helm.sh/docs/intro/install/) command provided in the `Installation Instructions` and run it on in the cluster.
35+
36+
## Verify Successful Upgrade
7437
See [Verify your installation](cluster-install.md#verify-your-clusters-health) on how to verify a Run:ai cluster installation
7538

7639

docs/admin/runai-setup/self-hosted/k8s/upgrade.md

Lines changed: 3 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -36,33 +36,7 @@ If you are installing an air-gapped version of Run:ai, The Run:ai tar file conta
3636

3737
Before proceeding with the upgrade, it's crucial to apply the specific prerequisites associated with your current version of Run:ai and every version in between up to the version you are upgrading to.
3838

39-
### Upgrade from version 2.7 or 2.8
40-
41-
Before upgrading the control plane, run:
42-
43-
``` bash
44-
POSTGRES_PV=$(kubectl get pvc pvc-postgresql -n runai-backend -o jsonpath='{.spec.volumeName}')
45-
THANOS_PV=$(kubectl get pvc pvc-thanos-receive -n runai-backend -o jsonpath='{.spec.volumeName}')
46-
kubectl patch pv $POSTGRES_PV $THANOS_PV -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
47-
48-
kubectl delete secret -n runai-backend runai-backend-postgresql
49-
kubectl delete sts -n runai-backend keycloak runai-backend-postgresql
50-
```
51-
52-
Before version 2.9, the Run:ai installation, by default, included NGINX. It was possible to disable this installation. If NGINX is enabled in your current installation, as per the default, run the following 2 lines:
53-
54-
``` bash
55-
kubectl delete ValidatingWebhookConfiguration runai-backend-nginx-ingress-admission
56-
kubectl delete ingressclass nginx
57-
```
58-
(If Run:ai configuration has previously disabled NGINX installation then these lines should not be run).
59-
60-
Next, install NGINX as described [here](../../cluster-setup/cluster-prerequisites.md#ingress-controller)
61-
62-
Then create a TLS secret and upgrade the control plane as described in the [control plane installation](backend.md). Before upgrading, find customizations and merge them as discussed below.
63-
64-
65-
### Upgrade from version 2.9, 2.10 , or 2.11
39+
### Upgrade from version 2.9
6640

6741
Two significant changes to the control-plane installation have happened with version 2.12: _PVC ownership_ and _installation customization_.
6842

@@ -81,7 +55,6 @@ To remove the ownership in an older installation, run:
8155
kubectl patch pvc -n runai-backend pvc-thanos-receive -p '{"metadata": {"annotations":{"helm.sh/resource-policy": "keep"}}}'
8256
kubectl patch pvc -n runai-backend pvc-postgresql -p '{"metadata": {"annotations":{"helm.sh/resource-policy": "keep"}}}'
8357
```
84-
8558
#### Ingress
8659

8760
Delete the ingress object which will be recreated by the control plane upgrade
@@ -98,9 +71,7 @@ The Run:ai control-plane installation has been rewritten and is no longer using
9871

9972

10073
## Upgrade Control Plane
101-
10274
### Upgrade from version 2.13, or later
103-
10475
=== "Connected"
10576

10677
``` bash
@@ -113,9 +84,7 @@ The Run:ai control-plane installation has been rewritten and is no longer using
11384
helm get values runai-backend -n runai-backend > runai_control_plane_values.yaml
11485
helm upgrade runai-backend control-plane-<NEW-VERSION>.tgz -n runai-backend -f runai_control_plane_values.yaml --reset-then-reuse-values
11586
```
116-
117-
### Upgrade from version 2.7, 2.8, 2.9, or 2.11
118-
87+
### Upgrade from version 2.9
11988
* Create a `tls secret` as described in the [control plane installation](backend.md).
12089
* Upgrade the control plane as described in the [control plane installation](backend.md). During the upgrade, you must tell the installation __not__ to create the two PVCs:
12190

@@ -142,4 +111,4 @@ The Run:ai control-plane installation has been rewritten and is no longer using
142111

143112
## Upgrade Cluster
144113

145-
To upgrade the cluster follow the instructions [here](../../cluster-setup/cluster-upgrade.md).
114+
To upgrade the cluster follow the instructions [here](../../cluster-setup/cluster-upgrade.md).

docs/admin/runai-setup/self-hosted/ocp/upgrade.md

Lines changed: 4 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,19 @@
22
title: Upgrade self-hosted OpenShift installation
33
---
44
# Upgrade Run:ai
5-
6-
75
!!! Important
86
Run:ai data is stored in Kubernetes persistent volumes (PVs). Prior to Run:ai 2.12, PVs are owned by the Run:ai installation. Thus, uninstalling the `runai-backend` helm chart may delete all of your data.
97

108
From version 2.12 forward, PVs are owned the customer and are independent of the Run:ai installation. As such, they are subject to storage class [reclaim](https://kubernetes.io/docs/concepts/storage/storage-classes/#reclaim-policy){target=_blank} policy.
119

1210
## Preparations
13-
1411
### Helm
1512
Run:ai requires [Helm](https://helm.sh/){target=_blank} 3.14 or later.
1613
Before you continue, validate your installed helm client version.
1714
To install or upgrade Helm, see [Installing Helm](https://helm.sh/docs/intro/install/){target=_blank}.
1815
If you are installing an air-gapped version of Run:ai, The Run:ai tar file contains the helm binary.
1916

2017
### Software files
21-
2218
=== "Connected"
2319
Run the helm command below:
2420

@@ -32,11 +28,8 @@ If you are installing an air-gapped version of Run:ai, The Run:ai tar file conta
3228
* Upload the images as described [here](preparations.md#software-artifacts).
3329

3430
## Before upgrade
35-
3631
Before proceeding with the upgrade, it's crucial to apply the specific prerequisites associated with your current version of Run:ai and every version in between up to the version you are upgrading to.
3732

38-
### Upgrade from version 2.7 or 2.8
39-
4033
Before upgrading the control plane, run:
4134

4235
``` bash
@@ -49,11 +42,10 @@ kubectl delete sts -n runai-backend keycloak runai-backend-postgresql
4942

5043
Then upgrade the control plane as described [below](#upgrade-control-plane). Before upgrading, find customizations and merge them as discussed below.
5144

52-
### Upgrade from version 2.9, 2.10 or 2.11
53-
45+
### Upgrade from version 2.9
5446
Two significant changes to the control-plane installation have happened with version 2.12: _PVC ownership_ and _installation customization_.
55-
#### PVC ownership
5647

48+
#### PVC ownership
5749
Run:ai will no longer directly create the PVCs that store Run:ai data (metrics and database). Instead, going forward,
5850

5951
* Run:ai requires a Kubernetes storage class to be installed.
@@ -68,17 +60,13 @@ kubectl patch pvc -n runai-backend pvc-postgresql -p '{"metadata": {"annotation
6860
```
6961

7062
#### Installation customization
71-
7263
The Run:ai control-plane installation has been rewritten and is no longer using a _backend values file_. Instead, to customize the installation use standard `--set` flags. If you have previously customized the installation, you must now extract these customizations and add them as `--set` flag to the helm installation:
7364

7465
* Find previous customizations to the control plane if such exist. Run:ai provides a utility for that here `https://raw.githubusercontent.com/run-ai/docs/v2.13/install/backend/cp-helm-vals-diff.sh`. For information on how to use this utility please contact Run:ai customer support.
7566
* Search for the customizations you found in the [optional configurations](./backend.md#additional-runai-configurations-optional) table and add them in the new format.
7667

77-
7868
## Upgrade Control Plane
79-
8069
### Upgrade from version 2.13, or later
81-
8270
=== "Connected"
8371

8472
``` bash
@@ -91,8 +79,7 @@ The Run:ai control-plane installation has been rewritten and is no longer using
9179
helm get values runai-backend -n runai-backend > runai_control_plane_values.yaml
9280
helm upgrade runai-backend control-plane-<NEW-VERSION>.tgz -n runai-backend -f runai_control_plane_values.yaml --reset-then-reuse-values
9381
```
94-
95-
### Upgrade from version 2.7, 2.8, 2.9, or 2.11
82+
### Upgrade from version 2.9
9683

9784
=== "Connected"
9885

@@ -124,5 +111,4 @@ The Run:ai control-plane installation has been rewritten and is no longer using
124111
1. The subdomain configured for the OpenShift cluster.
125112

126113
## Upgrade Cluster
127-
128-
To upgrade the cluster follow the instructions [here](../../cluster-setup/cluster-upgrade.md).
114+
To upgrade the cluster follow the instructions [here](../../cluster-setup/cluster-upgrade.md).

0 commit comments

Comments
 (0)