Chapter 5. Upgrading CodeReady Workspaces

This chapter describes how to upgrade a CodeReady Workspaces instance from version 2.12 to CodeReady Workspaces 2.13.

The method used to install the CodeReady Workspaces instance determines the method to proceed with for the upgrade:

5.1. Upgrading CodeReady Workspaces using OperatorHub

This section describes how to upgrade from an earlier minor version using the Operator from OperatorHub in the OpenShift web console.

OperatorHub supports Automatic and Manual upgrade strategies: Automatic:: The upgrade process starts when a new version of the Operator is published. Manual:: The update must be manually approved every time the new version of the Operator is published.

5.1.1. Specifying the approval strategy of CodeReady Workspaces in OperatorHub

Prerequisites

  • An administrator account on an instance of OpenShift.
  • An instance of CodeReady Workspaces 2.12 or earlier that was installed by using OperatorHub.

Procedure

  1. Open the OpenShift web console.
  2. Navigate to the Operators → Installed Operators page.
  3. Click Red Hat CodeReady Workspaces in the list of installed Operators.
  4. Navigate to the Subscription tab.

  5. Configure the approval strategy to Automatic or Manual.

    Specifying upgrade strategy screenshot

5.1.2. Manually upgrading CodeReady Workspaces in OperatorHub

OperatorHub is an assembly point for sharing Operators. The OperatorHub helps you deploy and update applications. The following section describes the process of upgrading CodeReady Workspaces by using OperatorHub and the Manual approval strategy approach. Use the Manual approval strategy to prevent automatic updates of the Operator with every release.

Prerequisites

  • An administrator account on an instance of OpenShift.
  • An instance of CodeReady Workspaces 2.12 or earlier that was installed by using OperatorHub.
  • The approval strategy in the subscription is Manual.

Procedure

  1. Open the OpenShift web console.
  2. Navigate to the Operators → Installed Operators page.
  3. In the list of the installed Operators, click Red Hat CodeReady Workspaces.
  4. Navigate to the Subscription tab.
  5. Next to the Upgrade Status, inspect the upgrades that require approval. The expected message is 1 requires approval.
  6. Click 1 requires approval.
  7. Click Preview Install Plan.
  8. Review the resources that are available for upgrade and click Approve.

Verification steps

  1. Navigate to the Operators → Installed Operators page.
  2. Monitor the upgrade progress. When complete, the status changes to Succeeded and Up to date. The 2.13 version number is visible at the end of the page.

Additional resources

5.2. Upgrading CodeReady Workspaces using the CLI management tool

This section describes how to upgrade from the previous minor version using the CLI management tool.

Prerequisites

  • An administrative account on OpenShift.
  • A running instance of a previous minor version of Red Hat CodeReady Workspaces, installed using the CLI management tool on the same instance of OpenShift, in the <openshift-workspaces> project.
  • crwctl is available and updated. See Section 3.3.1, “Installing the crwctl CLI management tool”.

Procedure

  1. Save and push changes back to the Git repositories for all running CodeReady Workspaces 2.12 workspaces.
  2. Shut down all workspaces in the CodeReady Workspaces 2.12 instance.

  3. Upgrade CodeReady Workspaces: 

    $ crwctl server:update -n openshift-workspaces
Note

For slow systems or internet connections, add the --k8spodwaittimeout=1800000 flag option to the crwctl server:update command to extend the Pod timeout period to 1800000 ms or longer.

Verification steps

  1. Navigate to the CodeReady Workspaces instance.
  2. The 2.13 version number is visible at the bottom of the page.

5.3. Upgrading CodeReady Workspaces using the CLI management tool in restricted environment

This section describes how to upgrade Red Hat CodeReady Workspaces using the CLI management tool in restricted environment. The upgrade path supports minor version update, from CodeReady Workspaces version 2.12 to version 2.13.

Prerequisites

5.3.1. Understanding network connectivity in restricted environments

