Chapter 5. Upgrading CodeReady Workspaces

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

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.11 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.11 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.12 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.11 workspaces.
  2. Shut down all workspaces in the CodeReady Workspaces 2.11 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.12 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.11 to version 2.12.

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.12-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.12-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 for better performance on those systems.

    Table 5.3. Images to copy in the private registry

    <source-image><target-image>

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

    backup-rhel8@sha256:fcf0e843868889f9125b5bee63b6456d08095004ccacb4e5c63e7a0c020e7ca3

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

    configbump-rhel8@sha256:c833b59bdc7022883cd71f6b72e457d8a2fae9d25ac9b45eec2f9501ec89c380

    registry.redhat.io/codeready-workspaces/crw-2-rhel8-operator@sha256:50bb42c6b5d38c4af5f620a44e8681656383d67a557b6a66af3ffdb51846677e

    crw-2-rhel8-operator@sha256:50bb42c6b5d38c4af5f620a44e8681656383d67a557b6a66af3ffdb51846677e

    registry.redhat.io/codeready-workspaces/dashboard-rhel8@sha256:4a5a51764cb7f4eb3aab8f089826738d46ed40f6ec263d0697ae9f28107af06f

    dashboard-rhel8@sha256:4a5a51764cb7f4eb3aab8f089826738d46ed40f6ec263d0697ae9f28107af06f

    registry.redhat.io/codeready-workspaces/devfileregistry-rhel8@sha256:40448eb12f3af94efe8b78120995b204cb983f2f9b66f795cf2b68dd67e45cf7

    devfileregistry-rhel8@sha256:40448eb12f3af94efe8b78120995b204cb983f2f9b66f795cf2b68dd67e45cf7

    registry.redhat.io/codeready-workspaces/jwtproxy-rhel8@sha256:82f553706c8c809c589b4169ccb7858569e746e0f06d23e414dd47442ab119ad

    jwtproxy-rhel8@sha256:82f553706c8c809c589b4169ccb7858569e746e0f06d23e414dd47442ab119ad

    registry.redhat.io/codeready-workspaces/machineexec-rhel8@sha256:93dc77a7f33171b36dbc112e7e732da4044c4c75a48b7a25907521c529170c0c

    machineexec-rhel8@sha256:93dc77a7f33171b36dbc112e7e732da4044c4c75a48b7a25907521c529170c0c

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

    plugin-java11-openj9-rhel8@sha256:ff81f7332ae1fed4c84fa9f47921173a754624ef3e019fcd71a5192491857866

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

    plugin-java11-rhel8@sha256:f06f983d5e49a1ab05b9de54e449b2033688e7a38a6c57550f2ed87b3bef3fe2

    registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:712968392395b940f18c586ee6fe9c50037be70813e099189ff24bc0767057fb

    plugin-java8-openj9-rhel8@sha256:712968392395b940f18c586ee6fe9c50037be70813e099189ff24bc0767057fb

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

    plugin-java8-rhel8@sha256:c451114be8be1ff012a85eae983d85216d0171dfc1376df1c410f54af0226bc2

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

    plugin-kubernetes-rhel8@sha256:3e43ffa6757980fb0f092798b76d6bbfa63768c72d2f071b666f6401b6c0df5c

    registry.redhat.io/codeready-workspaces/plugin-openshift-rhel8@sha256:55e67c70b3b04e045230bf553e2394920d088027aad6eb5ce0a21abede138af5

    plugin-openshift-rhel8@sha256:55e67c70b3b04e045230bf553e2394920d088027aad6eb5ce0a21abede138af5

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

    pluginbroker-artifacts-rhel8@sha256:3436bacdc249e8dcc289b67e89340bdc2c5b6694304fe369af751f684a140d60

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

    pluginbroker-metadata-rhel8@sha256:e709e89bd1ab1612baad039ad6b824b027a070ff0a37be3395202faa55518e09

    registry.redhat.io/codeready-workspaces/pluginregistry-rhel8@sha256:7522baa5b8798bf98d9aad17d08dc34799cc5e33133af5b63179266c1b4dfb52

    pluginregistry-rhel8@sha256:7522baa5b8798bf98d9aad17d08dc34799cc5e33133af5b63179266c1b4dfb52

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

    server-rhel8@sha256:ae26042c25464990d626f2de586d47c7f8077444b48b29792bc9c2c45d739313

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

    stacks-cpp-rhel8@sha256:5ae3c3fcef5050ca30126d55229fe3334e887c658d6e5fbe9ef6aa8339dfc89e

    registry.redhat.io/codeready-workspaces/stacks-dotnet-rhel8@sha256:68875b794b80d9590fceff2e35eaa8f0ac47cd9e8f183f54652a1d1703024dd8

    stacks-dotnet-rhel8@sha256:68875b794b80d9590fceff2e35eaa8f0ac47cd9e8f183f54652a1d1703024dd8

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

    stacks-golang-rhel8@sha256:a007380852029dcb01f2a00956f4e2b26c9c53d2063eca92d41d56fff4e83a27

    registry.redhat.io/codeready-workspaces/stacks-php-rhel8@sha256:193b9775d58e1f7d9a45607b23bbfea4cfcba53356872da3e28de3ee9a8254e5

    stacks-php-rhel8@sha256:193b9775d58e1f7d9a45607b23bbfea4cfcba53356872da3e28de3ee9a8254e5

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

    theia-endpoint-rhel8@sha256:2eb5fd69e08e3a1a8f557fe1d41170ee9dac89d15c5947aabc477d4e2107a9ea

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

    theia-rhel8@sha256:7c1fcf0a972e2905a0758d53e2155534643d0fbcbb688d57b54f05bafe323582

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

    traefik-rhel8@sha256:012b6d04e2c3ed30e34d95f3566a7ccdaa2e696b33d77f7622405149c21d9a6f

    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:896c1a9baf21400e8bc75e8b7fb22fc3a829aa3fee68ca9f8373111b7c21e27d

    eap-xp3-openj9-11-openshift-rhel8@sha256:896c1a9baf21400e8bc75e8b7fb22fc3a829aa3fee68ca9f8373111b7c21e27d

    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:bd74f0b95ff2881faf6eb4520feecd067b69a759f09bbfecd467447ce2a2a25e

    openshift4ose-kube-rbac-proxy@sha256:bd74f0b95ff2881faf6eb4520feecd067b69a759f09bbfecd467447ce2a2a25e

    registry.redhat.io/openshift4/ose-oauth-proxy@sha256:7e14b5d357940f2e5e72a41f2a289c7b2757b64abf96a71f54f5829621730f84

    openshift4ose-oauth-proxy@sha256:7e14b5d357940f2e5e72a41f2a289c7b2757b64abf96a71f54f5829621730f84

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

    sso74-openj9-openshift-rhel8@sha256:4ff9d6342dfd3b85234ea554b92867c649744ece9aa7f8751aae06bf9d2d324c

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

    sso74-openshift-rhel8@sha256:b98f0b743dd406be726d8ba8c0437ed5228c7064015c1d48ef5f87eb365522bc

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

    postgresql-96@sha256:e8177c5de05ccdd6d12e360b65c63c889b2de725d573ffdedd8914230b118639

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

    mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73

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

    ubi8ubi-minimal@sha256:54ef2173bba7384dc7609e8affbae1c36f8a3ec137cacc0866116d65dd4b9afe

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.11 instance, save and push changes back to the Git repositories.
  2. Stop all workspaces in the CodeReady Workspaces 2.11 instance.

  3. Run the following command: 

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

Verification steps

  1. Navigate to the CodeReady Workspaces instance.
  2. The 2.12 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