Merge pull request #737 from jasonnovichRunAI:v2.17

Merge pull request #721 from ozRunAI/v2.16

Author: jasonnovichRunAI

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

@@ -23,7 +23,7 @@ Follow the prerequisites as explained in [Self-Hosted installation over Kubernet
     ```
 
 === "Airgapped"
-    You should receive a single file `runai-air-gapped-<version>.tar.gz` from Run:ai customer support
+    You should receive a single file `runai-air-gapped-<VERSION>.tar.gz` from Run:ai customer support
 
     SSH into a node with `kubectl` access to the cluster and `Docker` installed.
 
@@ -60,7 +60,7 @@ Follow the prerequisites as explained in [Self-Hosted installation over Kubernet
 
 To access the organization's docker registry it is required to set the registry's credentials (imagePullSecret)
 
-Create the secret named `runai-reg-creds` based on your existing credentials. For more information, see [Allowing pods to reference images from other secured registries](https://docs.openshift.com/container-platform/latest/openshift_images/managing_images/using-image-pull-secrets.html#images-allow-pods-to-reference-images-from-secure-registries_using-image-pull-secrets){target=_blank}.
+Create the secret named `runai-reg-creds` based on your existing credentials. For more information, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/){target=_blank}.
 
 ## Configure your environment
 

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

@@ -11,9 +11,6 @@ As part of the installation process you will install:
 
 Both the control plane and clusters require Kubernetes. Typically the control plane and first cluster are installed on the same Kubernetes cluster but this is not a must. 
 
-!!! Important
-    In OpenShift environments, adding a cluster connecting to a __remote__ control plane currently requires the assistance of customer support.  
-
 ## Installer machine
 
 The machine running the installation script (typically the Kubernetes master) must have:
@@ -24,7 +21,7 @@ The machine running the installation script (typically the Kubernetes master) mu
 
 ### Helm
 
-Run:ai requires [Helm](https://helm.sh/){target=_blank} 3.10 or later. To install Helm, see [Installing Helm](https://helm.sh/docs/intro/install/){target=_blank}. If you are installing an air-gapped version of Run:ai, The Run:ai tar file contains the helm binary. 
+Run:ai requires [Helm](https://helm.sh/){target=_blank} 3.14 or later. To install Helm, see [Installing Helm](https://helm.sh/docs/intro/install/){target=_blank}. If you are installing an air-gapped version of Run:ai, The Run:ai tar file contains the helm binary. 
 
 ## Cluster hardware requirements
 

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

@@ -8,29 +8,35 @@ title: Upgrade self-hosted Kubernetes installation
     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. 
 
     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.
+    
 ## Preparations
 
-=== "Connected"
-    No preparation required.
+### Helm
+Run:ai requires [Helm](https://helm.sh/){target=_blank} 3.14 or later.
+Before you continue, validate your installed helm client version.
+To install or upgrade Helm, see [Installing Helm](https://helm.sh/docs/intro/install/){target=_blank}.
+If you are installing an air-gapped version of Run:ai, The Run:ai tar file contains the helm binary. 
 
-=== "Airgapped" 
-    * Ask for a tar file `runai-air-gapped-<new-version>.tar` from Run:ai customer support. The file contains the new version you want to upgrade to. `new-version` is the updated version of the Run:ai control plane.
-    * Upload the images as described [here](preparations.md#runai-software-files).
+### Software files
 
+=== "Connected"
 
-## Upgrade Control Plane
+    Run the helm command below:
 
-### Upgrade from Version 2.9, 2.13, 2.15 or 2.16
+    ``` bash
+    helm repo add runai-backend https://runai.jfrog.io/artifactory/cp-charts-prod
+    helm repo update
+    ```
 
-Before upgrading the control plane, run:
+=== "Airgapped"
+    * Ask for a tar file `runai-air-gapped-<NEW-VERSION>.tar.gz` from Run:ai customer support. The file contains the new version you want to upgrade to. `<NEW-VERSION>` is the updated version of the Run:ai control plane.
+    * Upload the images as described [here](preparations.md#runai-software-files).
 
-``` bash
-POSTGRES_PV=$(kubectl get pvc pvc-postgresql -n runai-backend -o jsonpath='{.spec.volumeName}')
-THANOS_PV=$(kubectl get pvc pvc-thanos-receive -n runai-backend -o jsonpath='{.spec.volumeName}')
-kubectl patch pv $POSTGRES_PV $THANOS_PV -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
-```
+## Before upgrade
 
-### Upgrade from Version 2.7 or 2.8
+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.
+
+### Upgrade from version 2.7 or 2.8
 
 Before upgrading the control plane, run: 
 
@@ -55,11 +61,12 @@ Next, install NGINX as described [here](../../cluster-setup/cluster-prerequisite
 
 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. 
 
-### Upgrade from version 2.9, 2.10, 2.11 
+
+### Upgrade from version 2.9, 2.10 , or 2.11 
 
 Two significant changes to the control-plane installation have happened with version 2.12: _PVC ownership_ and _installation customization_. 
 
-#### PVC Ownership
+#### PVC ownership
 
 Run:ai will no longer directly create the PVCs that store Run:ai data (metrics and database). Instead, going forward, 
 
@@ -70,7 +77,7 @@ The storage class, as per [Kubernetes standards](https://kubernetes.io/docs/conc
 
 To remove the ownership in an older installation, run:
 
-```
+``` bash
 kubectl patch pvc -n runai-backend pvc-thanos-receive  -p '{"metadata": {"annotations":{"helm.sh/resource-policy": "keep"}}}'
 kubectl patch pvc -n runai-backend pvc-postgresql  -p '{"metadata": {"annotations":{"helm.sh/resource-policy": "keep"}}}'
 ```
@@ -79,31 +86,59 @@ kubectl patch pvc -n runai-backend pvc-postgresql  -p '{"metadata": {"annotation
 
 Delete the ingress object which will be recreated by the control plane upgrade
 
-```
+``` bash
 kubectl delete ing -n runai-backend runai-backend-ingress
 ```
-#### Installation Customization
+#### Installation customization
 
 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:
 
 * 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. 
 * Search for the customizations you found in the [optional configurations](./backend.md#optional-additional-configurations) table and add them in the new format. 
 
-### Upgrade Control Plane
 
+## Upgrade Control Plane
+
+### Upgrade from version 2.13, or later
+
+=== "Connected"
+
+    ``` bash
+    helm get values runai-backend -n runai-backend > runai_control_plane_values.yaml
+    helm upgrade runai-backend -n runai-backend runai-backend/control-plane -f runai_control_plane_values.yaml --reset-then-reuse-values
+    ```
+=== "Airgapped"
+
+    ``` bash
+    helm get values runai-backend -n runai-backend > runai_control_plane_values.yaml
+    helm upgrade runai-backend control-plane-<NEW-VERSION>.tgz -n runai-backend  -f runai_control_plane_values.yaml --reset-then-reuse-values
+    ```
+
+### Upgrade from version 2.7, 2.8, 2.9, or 2.11
+    
 * Create a `tls secret` as described in the [control plane installation](backend.md). 
 * 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:
 
-```
-helm upgrade -i runai-backend -n runai-backend runai-backend/control-plane \
+=== "Connected"
+
+    ``` bash
+    helm upgrade -i runai-backend -n runai-backend runai-backend/control-plane \
     --set global.domain=<DOMAIN> \
     --set postgresql.primary.persistence.existingClaim=pvc-postgresql \ 
     --set thanos.receive.persistence.existingClaim=pvc-thanos-receive 
-```
+    ```
 
-!!! Note
-    The helm repository name has changed from `runai-backend/runai-backend` to `runai-backend/control-plane`.
+    !!! Note
+        The helm repository name has changed from `runai-backend/runai-backend` to `runai-backend/control-plane`.
+ 
+=== "Airgapped"
 
+    ``` bash
+    helm upgrade -i runai-backend control-plane-<NEW-VERSION>.tgz -n runai-backend \
+    --set global.domain=<DOMAIN> \
+    --set postgresql.primary.persistence.existingClaim=pvc-postgresql \ 
+    --set thanos.receive.persistence.existingClaim=pvc-thanos-receive 
+    ```
 
 ## Upgrade Cluster 
 

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

@@ -23,7 +23,7 @@ The machine running the installation script (typically the Kubernetes master) mu
 
 ### Helm
 
-Run:ai requires [Helm](https://helm.sh/){target=_blank} 3.10 or later. To install Helm, see [Installing Helm](https://helm.sh/docs/intro/install/){target=_blank}. If you are installing an air-gapped version of Run:ai, The Run:ai tar file contains the helm binary. 
+Run:ai requires [Helm](https://helm.sh/){target=_blank} 3.14 or later. To install Helm, see [Installing Helm](https://helm.sh/docs/intro/install/){target=_blank}. If you are installing an air-gapped version of Run:ai, The Run:ai tar file contains the helm binary. 
 
 ## Cluster hardware requirements
 

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

@@ -3,18 +3,39 @@ title: Upgrade self-hosted OpenShift installation
 ---
 # Upgrade Run:ai 
 
+
+!!! Important
+    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. 
+
+    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.
+
 ## Preparations
 
+### Helm
+Run:ai requires [Helm](https://helm.sh/){target=_blank} 3.14 or later.
+Before you continue, validate your installed helm client version.
+To install or upgrade Helm, see [Installing Helm](https://helm.sh/docs/intro/install/){target=_blank}.
+If you are installing an air-gapped version of Run:ai, The Run:ai tar file contains the helm binary. 
+
+### Software files
+
 === "Connected"
-    No preparation required.
+    Run the helm command below:
+
+    ``` bash
+    helm repo add runai-backend https://runai.jfrog.io/artifactory/cp-charts-prod
+    helm repo update
+    ```
 
 === "Airgapped" 
-    * Ask for a tar file `runai-air-gapped-<new-version>.tar` from Run:ai customer support. The file contains the new version you want to upgrade to. `new-version` is the updated version of the Run:ai control plane.
+    * Ask for a tar file `runai-air-gapped-<NEW-VERSION>.tar.gz` from Run:ai customer support. The file contains the new version you want to upgrade to. `<NEW-VERSION>` is the updated version of the Run:ai control plane.
     * Upload the images as described [here](preparations.md#runai-software-files).
 
-## Upgrade Control Plane
+## Before upgrade
 
-### Upgrade from Version 2.7 or 2.8.
+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.
+
+### Upgrade from version 2.7 or 2.8
 
 Before upgrading the control plane, run: 
 
@@ -28,10 +49,10 @@ kubectl delete sts -n runai-backend keycloak runai-backend-postgresql
 
 Then upgrade the control plane as described [below](#upgrade-the-control-plane). Before upgrading, find customizations and merge them as discussed below. 
 
-### Upgrade from Version 2.9, 2.10 or 2.11
+### Upgrade from version 2.9, 2.10 or 2.11
 
 Two significant changes to the control-plane installation have happened with version 2.12: _PVC ownership_ and _installation customization_. 
-#### PVC Ownership
+#### PVC ownership
 
 Run:ai will no longer directly create the PVCs that store Run:ai data (metrics and database). Instead, going forward, 
 
@@ -46,20 +67,35 @@ To remove the ownership in an older installation, run:
 kubectl patch pvc -n runai-backend pvc-postgresql  -p '{"metadata": {"annotations":{"helm.sh/resource-policy": "keep"}}}'
 ```
 
-#### Installation Customization
+#### Installation customization
 
 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:
 
 * 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. 
 * Search for the customizations you found in the [optional configurations](./backend.md#optional-additional-configurations) table and add them in the new format.  
 
 
+## Upgrade Control Plane
 
-Then upgrade the control plane as described [below](#upgrade-the-control-plane). 
+### Upgrade from version 2.13, or later
 
-### Upgrade Control Plane
+=== "Connected"
+
+    ``` bash
+    helm get values runai-backend -n runai-backend > runai_control_plane_values.yaml
+    helm upgrade runai-backend -n runai-backend runai-backend/control-plane -f runai_control_plane_values.yaml --reset-then-reuse-values
+    ```
+=== "Airgapped"
+
+    ``` bash
+    helm get values runai-backend -n runai-backend > runai_control_plane_values.yaml
+    helm upgrade runai-backend control-plane-<NEW-VERSION>.tgz -n runai-backend  -f runai_control_plane_values.yaml --reset-then-reuse-values
+    ```
+
+### Upgrade from version 2.7, 2.8, 2.9, or 2.11
 
 === "Connected"
+
     ``` bash
     helm upgrade -i runai-backend -n runai-backend runai-backend/control-plane  \
     --set global.domain=runai.apps.<OPENSHIFT-CLUSTER-DOMAIN> \ #(1)
@@ -76,9 +112,9 @@ Then upgrade the control plane as described [below](#upgrade-the-control-plane).
 
 
 === "Airgapped"
-    ``` bash
 
-    helm upgrade -i runai-backend  ./runai-backend-<version>.tgz -n runai-backend \
+    ``` bash
+    helm upgrade -i runai-backend  ./control-plane-<NEW-VERSION>.tgz -n runai-backend \
     --set global.domain=runai.apps.<OPENSHIFT-CLUSTER-DOMAIN> \ #(1)
     --set global.config.kubernetesDistribution=openshift \
     --set thanos.query.stores={thanos-grpc-port-forwarder:10901} \