CodeReady Workspaces requires that each OpenShift Route created for CodeReady Workspaces is accessible from inside the OpenShift cluster. These CodeReady Workspaces components have a OpenShift Route: codeready-workspaces-server, keycloak, devfile-registry, plugin-registry.

Consider the network topology of the environment to determine how best to accomplish this.

Example 5.1. Network owned by a company or an organization, disconnected from the public Internet

The network administrators must ensure that it is possible to route traffic bound from the cluster to OpenShift Route host names.

Example 5.2. Private subnetwork in a cloud provider

Create a proxy configuration allowing the traffic to leave the node to reach an external-facing Load Balancer.

5.3.2. Building offline registry images

5.3.2.1. Building an offline devfile registry image

This section describes how to build an offline devfile registry image. Starting workspaces without relying on resources from the outside Internet requires building this image. The image contains all sample projects referenced in devfiles as zip files.

Prerequisites:

Procedure

  1. Clone the devfile registry repository and check out the version to deploy: 

    $ git clone git@github.com:redhat-developer/codeready-workspaces.git
$ cd codeready-workspaces
$ git checkout crw-2.13-rhel-8

  2. Build an offline devfile registry image: 

    $ cd dependencies/che-devfile-registry
$ ./build.sh --organization <my-org> \
           --registry <my-registry> \
           --tag <my-tag> \
           --offline
    Note

    To display full options for the build.sh script, use the --help parameter.

Additional resources

5.3.2.2. Building an offline plug-in registry image

This section describes how to build an offline plug-in registry image. Starting workspaces without relying on resources from the outside Internet requires building this image. The image contains plug-in metadata and all plug-in or extension artifacts.

Prerequisites

  • Node.js 12.x
  • A running version of yarn. See Installing Yarn.
  • ./node_modules/.bin is in the PATH environment variable.
  • A running installation of podman or docker.

Procedure

  1. Clone the plug-in registry repository and check out the version to deploy: 

    $ git clone git@github.com:redhat-developer/codeready-workspaces.git
$ cd codeready-workspaces
$ git checkout crw-2.13-rhel-8

  2. Build offline plug-in registry image: 

    $ cd dependencies/che-plugin-registry
$ ./build.sh --organization <my-org> \
           --registry <my-registry> \
           --tag <my-tag> \
           --offline \
           --skip-digest-generation
    Note

    To display full options for the build.sh script, use the --help parameter.

Additional resources

5.3.3. Preparing an private registry

Prerequisites

  • The oc tool is available.
  • The skopeo tool, version 0.1.40 or later, is available.
  • The podman tool is available.
  • An image registry accessible from the OpenShift cluster and supporting the format of the V2 image manifest, schema version 2. Ensure you can push to it from a location having, at least temporarily, access to the internet.

Table 5.1. Placeholders used in examples

<source-image>

Full coordinates of the source image, including registry, organization, and digest.

<target-registry>

Host name and port of the target container-image registry.

<target-organization>

Organization in the target container-image registry

<target-image>

Image name and digest in the target container-image registry.

<target-user>

User name in the target container-image registry.

<target-password>

User password in the target container-image registry.

Procedure

  1. Log into the internal image registry: 

    $ podman login --username <user> --password <password> <target-registry>
    Note

    If you encounter an error, like x509: certificate signed by unknown authority, when attempting to push to the internal registry, try one of these workarounds:

    • add the OpenShift cluster’s certificate to /etc/containers/certs.d/<target-registry>
    • add the registry as an insecure registry by adding the following lines to the Podman configuration file located at /etc/containers/registries.conf: 
    [registries.insecure]
registries = ['<target-registry>']

  2. Copy images without changing their digest. Repeat this step for every image in the following table: 

    $ skopeo copy --all docker://<source-image> docker://<target-registry>/<target-organization>/<target-image>
    Note

    Table 5.2. Understanding the usage of the container-images from the prefix or keyword they include in their name

    UsagePrefix or keyword

    Essential

    not stacks-, plugin-, or -openj9-

    Workspaces

    stacks-, plugin-

    IBM Z and IBM Power Systems

    -openj9-

    Note

    Images suffixed with openj9 are the Eclipse OpenJ9 image equivalents of the OpenJDK images used on x86_64. IBM Power Systems and IBM Z use Eclipse OpenJ9 from IBM Semeru for better performance on those systems. See IBM Semeru Runtimes.

    Table 5.3. Images to copy in the private registry

    <source-image><target-image>

    registry.redhat.io/codeready-workspaces/backup-rhel8@sha256:86fa48f4bd48a9d3de78ea1a1c96c5e5f5d9fa614da021a06c735da8dfdf06a2

    backup-rhel8@sha256:86fa48f4bd48a9d3de78ea1a1c96c5e5f5d9fa614da021a06c735da8dfdf06a2

    registry.redhat.io/codeready-workspaces/configbump-rhel8@sha256:04eeff2c4767a267759d87a34032d6ff8f283e23b323b33a39a3ae4304d259aa

    configbump-rhel8@sha256:04eeff2c4767a267759d87a34032d6ff8f283e23b323b33a39a3ae4304d259aa

    registry.redhat.io/codeready-workspaces/crw-2-rhel8-operator@sha256:415dad894e8268c1c9836599b95eff87da5b87ff032d040fc0301d9e0daba30d

    crw-2-rhel8-operator@sha256:415dad894e8268c1c9836599b95eff87da5b87ff032d040fc0301d9e0daba30d

    registry.redhat.io/codeready-workspaces/dashboard-rhel8@sha256:20c11bfa817a94b000b886a5fbe88de304db1e263c00e97a8fe183357870c1aa

    dashboard-rhel8@sha256:20c11bfa817a94b000b886a5fbe88de304db1e263c00e97a8fe183357870c1aa

    registry.redhat.io/codeready-workspaces/devfileregistry-rhel8@sha256:95bb0ad3a8db800f7aff6e4049a1f1bfa1c705ebecca4ae2c9d1c5bf28d19052

    devfileregistry-rhel8@sha256:95bb0ad3a8db800f7aff6e4049a1f1bfa1c705ebecca4ae2c9d1c5bf28d19052

    registry.redhat.io/codeready-workspaces/jwtproxy-rhel8@sha256:53ba026ac971bc228b73f70880f0eec9971d683b7b4e17f841eee9ca3f2a4421

    jwtproxy-rhel8@sha256:53ba026ac971bc228b73f70880f0eec9971d683b7b4e17f841eee9ca3f2a4421

    registry.redhat.io/codeready-workspaces/machineexec-rhel8@sha256:3d453b099d33f8024e2f5a7b0ed312bebe5f9cc74d4e27b0e1b70d94aa8605d7

    machineexec-rhel8@sha256:3d453b099d33f8024e2f5a7b0ed312bebe5f9cc74d4e27b0e1b70d94aa8605d7

    registry.redhat.io/codeready-workspaces/plugin-java11-openj9-rhel8@sha256:90b7403f9833e393759bde7df0544518bb141ce7c0072217194b953a8d4b4f82

    plugin-java11-openj9-rhel8@sha256:90b7403f9833e393759bde7df0544518bb141ce7c0072217194b953a8d4b4f82

    registry.redhat.io/codeready-workspaces/plugin-java11-rhel8@sha256:eba0875477a9a116cf0e2697048cb586c9b32e90cf21ff4b3dfd70fab77c5fd0

    plugin-java11-rhel8@sha256:eba0875477a9a116cf0e2697048cb586c9b32e90cf21ff4b3dfd70fab77c5fd0

    registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:4dd576f6cfd6ef0355d577ce751175ad3ac21d53b1a6ce056c7df01169918aec

    plugin-java8-openj9-rhel8@sha256:4dd576f6cfd6ef0355d577ce751175ad3ac21d53b1a6ce056c7df01169918aec

    registry.redhat.io/codeready-workspaces/plugin-java8-rhel8@sha256:81548d8559fdc3ba3e2b1ec398f3bd94728e8e4037a4c3a180177f20c9704db9

    plugin-java8-rhel8@sha256:81548d8559fdc3ba3e2b1ec398f3bd94728e8e4037a4c3a180177f20c9704db9

    registry.redhat.io/codeready-workspaces/plugin-kubernetes-rhel8@sha256:b284a345abe28ecbeb51261bd99a89870f4a0b37fea4780e3e31d7e2a946936c

    plugin-kubernetes-rhel8@sha256:b284a345abe28ecbeb51261bd99a89870f4a0b37fea4780e3e31d7e2a946936c

    registry.redhat.io/codeready-workspaces/plugin-openshift-rhel8@sha256:7b176e808a370a7ea115652463a2035a324e1e5ab0286bc8091284ee005e47d4

    plugin-openshift-rhel8@sha256:7b176e808a370a7ea115652463a2035a324e1e5ab0286bc8091284ee005e47d4

    registry.redhat.io/codeready-workspaces/pluginbroker-artifacts-rhel8@sha256:bb471b89e7df1f2178bf0e2c75b5d71601e35555b31358138c9933391e5f00f0

    pluginbroker-artifacts-rhel8@sha256:bb471b89e7df1f2178bf0e2c75b5d71601e35555b31358138c9933391e5f00f0

    registry.redhat.io/codeready-workspaces/pluginbroker-metadata-rhel8@sha256:db2838f1a2a868d9f3e2b2f7eb9db12fe0e41a0e7bb053dbe11661b235b1db59

    pluginbroker-metadata-rhel8@sha256:db2838f1a2a868d9f3e2b2f7eb9db12fe0e41a0e7bb053dbe11661b235b1db59

    registry.redhat.io/codeready-workspaces/pluginregistry-rhel8@sha256:798931885554875fe728d1fe84bfed70c844902a1e67ce0d451ce82156ebca4c

    pluginregistry-rhel8@sha256:798931885554875fe728d1fe84bfed70c844902a1e67ce0d451ce82156ebca4c

    registry.redhat.io/codeready-workspaces/server-rhel8@sha256:090a78d53f9781fbd360bdf74a3e1bbf5f5e2189ec6ba7dbc772f299d99b5c4f

    server-rhel8@sha256:090a78d53f9781fbd360bdf74a3e1bbf5f5e2189ec6ba7dbc772f299d99b5c4f

    registry.redhat.io/codeready-workspaces/stacks-cpp-rhel8@sha256:b3c318ddf23e6fcdd8cc307b135a3e570a6787f97b51461daf94948ddddb6171

    stacks-cpp-rhel8@sha256:b3c318ddf23e6fcdd8cc307b135a3e570a6787f97b51461daf94948ddddb6171

    registry.redhat.io/codeready-workspaces/stacks-dotnet-rhel8@sha256:6f0534ca7f9727a57719f99fe02fe72557d814d28d7dc233de32bb0496422835

    stacks-dotnet-rhel8@sha256:6f0534ca7f9727a57719f99fe02fe72557d814d28d7dc233de32bb0496422835

    registry.redhat.io/codeready-workspaces/stacks-golang-rhel8@sha256:415c265e03a1f253fb5484139653a3363c7ad466263bf6ab3a9bd201369324cc

    stacks-golang-rhel8@sha256:415c265e03a1f253fb5484139653a3363c7ad466263bf6ab3a9bd201369324cc

    registry.redhat.io/codeready-workspaces/stacks-php-rhel8@sha256:3a6ff083fde5d262456c96b4752e3d802046ef14d9864f52aa31176aff18bcdd

    stacks-php-rhel8@sha256:3a6ff083fde5d262456c96b4752e3d802046ef14d9864f52aa31176aff18bcdd

    registry.redhat.io/codeready-workspaces/theia-endpoint-rhel8@sha256:ae77e83cdf64acd95c0558261c6e5a35049a894f39a7e1debfb709c3b976b262

    theia-endpoint-rhel8@sha256:ae77e83cdf64acd95c0558261c6e5a35049a894f39a7e1debfb709c3b976b262

    registry.redhat.io/codeready-workspaces/theia-rhel8@sha256:d9e2e5d0690874f8e9ff47c3badd533ac4addd2a54182ac8a5de3a34b0f1497a

    theia-rhel8@sha256:d9e2e5d0690874f8e9ff47c3badd533ac4addd2a54182ac8a5de3a34b0f1497a

    registry.redhat.io/codeready-workspaces/traefik-rhel8@sha256:a2d87970ffc0a191ce474a3ae7fd16da896e4c5fe7cbe91fcb5fc730fa3dd993

    traefik-rhel8@sha256:a2d87970ffc0a191ce474a3ae7fd16da896e4c5fe7cbe91fcb5fc730fa3dd993

    registry.redhat.io/devworkspace/devworkspace-rhel8-operator@sha256:e68ec2fe7ac27e59641bdfc7794ae99fdfaa60e5b6d0cc0e3f20ab3f7a31bc11

    devworkspacedevworkspace-rhel8-operator@sha256:e68ec2fe7ac27e59641bdfc7794ae99fdfaa60e5b6d0cc0e3f20ab3f7a31bc11

    registry.redhat.io/jboss-eap-7/eap-xp3-openj9-11-openshift-rhel8@sha256:44f82c43a730acbfb4ce2be81ca32197099c370eeb85cedbee3d1e89e9ac7684

    eap-xp3-openj9-11-openshift-rhel8@sha256:44f82c43a730acbfb4ce2be81ca32197099c370eeb85cedbee3d1e89e9ac7684

    registry.redhat.io/jboss-eap-7/eap-xp3-openjdk11-openshift-rhel8@sha256:3875b2ee2826a6d8134aa3b80ac0c8b5ebc4a7f718335d76dfc3461b79f93d19

    eap-xp3-openjdk11-openshift-rhel8@sha256:3875b2ee2826a6d8134aa3b80ac0c8b5ebc4a7f718335d76dfc3461b79f93d19

    registry.redhat.io/jboss-eap-7/eap74-openjdk8-openshift-rhel7@sha256:b4a113c4d4972d142a3c350e2006a2b297dc883f8ddb29a88db19c892358632d

    eap74-openjdk8-openshift-rhel7@sha256:b4a113c4d4972d142a3c350e2006a2b297dc883f8ddb29a88db19c892358632d

    registry.redhat.io/openshift4/ose-kube-rbac-proxy@sha256:86e5fa1fa294987114be200890c2e516501e424aee0fb98ece25c95e7716295b

    openshift4ose-kube-rbac-proxy@sha256:86e5fa1fa294987114be200890c2e516501e424aee0fb98ece25c95e7716295b

    registry.redhat.io/openshift4/ose-oauth-proxy@sha256:30692aed2508e0576f9769fedb87333ab027babda774a870edfbdf2b3ecabed0

    openshift4ose-oauth-proxy@sha256:30692aed2508e0576f9769fedb87333ab027babda774a870edfbdf2b3ecabed0

    registry.redhat.io/rh-sso-7/sso74-openj9-openshift-rhel8@sha256:db43655b39ef29a3a96f8d454a3f03cd750770473b8ac8cbe4b2bc10616029f6

    sso74-openj9-openshift-rhel8@sha256:db43655b39ef29a3a96f8d454a3f03cd750770473b8ac8cbe4b2bc10616029f6

    registry.redhat.io/rh-sso-7/sso74-openshift-rhel8@sha256:becab7360738f4fc637785698b4a1327de81b8443577ae432132d6f6435f593c

    sso74-openshift-rhel8@sha256:becab7360738f4fc637785698b4a1327de81b8443577ae432132d6f6435f593c

    registry.redhat.io/rhel8/postgresql-13@sha256:487183263b25ff4a0d68e97f17756aa9600ca640b20804ca34f19718e471f647

    postgresql-13@sha256:487183263b25ff4a0d68e97f17756aa9600ca640b20804ca34f19718e471f647

    registry.redhat.io/rhel8/postgresql-96@sha256:314747a4a64ac16c33ead6a34479dccf16b9a07abf440ea7eeef7cda4cd19e32

    postgresql-96@sha256:314747a4a64ac16c33ead6a34479dccf16b9a07abf440ea7eeef7cda4cd19e32

    registry.redhat.io/rhscl/mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73

    mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73

    registry.redhat.io/ubi8/ubi-minimal@sha256:c536d4c63253318fdfc1db499f8f4bb0881db7fbd6f3d1554b4d54c812f85cc7

    ubi8ubi-minimal@sha256:c536d4c63253318fdfc1db499f8f4bb0881db7fbd6f3d1554b4d54c812f85cc7

