Chapter 5. Upgrading CodeReady Workspaces

This chapter describes how to upgrade a CodeReady Workspaces instance from version 2.6 to CodeReady Workspaces 2.7.

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 OpenShift instance.
  • An instance of an earlier minor version of CodeReady Workspaces, installed using the Operator from OperatorHub on the same instance of OpenShift.

Procedure

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

  4. Navigate to the Subscription tab and specify the approval strategy:

    • Approval: Automatic

      or

      Approval: Manual

      Specifying upgrade strategy screenshot

5.1.2. Manually upgrading CodeReady Workspaces in OperatorHub

Prerequisites

  • An administrator account on an OpenShift instance.
  • An instance of an earlier minor version of CodeReady Workspaces, installed using the Operator from OperatorHub on the same instance of OpenShift.
  • The approval strategy in the subscription is set to Manual.

Procedure

  1. Open the OpenShift web console.
  2. Navigate to the Operators → Installed Operators section.
  3. Click Red Hat CodeReady Workspaces in the list of the installed Operators.
  4. Navigate to the Subscription tab. Upgrades requiring approval are displayed next to Upgrade Status, for example 1 requires approval.
  5. Click 1 requires approval, then click Preview Install Plan.
  6. Review the resources that are listed as available for upgrade and click Approve.

Verification steps

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

Additional resources

5.2. Upgrading CodeReady Workspaces using the CLI management tool

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

Prerequisites

  • And administrative account on an OpenShift instance.
  • 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.
  • An installation of the crwctl 2.7 version management tool. See Section 3.3.1, “Installing the crwctl CLI management tool”.

