Chapter 5. Upgrading CodeReady Workspaces
This chapter describes how to upgrade a CodeReady Workspaces instance from version 2.3 to CodeReady Workspaces 2.4.
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 a previous minor version using the Operator from OperatorHub in the OpenShift web console.
Prerequisites
- An administrator account on an OpenShift instance.
- An instance of a previous 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 enable the following options:
-
Channel:
latest
-
Approval:
Automatic
-
Channel:
Verification steps
- Navigate to the CodeReady Workspaces instance.
- The 2.4 version number is visible at the bottom of the page.
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.4 version management tool. See Section 3.2.1, “Installing the crwctl CLI management tool”.
Procedure
- In all running workspaces in the CodeReady Workspaces 2.3 instance, save and push changes back to the Git repositories.
- Shut down all workspaces in the CodeReady Workspaces 2.3 instance.
Run the following command:
$ crwctl -n <openshift-workspaces> server:update
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.4 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.3 to version 2.4.
Prerequisites
- An administrative account on an instance of OpenShift.
-
A running instance version 2.3 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.3, “Installing CodeReady Workspaces in a restricted enviroment”. -
The
crwctl
2.4 management tool is available. See Section 3.2.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. Preparing a 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>
TipIf you meet an error, such as
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-openj-
Workspaces
stacks-
,plugin-
Z and Power
-openj-
Table 5.3. Images to copy in the private registry
<source-image> <target-image> registry.redhat.io/codeready-workspaces/crw-2-rhel8-operator@sha256:89763ddec38a5925a052fa7ea75fc5a0db39124cada1e2d33b6eba3e32e8a7c6
crw-2-rhel8-operator@sha256:89763ddec38a5925a052fa7ea75fc5a0db39124cada1e2d33b6eba3e32e8a7c6
registry.redhat.io/codeready-workspaces/devfileregistry-rhel8@sha256:7702adb0ed28b635e45804e87fe5dd98bdd3aa766fed7845a8ce509b91c22e36
devfileregistry-rhel8@sha256:7702adb0ed28b635e45804e87fe5dd98bdd3aa766fed7845a8ce509b91c22e36
registry.redhat.io/codeready-workspaces/jwtproxy-rhel8@sha256:8afecd5b0edc7734532ee76ff9eac1fc4814d8aaa6c9be440a2a88a20c014e4e
jwtproxy-rhel8@sha256:8afecd5b0edc7734532ee76ff9eac1fc4814d8aaa6c9be440a2a88a20c014e4e
registry.redhat.io/codeready-workspaces/machineexec-rhel8@sha256:c9bebc895e5fa5a0bd4ecaedfd5384ab75a45a96b6314ba5d4a6f4c1e8e109f9
machineexec-rhel8@sha256:c9bebc895e5fa5a0bd4ecaedfd5384ab75a45a96b6314ba5d4a6f4c1e8e109f9
registry.redhat.io/codeready-workspaces/plugin-java11-openj9-rhel8@sha256:27a71612f9bd3bee77adb4e164c44c61cf5085458d592215b2fe74c55d11abc6
plugin-java11-openj9-rhel8@sha256:27a71612f9bd3bee77adb4e164c44c61cf5085458d592215b2fe74c55d11abc6
registry.redhat.io/codeready-workspaces/plugin-java11-rhel8@sha256:e9deebbc320d28a2f425e858ed3dcf87fc67a40f6654d6eb7c2b6feea022b7d6
plugin-java11-rhel8@sha256:e9deebbc320d28a2f425e858ed3dcf87fc67a40f6654d6eb7c2b6feea022b7d6
registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:14f2774e92b70d85280e506f81e2ea9a89c26490fd53a4421df8a694bd944d2d
plugin-java8-openj9-rhel8@sha256:14f2774e92b70d85280e506f81e2ea9a89c26490fd53a4421df8a694bd944d2d
registry.redhat.io/codeready-workspaces/plugin-java8-rhel8@sha256:d04f70c8340abaee1a282b77158d054f4faf2225bc17c79aafb413396c367782
plugin-java8-rhel8@sha256:d04f70c8340abaee1a282b77158d054f4faf2225bc17c79aafb413396c367782
registry.redhat.io/codeready-workspaces/plugin-kubernetes-rhel8@sha256:d87aed64704369a50d1e54a57815b699f74d4efad1401d1a638808e655a37e48
plugin-kubernetes-rhel8@sha256:d87aed64704369a50d1e54a57815b699f74d4efad1401d1a638808e655a37e48
registry.redhat.io/codeready-workspaces/plugin-openshift-rhel8@sha256:9c43a02b0dd0f66744359c5ccdb1f1780ecd92c3dc31b14d73b553ba763af8ab
plugin-openshift-rhel8@sha256:9c43a02b0dd0f66744359c5ccdb1f1780ecd92c3dc31b14d73b553ba763af8ab
registry.redhat.io/codeready-workspaces/pluginbroker-artifacts-rhel8@sha256:d0eebf2c8b460adb75dc6bc5200aa9fd40d030b7b17c6b1c3b9d3c879f4652ee
pluginbroker-artifacts-rhel8@sha256:d0eebf2c8b460adb75dc6bc5200aa9fd40d030b7b17c6b1c3b9d3c879f4652ee
registry.redhat.io/codeready-workspaces/pluginbroker-metadata-rhel8@sha256:cff23432d1d397bbbc7df65be9d6ddf4a97a3ef1801708bb7bb7d2fa72dbcce3
pluginbroker-metadata-rhel8@sha256:cff23432d1d397bbbc7df65be9d6ddf4a97a3ef1801708bb7bb7d2fa72dbcce3
registry.redhat.io/codeready-workspaces/pluginregistry-rhel8@sha256:9f37917122c20fc83e6558a5484efab42650958b513a22920f449f948e50cd51
pluginregistry-rhel8@sha256:9f37917122c20fc83e6558a5484efab42650958b513a22920f449f948e50cd51
registry.redhat.io/codeready-workspaces/server-rhel8@sha256:63bf304cd04576048012693e7e8544a5a703790f99551554a75798bc799b112b
server-rhel8@sha256:63bf304cd04576048012693e7e8544a5a703790f99551554a75798bc799b112b
registry.redhat.io/codeready-workspaces/stacks-cpp-rhel8@sha256:56543cfeeeac030821557ac4937db40f6845e874193c79c30267a680f9b2cbe7
stacks-cpp-rhel8@sha256:56543cfeeeac030821557ac4937db40f6845e874193c79c30267a680f9b2cbe7
registry.redhat.io/codeready-workspaces/stacks-dotnet-rhel8@sha256:13628110b96de0e516ff2dfa29cdcaee64cd8f8978052c8160c294c332dba9f0
stacks-dotnet-rhel8@sha256:13628110b96de0e516ff2dfa29cdcaee64cd8f8978052c8160c294c332dba9f0
registry.redhat.io/codeready-workspaces/stacks-golang-rhel8@sha256:fef91718ccebc4cd9b89999f6b5df83bf3d60fce657f6f44eda092100549af2c
stacks-golang-rhel8@sha256:fef91718ccebc4cd9b89999f6b5df83bf3d60fce657f6f44eda092100549af2c
registry.redhat.io/codeready-workspaces/stacks-php-rhel8@sha256:b75f498954fbe858c74f80a89d132ba3560f40c0f697b0cd9550ed5663078ef6
stacks-php-rhel8@sha256:b75f498954fbe858c74f80a89d132ba3560f40c0f697b0cd9550ed5663078ef6
registry.redhat.io/codeready-workspaces/theia-endpoint-rhel8@sha256:942e1e6328169508e3fff8fd96c575d7a423339ced17dbf5813d61d1971adaef
theia-endpoint-rhel8@sha256:942e1e6328169508e3fff8fd96c575d7a423339ced17dbf5813d61d1971adaef
registry.redhat.io/codeready-workspaces/theia-rhel8@sha256:78edc9f75680cbe7f63774d9dfbbc505401486a73c8e420380e1d3078bdf9f2a
theia-rhel8@sha256:78edc9f75680cbe7f63774d9dfbbc505401486a73c8e420380e1d3078bdf9f2a
registry.redhat.io/jboss-eap-7/eap-xp1-openj9-11-openshift-rhel8@sha256:d6a7bdbf4726fe0e0e54c0bce9b2257bbd2a165c37cb4ec68e1f994716ffb15c
eap-xp1-openj9-11-openshift-rhel8@sha256:d6a7bdbf4726fe0e0e54c0bce9b2257bbd2a165c37cb4ec68e1f994716ffb15c
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:8e6c7874247053df431c25552c6e2edb050b2627ae21907149f419e0d9909135
sso74-openj9-openshift-rhel8@sha256:8e6c7874247053df431c25552c6e2edb050b2627ae21907149f419e0d9909135
registry.redhat.io/rh-sso-7/sso74-openshift-rhel8@sha256:ec6801343eb1ca085154d8d7481552f2e9debc414125413d25e42216aa5922af
sso74-openshift-rhel8@sha256:ec6801343eb1ca085154d8d7481552f2e9debc414125413d25e42216aa5922af
registry.redhat.io/rhel8/postgresql-96@sha256:fdc2398a25530547354714f2538c691d91b700e0cedef5361a3e7d96ddfd4e11
postgresql-96@sha256:fdc2398a25530547354714f2538c691d91b700e0cedef5361a3e7d96ddfd4e11
registry.redhat.io/rhscl/mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73
mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73
registry.redhat.io/ubi8-minimal@sha256:5cfbaf45ca96806917830c183e9f37df2e913b187aadb32e89fd83fa455ebaa6
ubi8-minimal@sha256:5cfbaf45ca96806917830c183e9f37df2e913b187aadb32e89fd83fa455ebaa6
Verify the images have the same digests:
$ skopeo inspect docker://<source-image> $ skopeo inspect docker://<target-registry>/<target-organization>/<target-image>
Set the digests explicitly when different:
$ skopeo copy --all docker://<source-image> \ 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 CodeReady Workspaces Operator ClusterServiceVersion sources.
5.3.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.
Prerequisites
- An administrative account on an OpenShift instance.
-
A running instance version 2.3 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.3, “Installing CodeReady Workspaces in a restricted enviroment”. - Essential container images are available to the CodeReady Workspaces server running in the cluster. See Section 5.3.2, “Preparing a private registry”.
-
The
crwctl
2.4 management tool is available. See Section 3.2.1, “Installing the crwctl CLI management tool”.
Procedure
- In all running workspaces in the CodeReady Workspaces 2.3 instance, save and push changes back to the Git repositories.
- Stop all workspaces in the CodeReady Workspaces 2.3 instance.
Run the following command:
$ crwctl server:update --che-operator-image=<image-registry>/<organization>/crw-2-rhel8-operator:2.4 -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.2, “Preparing a private registry”.
Verification steps
- Navigate to the CodeReady Workspaces instance.
- The 2.4 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.