This chapter describes how to upgrade from Che 6.x instance to Che 7.3.

The method that was used to install the Che 6.x instance determines the method to proceed with for the upgrade.

Following scenarios are covered:

After a major upgrade of the Che instance from 6.x to 7.3, it is necessary to migrate the workspaces to new devfiles definitions:

Upgrading Che on OpenShift 4 using the web console

This section describes how to upgrade from Che 6.x to Che 7.3 on OpenShift 4 using the OpenShift web console. This method is using the Operator from OperatorHub.

Preparing the upgrade of Che on OpenShift using the Operator

This section describes how to prepare upgrade from Che 6.x to Che 7.3 on OpenShift using the Operator.

Uninstalling the Eclipse Che 6.x Operator means that the OpenShift cluster do not receive any updates of the Che 6.x Operator. As a consequence, the existing Che instances do not receive any update. The Che instances that are already present, including their database, remains present.

Prerequisites

  • And administrative account on an OpenShift 4 instance.

  • Eclipse Che 6.x Operator is installed on this OpenShift 4 instance.

  • A running instance of Che 6.x on this OpenShift 4 instance.

Procedure

  1. In all running workspaces in the Che 6.x instance, save and push changes back to the git repositories.

  2. Shut down all workspaces in the Che 6.x instance.

  3. Open the OpenShift console.

  4. Navigate to Operators > Installed Operators.

  5. Click on Eclipse Che 6.x.

  6. Click on the Actions button on the top right.

  7. A drop-down menu appears.

  8. Click on Uninstall Operator to uninstall the Che 6.x Operator.

  9. Accept the selected option Also completely remove the Operator from the selected namespace.

  10. Click on the Remove button.

  11. Navigate to Operators > Installed Operators.

  12. The Operator is removed from the list of installed operators.

Creating the Che project in OpenShift 4 web console

This section describes how to create the Che project in OpenShift 4 web console.

Prerequisites

  • An administrator account on a running instance of OpenShift 4.

Procedure

  1. Open the OpenShift web console.

  2. In the left panel, navigate to Projects.

  3. Click the Create Project button.

  4. Enter the project details:

    • In the Name field, type che.

    • In the Display Name field, type Eclipse Che.

  5. Click the Create button.

Installing the Che Operator in OpenShift 4 web console

This section describes how to install the Che Operator in OpenShift 4 web console.

Prerequisites

  • An administrator account on a running instance of OpenShift 4.

  • Administrative rights on an existing project named che on this instance of OpenShift 4. See Creating the Che project in OpenShift 4 web console.

  • The Eclipse Che 6.x Operator is not installed.

Procedure

  1. Open the OpenShift web console.

  2. In the left panel, navigate to the Operators → OperatorHub section.

  3. In the Search by keyword field, type Eclipse Che.

  4. Click on the Eclipse Che tile.

  5. Click the Install button in the Eclipse Che pop-up window.

  6. In the A specific namespace on the cluster field, in the cluster drop-down list, select che.

  7. Click the Subscribe button.

  8. In the left panel, navigate to the Operators → Installed Operators section.

  9. Eclipse Che is displayed as an installed Operator having the InstallSucceeded status.

  10. Click on the Eclipse Che name in the list of installed operators.

  11. Navigate to the Overview tab.

  12. In the Conditions sections at the bottom of the page, wait for this message: install strategy completed with no errors.

  13. Navigate to the Events tab.

  14. Wait for this message: install strategy completed with no errors.

Viewing the state of the Che cluster deployment in OpenShift 4 web console

This section describes how to view the state of the Che cluster deployment in OpenShift 4 web console.

Prerequisites

  • An administrator account on a running instance of OpenShift 4.

  • A Che cluster is deployed on this instance of OpenShift 4.

Procedure

  1. Open the OpenShift web console.

  2. Navigate to the Operators → Installed Operators section.

  3. Click Eclipse Che in the list of installed operators.

  4. Navigate to the Eclipse Che Cluster tab.

  5. Click on the eclipse-che cluster that is listed in the table.

  6. Navigate to the Overview tab.

  7. Watch the content of the Message field. The field contain error messages, if any. The expected content is None.

  8. Navigate to the Resources tab.

  9. The screen displays the state of the resources assigned to the Che cluster deployment.

    eclipse che resources tab

Finishing the upgrade of Che on OpenShift using the Operator

This section describes how to finish the upgrade from Che 6.x to Che 7.3 on OpenShift using the Operator.

Prerequisites
Procedure

  1. Log into the Eclipse Che instance.

  2. Select an old workspace and click on the Start button.

  3. An error message appears, with a link to the documentation explaining how to migrate a workspace to a devfile.

  4. For each workspace, create a devfile that represent your workspace. See Converting a Che 6.x workspace to a Che 7.3 devfile.

  5. Use the devfile to start the new workspace. See Configuring a workspace using a devfile

Upgrading Che on OpenShift 4 using the CLI management tool

This section describes how to upgrade from Che 6.x to Che 7.3 on OpenShift 4 using the CLI management tool.

Prerequisites

  • And administrative account on an OpenShift 4 instance.

  • A running instance of Eclipse Che running on OpenShift 4.

  • This instance was installed using the CLI management tool, not using OperatorHub.

  • The chectl management tool is installed. See Installing the chectl management tool.

Procedure

  1. In all running workspaces in the Che 6.x instance, save and push changes back to the Git repositories.

  2. Shut down all workspaces in the Che 6.x instance.

  3. Run following command:

    $ chectl server:update
Verification steps

  1. Log in to the Che instance.

  2. The 7.3 version number is displayed at the bottom of the page.

Upgrading Che on OpenShift 3 using the CLI management tool

This section describes how to upgrade from Che 6.x to Che 7.3 on OpenShift 3 using the CLI management tool.

Prerequisites

  • And administrative account on an OpenShift 3 instance.

  • A running instance of Eclipse Che running on OpenShift 3.

  • This instance was installed using the CLI management tool.

  • The chectl management tool is installed. See Installing the chectl management tool.

Procedure

  1. In all running workspaces in the Che 6.x instance, save and push changes back to the Git repositories.

  2. Shut down all workspaces in the Che 6.x instance.

  3. Run the following command:

    $ chectl server:update
Verification steps

  1. Log in to the Che instance.

  2. The 7.3 version number is displayed at the bottom of the page.

Known issues

Upgrading from Che 6.x to Che 7.3 using the Operator

When upgrading the Operator of a Che 6.x installation to Che 7.3, some components may not be automatically updated. To fix this, manually update the images listed in the checluster custom resource, which describes the Che installation. To reset the images to their default versions for given Operator version, set the image properties to empty strings. This forces the Che Operator to use the default versions it was built with.

Review the following components:

Component

CR attribute name

Postgresql

spec.database.postgresImage

Keycloak

spec.auth.identityProviderImage

PVC Jobs

spec.storage.pvcJobsImage

Updating a Che installation using the Operator

When making changes to the checluster custom resource, use patching to make updates to it. For example:

On Kubernetes, run:

$ kubectl patch checluster <my-che> --type=json -n <che-namespace> -p '...'

On OpenShift, run:

$ oc patch checluster <my-che> --type=json -n <che-namespace> -p '...'
Making local updates to the YAML file of the checluster resource and then applying such changed resource to the cluster using kubectl apply -f or oc apply -f can result in an invalidation of the Che installation.
Tags: