Chapter 5. Upgrading CodeReady Workspaces
This chapter describes how to upgrade a CodeReady Workspaces instance from version 2.10 to CodeReady Workspaces 2.11.
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.11 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.10 workspaces.
- Shut down all workspaces in the CodeReady Workspaces 2.10 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.11 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.10 to version 2.11.
Prerequisites
- An administrative account on an instance of OpenShift.
-
A running instance version 2.10 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.11 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.11-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.11-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:20fd31c45d769526d45eaf6738a6d4af1520a844126a2a2e510c304a81b7249a
configbump-rhel8@sha256:20fd31c45d769526d45eaf6738a6d4af1520a844126a2a2e510c304a81b7249a
registry.redhat.io/codeready-workspaces/crw-2-rhel8-operator@sha256:a41f7b950c5131a6bc08b1e094db2da9b784e6083ddaa4aa68512f3947798702
crw-2-rhel8-operator@sha256:a41f7b950c5131a6bc08b1e094db2da9b784e6083ddaa4aa68512f3947798702
registry.redhat.io/codeready-workspaces/dashboard-rhel8@sha256:1c37bdffae8cdc154d88b94ab38e868f7e33486c81b6c3bded36dfdfd85b81a4
dashboard-rhel8@sha256:1c37bdffae8cdc154d88b94ab38e868f7e33486c81b6c3bded36dfdfd85b81a4
registry.redhat.io/codeready-workspaces/devfileregistry-rhel8@sha256:b164968dbd52c72f39533bec4efd3ad3cce3acb6060495e472dd9c3f2908fbbc
devfileregistry-rhel8@sha256:b164968dbd52c72f39533bec4efd3ad3cce3acb6060495e472dd9c3f2908fbbc
registry.redhat.io/codeready-workspaces/devworkspace-controller-rhel8@sha256:c88242524a9074a58bc7d20cb8411d37e7e752358ab80366533b8165bb9f95b0
devworkspace-controller-rhel8@sha256:c88242524a9074a58bc7d20cb8411d37e7e752358ab80366533b8165bb9f95b0
registry.redhat.io/codeready-workspaces/devworkspace-rhel8@sha256:c18f166f570ca572c94472b7a3bd5127b48521e777ea09dcad6f78ad66cd7a13
devworkspace-rhel8@sha256:c18f166f570ca572c94472b7a3bd5127b48521e777ea09dcad6f78ad66cd7a13
registry.redhat.io/codeready-workspaces/jwtproxy-rhel8@sha256:44acafb02cce3d3fe8b57da2e27547b502c4088624935ffe7f3aa06a55d08bba
jwtproxy-rhel8@sha256:44acafb02cce3d3fe8b57da2e27547b502c4088624935ffe7f3aa06a55d08bba
registry.redhat.io/codeready-workspaces/machineexec-rhel8@sha256:bfdd8cf61a6fad757f1e8334aa84dbf44baddf897ff8def7496bf6dbc066679d
machineexec-rhel8@sha256:bfdd8cf61a6fad757f1e8334aa84dbf44baddf897ff8def7496bf6dbc066679d
registry.redhat.io/codeready-workspaces/plugin-java11-openj9-rhel8@sha256:8d9930cd3c0b2fa72a6c0d880b4d0b330b1a7a51491f09175134dcc79f2cb376
plugin-java11-openj9-rhel8@sha256:8d9930cd3c0b2fa72a6c0d880b4d0b330b1a7a51491f09175134dcc79f2cb376
registry.redhat.io/codeready-workspaces/plugin-java11-rhel8@sha256:d0337762e71fd4badabcb38a582b2f35e7e7fc1c9c0f2e841e339d45b7bd34ed
plugin-java11-rhel8@sha256:d0337762e71fd4badabcb38a582b2f35e7e7fc1c9c0f2e841e339d45b7bd34ed
registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:d7ec33ce2fa61a06fade63e2b516409c465bd5516030dd482e2f4bdb2d676c9f
plugin-java8-openj9-rhel8@sha256:d7ec33ce2fa61a06fade63e2b516409c465bd5516030dd482e2f4bdb2d676c9f
registry.redhat.io/codeready-workspaces/plugin-java8-rhel8@sha256:b2ceb0039c763e6a38aa370157b476ecb08faf8b2bfb680bada774e149583d62
plugin-java8-rhel8@sha256:b2ceb0039c763e6a38aa370157b476ecb08faf8b2bfb680bada774e149583d62
registry.redhat.io/codeready-workspaces/plugin-kubernetes-rhel8@sha256:45535630e37e3e317772f36b28b47859d32ad1e82505a796139682cdbefb03b8
plugin-kubernetes-rhel8@sha256:45535630e37e3e317772f36b28b47859d32ad1e82505a796139682cdbefb03b8
registry.redhat.io/codeready-workspaces/plugin-openshift-rhel8@sha256:d2384cafc870c497913168508be0d846412c68ace9724baa37ca3c6be9aa4772
plugin-openshift-rhel8@sha256:d2384cafc870c497913168508be0d846412c68ace9724baa37ca3c6be9aa4772
registry.redhat.io/codeready-workspaces/pluginbroker-artifacts-rhel8@sha256:a9bf68e6dabbaaaf3e97afe4ac6e97a317e8fd9c05c88e5801fbf01aaa1ebb99
pluginbroker-artifacts-rhel8@sha256:a9bf68e6dabbaaaf3e97afe4ac6e97a317e8fd9c05c88e5801fbf01aaa1ebb99
registry.redhat.io/codeready-workspaces/pluginbroker-metadata-rhel8@sha256:727f80af1e1f6054ac93cad165bc392f43c951681936b979b98003e06e759643
pluginbroker-metadata-rhel8@sha256:727f80af1e1f6054ac93cad165bc392f43c951681936b979b98003e06e759643
registry.redhat.io/codeready-workspaces/pluginregistry-rhel8@sha256:5d19f7c5c0417940c52e552c51401f729b9ec16868013e016d7b80342cd8de4e
pluginregistry-rhel8@sha256:5d19f7c5c0417940c52e552c51401f729b9ec16868013e016d7b80342cd8de4e
registry.redhat.io/codeready-workspaces/server-rhel8@sha256:e79e0a462b4dd47ecaac2f514567287c44e32437496b2c214ebc2bc0055c4aa9
server-rhel8@sha256:e79e0a462b4dd47ecaac2f514567287c44e32437496b2c214ebc2bc0055c4aa9
registry.redhat.io/codeready-workspaces/stacks-cpp-rhel8@sha256:31ef0774342bc1dbcd91e3b85d68d7a28846500f04ace7a5dfa3116c0cedfeb1
stacks-cpp-rhel8@sha256:31ef0774342bc1dbcd91e3b85d68d7a28846500f04ace7a5dfa3116c0cedfeb1
registry.redhat.io/codeready-workspaces/stacks-dotnet-rhel8@sha256:6ca14e5a94a98b15f39a353e533cf659b2b3937a86bd51af175dc3eadd8b80d5
stacks-dotnet-rhel8@sha256:6ca14e5a94a98b15f39a353e533cf659b2b3937a86bd51af175dc3eadd8b80d5
registry.redhat.io/codeready-workspaces/stacks-golang-rhel8@sha256:30e71577cb80ffaf1f67a292b4c96ab74108a2361347fc593cbb505784629db2
stacks-golang-rhel8@sha256:30e71577cb80ffaf1f67a292b4c96ab74108a2361347fc593cbb505784629db2
registry.redhat.io/codeready-workspaces/stacks-php-rhel8@sha256:bb7f7ef0ce58695aaf29b3355dd9ee187a94d1d382f68f329f9664ca01772ba2
stacks-php-rhel8@sha256:bb7f7ef0ce58695aaf29b3355dd9ee187a94d1d382f68f329f9664ca01772ba2
registry.redhat.io/codeready-workspaces/theia-endpoint-rhel8@sha256:abb4f4c8e1328ea9fc5ca4fe0c809ec007fe348e3d2ccd722e5ba75c02ff448f
theia-endpoint-rhel8@sha256:abb4f4c8e1328ea9fc5ca4fe0c809ec007fe348e3d2ccd722e5ba75c02ff448f
registry.redhat.io/codeready-workspaces/theia-rhel8@sha256:5ed38a48d18577120993cd3b673a365e31aeb4265c5b4a95dd9d0ac747260392
theia-rhel8@sha256:5ed38a48d18577120993cd3b673a365e31aeb4265c5b4a95dd9d0ac747260392
registry.redhat.io/codeready-workspaces/traefik-rhel8@sha256:6704bd086f0d971ecedc1dd6dc7a90429231fdfa86579e742705b31cbedbd8b2
traefik-rhel8@sha256:6704bd086f0d971ecedc1dd6dc7a90429231fdfa86579e742705b31cbedbd8b2
registry.redhat.io/jboss-eap-7/eap-xp3-openj9-11-openshift-rhel8@sha256:53684e34b0dbe8560d2c330b0761b3eb17982edc1c947a74c36d29805bda6736
eap-xp3-openj9-11-openshift-rhel8@sha256:53684e34b0dbe8560d2c330b0761b3eb17982edc1c947a74c36d29805bda6736
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/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:ed53ca7b191432f7cf9da0fd8629d7de14ade609ca5f38aba443716f83616f2e
postgresql-96@sha256:ed53ca7b191432f7cf9da0fd8629d7de14ade609ca5f38aba443716f83616f2e
registry.redhat.io/rhscl/mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73
mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73
registry.redhat.io/ubi8/ubi-minimal@sha256:31ccb79b1b2c2d6eff1bee0db23d5b8ab598eafd6238417d9813f1346f717c11
ubi8ubi-minimal@sha256:31ccb79b1b2c2d6eff1bee0db23d5b8ab598eafd6238417d9813f1346f717c11
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.10 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.11 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.10 instance, save and push changes back to the Git repositories.
- Stop all workspaces in the CodeReady Workspaces 2.10 instance.
Run the following command:
$ crwctl server:update --che-operator-image=<image-registry>/<organization>/crw-2-rhel8-operator:2.11 -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.11 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.