Verification steps

  • Verify the images have the same digests: 

    $ skopeo inspect docker://<source-image>
$ skopeo inspect docker://<target-registry>/<target-organization>/<target-image>

Additional resources

5.3.4. Upgrading CodeReady Workspaces using the CLI management tool in restricted environment

This section describes how to upgrade Red Hat CodeReady Workspaces using the CLI management tool in restricted environment.

Prerequisites

Procedure

  1. In all running workspaces in the CodeReady Workspaces 2.12 instance, save and push changes back to the Git repositories.
  2. Stop all workspaces in the CodeReady Workspaces 2.12 instance.

  3. Run the following command: 

    $ crwctl server:update --che-operator-image=<image-registry>/<organization>/crw-2-rhel8-operator:2.13 -n openshift-workspaces

Verification steps

  1. Navigate to the CodeReady Workspaces instance.
  2. The 2.13 version number is visible at the bottom of the page.
Note

For slow systems or internet connections, add the --k8spodwaittimeout=1800000 flag option to the crwctl server:update command to extend the Pod timeout period to 1800000 ms or longer.

5.4. Upgrading CodeReady Workspaces that uses project strategies other than 'per user'

This section describes how to upgrade CodeReady Workspaces that uses project strategies other than 'per user'.

CodeReady Workspaces intends to use Kubernetes secrets as a storage for all sensitive user data. One project per user simplifies the design of the workspaces. This is the reason why project strategies other than per user become deprecated. The deprecation process happens in two steps. In the First Step project strategies other than per user are allowed but not recommended. In the Second Step support for project strategies other than per user is going to be removed.

Note

No automated upgrade support exists between First Step and Second Step for the installations where project strategies other than per user are used without losing data.

Prerequisites

  • CodeReady Workspaces configured with the project strategies other than per user.
  • Intention to use CodeReady Workspaces configured with the per user namespace strategies per user.

5.4.1. Upgrading CodeReady Workspaces and backing up user data

Procedure

  1. Notify all CodeReady Workspaces users about the upcoming data wipe.

    Note

    To back up the data, you can commit workspace configuration to an SCM server and use factories to restore it later.

  2. Re-install CodeReady Workspaces with per user namespace strategy.

5.4.2. Upgrading CodeReady Workspaces and losing user data

When CodeReady Workspaces is upgraded and user data is not backed up, workspace configuration and user preferences are going to be preserved but all runtime data will be wiped out.

Procedure

  1. Notify all CodeReady Workspaces users about the upcoming data wipe.
  2. Change project strategy to per user.
Note

Upgrading without backing up user data has disadvantage. Original PVs with runtime data are going to be preserved and will no longer be used. This may lead to the waste of resources.

Additional resources