Chapter 5. Upgrading CodeReady Workspaces
This chapter describes how to upgrade a CodeReady Workspaces instance from version 2.9 to CodeReady Workspaces 2.10.
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
- Open the OpenShift web console.
- Navigate to the Operators → Installed Operators section.
- Click Red Hat CodeReady Workspaces in the list of the installed Operators.
Navigate to the Subscription tab and specify the approval strategy:
Approval:
Automatic
or
Approval:
Manual
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
- Open the OpenShift web console.
- Navigate to the Operators → Installed Operators section.
- Click Red Hat CodeReady Workspaces in the list of the installed Operators.
- Navigate to the Subscription tab. Upgrades requiring approval are displayed next to Upgrade Status, for example 1 requires approval.
- Click 1 requires approval, then click Preview Install Plan.
- Review the resources that are listed as available for upgrade and click Approve.
Verification steps
- 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.
- The 2.10 version number is visible at the bottom of the page.
Additional resources
- Upgrading installed Operators section in the OpenShift documentation.
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
- Save and push changes back to the Git repositories for all running CodeReady Workspaces 2.9 workspaces.
- Shut down all workspaces in the CodeReady Workspaces 2.9 instance.
Upgrade CodeReady Workspaces:
$ crwctl server:update -n openshift-workspaces
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
- Navigate to the CodeReady Workspaces instance.
- The 2.10 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.9 to version 2.10.
Prerequisites
- An administrative account on an instance of OpenShift.
-
A running instance version 2.9 of Red Hat CodeReady Workspaces, installed using the CLI management tool on the same instance of OpenShift, with the crwctl
--installer operator
method, in the<openshift-workspaces>
project. See Section 3.4, “Installing CodeReady Workspaces in a restricted environment”. -
The
crwctl
2.10 management tool is available. See Section 3.3.1, “Installing the crwctl CLI management tool”.
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.
Procedure
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.10-rhel-8
Build an offline devfile registry image:
$ cd dependencies/che-devfile-registry $ ./build.sh --organization <my-org> \ --registry <my-registry> \ --tag <my-tag> \ --offline
NoteTo 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 thePATH
environment variable. - A running installation of podman or docker.
Procedure
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.10-rhel-8
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
NoteTo 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
| Full coordinates of the source image, including registry, organization, and digest. |
| Host name and port of the target container-image registry. |
| Organization in the target container-image registry |
| Image name and digest in the target container-image registry. |
| User name in the target container-image registry. |
| User password in the target container-image registry. |
Procedure
Log into the internal image registry:
$ podman login --username <user> --password <password> <target-registry>
NoteIf 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>']
-
add the OpenShift cluster’s certificate to
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>
NoteTable 5.2. Understanding the usage of the container-images from the prefix or keyword they include in their name
Usage Prefix or keyword Essential
not
stacks-
,plugin-
, or-openj9-
Workspaces
stacks-
,plugin-
IBM Z and IBM Power Systems
-openj9-
NoteImages suffixed with
openj9
are theEclipse 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/configbump-rhel8@sha256:df90e683ef3141ea5e5ba77e4346285685be527a35073855c936c6237e91a1a8
configbump-rhel8@sha256:df90e683ef3141ea5e5ba77e4346285685be527a35073855c936c6237e91a1a8
registry.redhat.io/codeready-workspaces/crw-2-rhel8-operator@sha256:eac1db6b4008ba849d4bcab9acc8542806b2aeda8a5a5f4b3c56fb87129d8e54
crw-2-rhel8-operator@sha256:eac1db6b4008ba849d4bcab9acc8542806b2aeda8a5a5f4b3c56fb87129d8e54
registry.redhat.io/codeready-workspaces/dashboard-rhel8@sha256:d6911d22200677aa0116f4523d325e5630b300788ee55fd2ba3b709714901d34
dashboard-rhel8@sha256:d6911d22200677aa0116f4523d325e5630b300788ee55fd2ba3b709714901d34
registry.redhat.io/codeready-workspaces/devfileregistry-rhel8@sha256:1bbe4ccc6ad751bedcf30f6db38180a02730de32e36195be804e610ae2c636d7
devfileregistry-rhel8@sha256:1bbe4ccc6ad751bedcf30f6db38180a02730de32e36195be804e610ae2c636d7
registry.redhat.io/codeready-workspaces/devworkspace-controller-rhel8@sha256:ee3e6abf41fe504ef7c6c76a904542da0e22af242f2cd2007d3899e72fc17dab
devworkspace-controller-rhel8@sha256:ee3e6abf41fe504ef7c6c76a904542da0e22af242f2cd2007d3899e72fc17dab
registry.redhat.io/codeready-workspaces/devworkspace-rhel8@sha256:832ebf337003084ea649244b331bcc5442dae90f5ad5a0c83b2cc15e68b29fdf
devworkspace-rhel8@sha256:832ebf337003084ea649244b331bcc5442dae90f5ad5a0c83b2cc15e68b29fdf
registry.redhat.io/codeready-workspaces/jwtproxy-rhel8@sha256:c62c57ceb4b5f78eb62e43ee59e580e7df8cbe6e75a4e59ce344ea2c885c7129
jwtproxy-rhel8@sha256:c62c57ceb4b5f78eb62e43ee59e580e7df8cbe6e75a4e59ce344ea2c885c7129
registry.redhat.io/codeready-workspaces/machineexec-rhel8@sha256:56573ec2092ba1b4339e5ae9e9c128bb48c6ef08f95512fb7e12b6d732624899
machineexec-rhel8@sha256:56573ec2092ba1b4339e5ae9e9c128bb48c6ef08f95512fb7e12b6d732624899
registry.redhat.io/codeready-workspaces/plugin-java11-openj9-rhel8@sha256:adf7aedb113fda38db621f2660246ea011d5b25ce77734db406888545b194daf
plugin-java11-openj9-rhel8@sha256:adf7aedb113fda38db621f2660246ea011d5b25ce77734db406888545b194daf
registry.redhat.io/codeready-workspaces/plugin-java11-rhel8@sha256:f90e09397caa4dd5cd3476e495adfc0096272c0ba746a6e32215175c541ae058
plugin-java11-rhel8@sha256:f90e09397caa4dd5cd3476e495adfc0096272c0ba746a6e32215175c541ae058
registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:f3dd1d9b76591a9aaeb34c609150db0775443d7db2db5593135cf5c8ee8729f8
plugin-java8-openj9-rhel8@sha256:f3dd1d9b76591a9aaeb34c609150db0775443d7db2db5593135cf5c8ee8729f8
registry.redhat.io/codeready-workspaces/plugin-java8-rhel8@sha256:1f5ac84a66454ab4b7b31cb259d30d1a5675dd5a342c9c7dfc536846c8d9a9b1
plugin-java8-rhel8@sha256:1f5ac84a66454ab4b7b31cb259d30d1a5675dd5a342c9c7dfc536846c8d9a9b1
registry.redhat.io/codeready-workspaces/plugin-kubernetes-rhel8@sha256:82e5e4cc40a458b4ea3d7e070945532cbf6a2f3ae966a68b50fe4cd74348c283
plugin-kubernetes-rhel8@sha256:82e5e4cc40a458b4ea3d7e070945532cbf6a2f3ae966a68b50fe4cd74348c283
registry.redhat.io/codeready-workspaces/plugin-openshift-rhel8@sha256:00aeb2293b02a8875ca996b3b02cf7ece516fe5c254ce83ade8fa3648afb6a56
plugin-openshift-rhel8@sha256:00aeb2293b02a8875ca996b3b02cf7ece516fe5c254ce83ade8fa3648afb6a56
registry.redhat.io/codeready-workspaces/pluginbroker-artifacts-rhel8@sha256:0e6b054323fd8cfca3171fa5aaa25f48b1d4ebd098ca63e71d7f0a379e2a51a1
pluginbroker-artifacts-rhel8@sha256:0e6b054323fd8cfca3171fa5aaa25f48b1d4ebd098ca63e71d7f0a379e2a51a1
registry.redhat.io/codeready-workspaces/pluginbroker-metadata-rhel8@sha256:ca8ba32dd8c789cf4a384bf4bf1c63d845b370b7b1249dbbc0b7ebd1aab6437d
pluginbroker-metadata-rhel8@sha256:ca8ba32dd8c789cf4a384bf4bf1c63d845b370b7b1249dbbc0b7ebd1aab6437d
registry.redhat.io/codeready-workspaces/pluginregistry-rhel8@sha256:51f0aaf0f0967b7a986e8690b50a552a06a349cd2c24bfbfa1dbf6d7fb81f6e5
pluginregistry-rhel8@sha256:51f0aaf0f0967b7a986e8690b50a552a06a349cd2c24bfbfa1dbf6d7fb81f6e5
registry.redhat.io/codeready-workspaces/server-rhel8@sha256:591f23a2db6e6ced7bad91e33d2492bf796d8bad2f545dc17c79d23a39657b28
server-rhel8@sha256:591f23a2db6e6ced7bad91e33d2492bf796d8bad2f545dc17c79d23a39657b28
registry.redhat.io/codeready-workspaces/stacks-cpp-rhel8@sha256:4bd93c6fbd77acf07f2206fe76d9e8589f453aa219302c9b4ad0e80ca6180dce
stacks-cpp-rhel8@sha256:4bd93c6fbd77acf07f2206fe76d9e8589f453aa219302c9b4ad0e80ca6180dce
registry.redhat.io/codeready-workspaces/stacks-dotnet-rhel8@sha256:581d3da4bf1fe4467d688cd4390e958dc15f07b530845298c3fbcb18bfdc033a
stacks-dotnet-rhel8@sha256:581d3da4bf1fe4467d688cd4390e958dc15f07b530845298c3fbcb18bfdc033a
registry.redhat.io/codeready-workspaces/stacks-golang-rhel8@sha256:a4c848642e5cbd2e503915932c27342c94904763caa9085a866cb39c7e443335
stacks-golang-rhel8@sha256:a4c848642e5cbd2e503915932c27342c94904763caa9085a866cb39c7e443335
registry.redhat.io/codeready-workspaces/stacks-php-rhel8@sha256:a3fc9a39225136f735660830787fdb84531db4481665a26e5be21e4534b6bac0
stacks-php-rhel8@sha256:a3fc9a39225136f735660830787fdb84531db4481665a26e5be21e4534b6bac0
registry.redhat.io/codeready-workspaces/theia-endpoint-rhel8@sha256:e19ab58d0bb1b4f39ff3f66edd2138fed76b8feae5db78acee0e364936a73827
theia-endpoint-rhel8@sha256:e19ab58d0bb1b4f39ff3f66edd2138fed76b8feae5db78acee0e364936a73827
registry.redhat.io/codeready-workspaces/theia-rhel8@sha256:1e77ab29f9a72ce94ae40670499c3823048cfdb4fe7de0707adeffd7274f78c9
theia-rhel8@sha256:1e77ab29f9a72ce94ae40670499c3823048cfdb4fe7de0707adeffd7274f78c9
registry.redhat.io/codeready-workspaces/traefik-rhel8@sha256:983abe532ec2d8741d326dd3cd2a4678ba82a3d4e71d77f02bf39d92a8ba3303
traefik-rhel8@sha256:983abe532ec2d8741d326dd3cd2a4678ba82a3d4e71d77f02bf39d92a8ba3303
registry.redhat.io/jboss-eap-7/eap-xp2-openj9-11-openshift-rhel8@sha256:3f2de8176fb0b0e996fb1051d4244b4720014e0767b60e4b815ef0f7ec33dec9
eap-xp2-openj9-11-openshift-rhel8@sha256:3f2de8176fb0b0e996fb1051d4244b4720014e0767b60e4b815ef0f7ec33dec9
registry.redhat.io/jboss-eap-7/eap-xp2-openjdk11-openshift-rhel8@sha256:647d092383a760edc083eafb2d7bc3208d6409097281bedbd5eaccde360e7e39
eap-xp2-openjdk11-openshift-rhel8@sha256:647d092383a760edc083eafb2d7bc3208d6409097281bedbd5eaccde360e7e39
registry.redhat.io/jboss-eap-7/eap73-openjdk8-openshift-rhel7@sha256:d16cfe30eaf20a157cd5d5980a6c34f3fcbcfd2fd225e670a0138d81007dd919
eap73-openjdk8-openshift-rhel7@sha256:d16cfe30eaf20a157cd5d5980a6c34f3fcbcfd2fd225e670a0138d81007dd919
registry.redhat.io/rh-sso-7/sso74-openj9-openshift-rhel8@sha256:eb5110c22109412b5101f95d353603c7e3080844ee48f89186f139be5b5faa42
sso74-openj9-openshift-rhel8@sha256:eb5110c22109412b5101f95d353603c7e3080844ee48f89186f139be5b5faa42
registry.redhat.io/rh-sso-7/sso74-openshift-rhel8@sha256:05f97328bafa615ceca025a6a93051a1ecdc08ae6123a78bf6ce56096f2ad233
sso74-openshift-rhel8@sha256:05f97328bafa615ceca025a6a93051a1ecdc08ae6123a78bf6ce56096f2ad233
registry.redhat.io/rhel8/postgresql-96@sha256:33643fb4cafffacb277982c6098b561aa80c06210e77d2badebef405ee953e43
postgresql-96@sha256:33643fb4cafffacb277982c6098b561aa80c06210e77d2badebef405ee953e43
registry.redhat.io/rhscl/mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73
mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73
registry.redhat.io/ubi8/ubi-minimal@sha256:d9b92ea78e76300968f5c9a4a04c2cf220a0bbfac667f77e5e7287692163d898
ubi8ubi-minimal@sha256:d9b92ea78e76300968f5c9a4a04c2cf220a0bbfac667f77e5e7287692163d898
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
-
To find the sources of the images list, see the values of the
relatedImages
attribute in the link: - CodeReady Workspaces Operator ClusterServiceVersion sources.
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
- An administrative account on an OpenShift instance.
-
A running instance version 2.9 of Red Hat CodeReady Workspaces, installed using the CLI management tool on the same instance of OpenShift, with the crwctl
--installer operator
method, in the<openshift-workspaces>
project. See Section 3.4, “Installing CodeReady Workspaces in a restricted environment”. - Essential container images are available to the CodeReady Workspaces server running in the cluster. See Section 5.3.3, “Preparing an private registry”.
-
The
crwctl
2.10 management tool is available. See Section 3.3.1, “Installing the crwctl CLI management tool”.
Procedure
- In all running workspaces in the CodeReady Workspaces 2.9 instance, save and push changes back to the Git repositories.
- Stop all workspaces in the CodeReady Workspaces 2.9 instance.
Run the following command:
$ crwctl server:update --che-operator-image=<image-registry>/<organization>/crw-2-rhel8-operator:2.10 -n openshift-workspaces
- <image-registry>: A host name and a port of the container-image registry accessible in the restricted environment.
- <organization>: An organization of the container-image registry. See: Section 5.3.3, “Preparing an private registry”.
Verification steps
- Navigate to the CodeReady Workspaces instance.
- The 2.10 version number is visible at the bottom of the page.
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.
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 strategiesper user
.
5.4.1. Upgrading CodeReady Workspaces and backing up user data
Procedure
Notify all CodeReady Workspaces users about the upcoming data wipe.
NoteTo back up the data, you can commit workspace configuration to an SCM server and use factories to restore it later.
-
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
- Notify all CodeReady Workspaces users about the upcoming data wipe.
-
Change project strategy to
per user
.
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.