Procedure

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

  3. Run the following command: 

    $ 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.7 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.6 to version 2.7.

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.7-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

  • NodeJS 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.7-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
    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-

    Table 5.3. Images to copy in the private registry

    <source-image><target-image>

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

    configbump-rhel8@sha256:30f61524365f0d36bbe1208df77dd5cbe75b3f9e5c979305566e46ccac139dac

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

    crw-2-rhel8-operator@sha256:df78dac12257c42910cc98e3cf7cafab628012c19b3e4104f85f0567346f45d9

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

    crw-2-rhel8-operator@sha256:df78dac12257c42910cc98e3cf7cafab628012c19b3e4104f85f0567346f45d9

    registry.redhat.io/codeready-workspaces/devfileregistry-rhel8@sha256:58e961fa91492fd13ccb2c39afb201431f187301a2a192ab683ee202c9fe8c55

    devfileregistry-rhel8@sha256:58e961fa91492fd13ccb2c39afb201431f187301a2a192ab683ee202c9fe8c55

    registry.redhat.io/codeready-workspaces/jwtproxy-rhel8@sha256:79783bfaedce74edcb9681baab0a33dd40268f721642c31ca5319b4b47219cb7

    jwtproxy-rhel8@sha256:79783bfaedce74edcb9681baab0a33dd40268f721642c31ca5319b4b47219cb7

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

    machineexec-rhel8@sha256:a493fcb94465bdbc2c61250a0cacd95b0b5bb46618e9b5fd49e5902341ed0fcd

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

    plugin-java11-openj9-rhel8@sha256:d7facc17f95bcfc23b32487346c82d2e23e6efe4d595a1b782e94f54aa636bbc

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

    plugin-java11-openj9-rhel8@sha256:d7facc17f95bcfc23b32487346c82d2e23e6efe4d595a1b782e94f54aa636bbc

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

    plugin-java11-openj9-rhel8@sha256:d7facc17f95bcfc23b32487346c82d2e23e6efe4d595a1b782e94f54aa636bbc

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

    plugin-java11-rhel8@sha256:641e223f5efbc32bab3461aa000e3a50a5dcca063331322158d1c959129ffd99

    registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:1e84507ef957ed0ad8384cdb2e3d9bbca51db128c7289bcfbc9da505d715bd75

    plugin-java8-openj9-rhel8@sha256:1e84507ef957ed0ad8384cdb2e3d9bbca51db128c7289bcfbc9da505d715bd75

    registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:1e84507ef957ed0ad8384cdb2e3d9bbca51db128c7289bcfbc9da505d715bd75

    plugin-java8-openj9-rhel8@sha256:1e84507ef957ed0ad8384cdb2e3d9bbca51db128c7289bcfbc9da505d715bd75

    registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:1e84507ef957ed0ad8384cdb2e3d9bbca51db128c7289bcfbc9da505d715bd75

    plugin-java8-openj9-rhel8@sha256:1e84507ef957ed0ad8384cdb2e3d9bbca51db128c7289bcfbc9da505d715bd75

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

    plugin-java8-rhel8@sha256:5b2df65e7ec4676a43b763b431744790a89acd5c6d197316b694693b58c19770

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

    plugin-kubernetes-rhel8@sha256:5821febf70c74ed560a372f990e9fab9baa47f659ef9450b7881072e3cb40399

    registry.redhat.io/codeready-workspaces/plugin-openshift-rhel8@sha256:7772bc9073e64713ebbfc1a950cc3cbe21ed7301c65f84bb509fa2b6e71fa81d

    plugin-openshift-rhel8@sha256:7772bc9073e64713ebbfc1a950cc3cbe21ed7301c65f84bb509fa2b6e71fa81d

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

    pluginbroker-artifacts-rhel8@sha256:dc191ef97b01d0afedab6ccdb8c303f32d046f7eccf9f452eb30e615f2a0bf0e

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

    pluginbroker-metadata-rhel8@sha256:dbd839715c80db641c1505a0fa6f96969cf8cc4aa8c4db95b40626f95854a525

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

    pluginregistry-rhel8@sha256:c9f48f247cff27280587aeff54cea5d8a27e0eb55c99a73726cd7d575db7fbcc

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

    server-rhel8@sha256:feb6c83be2b1e6edc56287d2c9ed66a82522a297f88b495aeddd0778fb9d1f57

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

    stacks-cpp-rhel8@sha256:4bc877635a0feae47d259a232cca84130dc1f36890f76e39f422024372830bcb

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

    stacks-dotnet-rhel8@sha256:a61038e596c0c6104ae86cf4c5af5c60a6126feefa6e6585c540de2c48b723a2

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

    stacks-golang-rhel8@sha256:4ecb4f5fe6917a0e54cdaa8bb8332a06472debc8a12e8c948d7abbb6e90a95f0

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

    stacks-php-rhel8@sha256:d07364b8556e2f6689fa59fafefbaad3bb8c63b47e3e51be59521d38816a13db

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

    theia-endpoint-rhel8@sha256:bbd5b5fce80594d68a266128f607176a2f392829b969deafd848306d90c265e3

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

    theia-rhel8@sha256:3713798c7f61c3863afd4f501806df2fe462d8e3be37ab9e572940bf7a6facc0

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

    traefik-rhel8@sha256:c7ab18087c660f35386268053f29ebd2dc55163d2fd7956f0fdc227938b136ed

    registry.redhat.io/jboss-eap-7/eap-xp1-openj9-11-openshift-rhel8@sha256:42d7a7264314b9ef8399bda08ea61362887e4c1a88addb4c4f9f3b5d9d3169ce

    eap-xp1-openj9-11-openshift-rhel8@sha256:42d7a7264314b9ef8399bda08ea61362887e4c1a88addb4c4f9f3b5d9d3169ce

    registry.redhat.io/jboss-eap-7/eap-xp1-openj9-11-openshift-rhel8@sha256:42d7a7264314b9ef8399bda08ea61362887e4c1a88addb4c4f9f3b5d9d3169ce

    eap-xp1-openj9-11-openshift-rhel8@sha256:42d7a7264314b9ef8399bda08ea61362887e4c1a88addb4c4f9f3b5d9d3169ce

    registry.redhat.io/jboss-eap-7/eap-xp1-openj9-11-openshift-rhel8@sha256:42d7a7264314b9ef8399bda08ea61362887e4c1a88addb4c4f9f3b5d9d3169ce

    eap-xp1-openj9-11-openshift-rhel8@sha256:42d7a7264314b9ef8399bda08ea61362887e4c1a88addb4c4f9f3b5d9d3169ce

    registry.redhat.io/jboss-eap-7/eap-xp1-openjdk11-openshift-rhel8@sha256:94e1cd4eb4196a358e301c1992663258c0016c80247f507fd1c39cf9a73da833

    eap-xp1-openjdk11-openshift-rhel8@sha256:94e1cd4eb4196a358e301c1992663258c0016c80247f507fd1c39cf9a73da833

    registry.redhat.io/jboss-eap-7/eap73-openjdk8-openshift-rhel7@sha256:24dea0cfc154a23c1aeb6b46ade182d0f981362f36b7e6fb9c7d8531ac639fe0

    eap73-openjdk8-openshift-rhel7@sha256:24dea0cfc154a23c1aeb6b46ade182d0f981362f36b7e6fb9c7d8531ac639fe0

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

    sso74-openj9-openshift-rhel8@sha256:9297414d1cad8f86871f240c1c0ae324f7d1a3285c22ac7dd878bfcf3c59a75f

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

    sso74-openj9-openshift-rhel8@sha256:9297414d1cad8f86871f240c1c0ae324f7d1a3285c22ac7dd878bfcf3c59a75f

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

    sso74-openshift-rhel8@sha256:c0045cd676e06eb17083a44c4b90b29b11ddb40e1fb6a7b651384cf0960f5158

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

    postgresql-96@sha256:5b5bf623d89deda89250f422d352b122bce9533b902b5474f9c63a9facc7a6f1

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

    mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73

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

    ubi8ubi-minimal@sha256:5cfbaf45ca96806917830c183e9f37df2e913b187aadb32e89fd83fa455ebaa6

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

  3. Run the following command: 

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

Verification steps

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