Chapter 4. Upgrading CodeReady Workspaces

This chapter describes how to upgrade from CodeReady Workspaces 1.2 instance to CodeReady Workspaces 2.0.

The method that was used to install the CodeReady Workspaces 1.2 instance determines the method to proceed with for the upgrade.

Following scenarios are covered:

After a major upgrade of the CodeReady Workspaces instance from 1.2 to 2.0, it is necessary to migrate the workspaces to new devfiles definitions:

See the CodeReady Workspaces 2.0 End-user Guide.

4.1. Upgrading CodeReady Workspaces on OpenShift 4 using the web console

This section describes how to upgrade from CodeReady Workspaces 1.2 to CodeReady Workspaces 2.0 on OpenShift 4 using the OpenShift web console. This method is using the Operator from OperatorHub.

4.1.1. Preparing the upgrade of CodeReady Workspaces on OpenShift using the Operator

This section describes how to prepare upgrade from CodeReady Workspaces 1.2 to CodeReady Workspaces 2.0 on OpenShift using the Operator.

Uninstalling the Red Hat CodeReady Workspaces 1.2 Operator means that the OpenShift cluster do not receive any updates of the CodeReady Workspaces 1.2 Operator. As a consequence, the existing CodeReady Workspaces instances do not receive any update. The CodeReady Workspaces instances that are already present, including their database, remains present.

Prerequisites
  • And administrative account on an OpenShift 4 instance.
  • Red Hat CodeReady Workspaces 1.2 Operator is installed on this OpenShift 4 instance.
  • A running instance of CodeReady Workspaces 1.2 on this OpenShift 4 instance.
Procedure
  1. In all running workspaces in the CodeReady Workspaces 1.2 instance, save and push changes back to the git repositories.
  2. Shut down all workspaces in the CodeReady Workspaces 1.2 instance.
  3. Open the OpenShift console.
  4. Navigate to Operators > Installed Operators.
  5. Click on Red Hat CodeReady Workspaces 1.2.
  6. Click on the Actions button on the top right.
  7. A drop-down menu appears.
  8. Click on Uninstall Operator to uninstall the CodeReady Workspaces 1.2 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.

4.1.2. Creating the CodeReady Workspaces project in OpenShift 4 web console

This section describes how to create the CodeReady Workspaces 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 workspaces.
    • In the Display Name field, type Red Hat CodeReady Workspaces.
  5. Click the Create button.

4.1.3. Installing the CodeReady Workspaces Operator in OpenShift 4 web console

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

Prerequisites
Procedure
  1. Open the OpenShift web console.
  2. In the left panel, navigate to the OperatorsOperatorHub section.
  3. In the Search by keyword field, type Red Hat CodeReady Workspaces.
  4. Click on the Red Hat CodeReady Workspaces tile.
  5. Click the Install button in the Red Hat CodeReady Workspaces pop-up window.
  6. In the A specific namespace on the cluster field, in the cluster drop-down list, select the namespace into which the previous version of the CodeReady Workspaces Operator was installed.
  7. Click the Subscribe button.
  8. In the left panel, navigate to the OperatorsInstalled Operators section.
  9. Red Hat CodeReady Workspaces is displayed as an installed Operator having the InstallSucceeded status.
  10. Click on the Red Hat CodeReady Workspaces 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.

4.1.4. Viewing the state of the CodeReady Workspaces cluster deployment in OpenShift 4 web console

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

Prerequisites
  • An administrator account on a running instance of OpenShift 4.
  • A CodeReady Workspaces cluster is deployed on this instance of OpenShift 4.
Procedure
  1. Open the OpenShift web console.
  2. Navigate to the OperatorsInstalled Operators section.
  3. Click Red Hat CodeReady Workspaces in the list of installed operators.
  4. Navigate to the Red Hat CodeReady Workspaces 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 CodeReady Workspaces cluster deployment.

    eclipse che resources tab

4.1.5. Finishing the upgrade of CodeReady Workspaces on OpenShift using the Operator

This section describes how to finish the upgrade from CodeReady Workspaces 1.2 to CodeReady Workspaces 2.0 on OpenShift using the Operator.

Prerequisites

Procedure

  1. Log into the Red Hat CodeReady Workspaces 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 the CodeReady Workspaces 2.0 End-user Guide.
  5. Use the devfile to start the new workspace. See the CodeReady Workspaces 2.0 End-user Guide.

4.2. Upgrading CodeReady Workspaces on OpenShift 4 using the CLI management tool

This section describes how to upgrade from CodeReady Workspaces 1.2 to CodeReady Workspaces 2.0 on OpenShift 4 using the CLI management tool.

Prerequisites

  • And administrative account on an OpenShift 4 instance.
  • A running instance of Red Hat CodeReady Workspaces running on OpenShift 4.
  • This instance was installed using the CLI management tool, not using OperatorHub.
  • The crwctl management tool is installed. See the CodeReady Workspaces 2.0 Installation Guide.

Procedure

  1. In all running workspaces in the CodeReady Workspaces 1.2 instance, save and push changes back to the Git repositories.
  2. Shut down all workspaces in the CodeReady Workspaces 1.2 instance.
  3. Run following command:

    $ crwctl server:update

Verification steps

  1. Log in to the CodeReady Workspaces instance.
  2. The 2.0 version number is displayed at the bottom of the page.

4.3. Upgrading CodeReady Workspaces on OpenShift 3 using the CLI management tool

This section describes how to upgrade from CodeReady Workspaces 1.2 to CodeReady Workspaces 2.0 on OpenShift 3 using the CLI management tool.

Prerequisites

  • And administrative account on an OpenShift 3 instance.
  • A running instance of Red Hat CodeReady Workspaces running on OpenShift 3.
  • This instance was installed using the CLI management tool.
  • The crwctl management tool is installed. See the CodeReady Workspaces 2.0 Installation Guide.

Procedure

  1. In all running workspaces in the CodeReady Workspaces 1.2 instance, save and push changes back to the Git repositories.
  2. Shut down all workspaces in the CodeReady Workspaces 1.2 instance.
  3. Run the following command:

    $ crwctl server:update

Verification steps

  1. Log in to the CodeReady Workspaces instance.
  2. The 2.0 version number is displayed at the bottom of the page.

4.4. Known issues

4.4.1. Upgrading from CodeReady Workspaces 1.2 to CodeReady Workspaces 2.0 using the Operator

When upgrading the Operator of a CodeReady Workspaces 1.2 installation to CodeReady Workspaces 2.0, some components may not be automatically updated. To fix this, manually update the images listed in the checluster custom resource, which describes the CodeReady Workspaces installation. To reset the images to their default versions for given Operator version, set the image properties to empty strings. This forces the CodeReady Workspaces 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

4.4.2. Updating a CodeReady Workspaces installation using the Operator

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

On OpenShift, run:

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

On OpenShift, run:

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

Making local updates to the YAML file of the checluster resource and then applying such changed resource to the cluster using oc apply -f or oc apply -f can result in an invalidation of the CodeReady Workspaces installation.