Chapter 5. Upgrading CodeReady Workspaces
This chapter describes how to upgrade a CodeReady Workspaces instance from version 2.7 to CodeReady Workspaces 2.8.
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.8 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 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.8 version management tool. See Section 3.3.1, “Installing the crwctl CLI management tool”.
Procedure
- In all running workspaces in the CodeReady Workspaces 2.7 instance, save and push changes back to the Git repositories.
- Shut down all workspaces in the CodeReady Workspaces 2.7 instance.
Run the following command:
$ 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.8 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.7 to version 2.8.
Prerequisites
- An administrative account on an instance of OpenShift.
-
A running instance version 2.7 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.8 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.8-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.8-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
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-
Table 5.3. Images to copy in the private registry
<source-image> <target-image> registry.redhat.io/codeready-workspaces/configbump-rhel8@sha256:db34b20374d99c2055612663a669a06f6dd0fc1fc19603761e993fd0870eddfe
configbump-rhel8@sha256:db34b20374d99c2055612663a669a06f6dd0fc1fc19603761e993fd0870eddfe
registry.redhat.io/codeready-workspaces/crw-2-rhel8-operator@sha256:a24dc83d8cdd8af715f0c4f235dcba0736bf395b7029ceaed0b8a683da5f74e0
crw-2-rhel8-operator@sha256:a24dc83d8cdd8af715f0c4f235dcba0736bf395b7029ceaed0b8a683da5f74e0
registry.redhat.io/codeready-workspaces/crw-2-rhel8-operator@sha256:a24dc83d8cdd8af715f0c4f235dcba0736bf395b7029ceaed0b8a683da5f74e0
crw-2-rhel8-operator@sha256:a24dc83d8cdd8af715f0c4f235dcba0736bf395b7029ceaed0b8a683da5f74e0
registry.redhat.io/codeready-workspaces/devfileregistry-rhel8@sha256:e3c360c031d8e68b62d1a28a4d736f41c5bfbc17c23999b9e1f1e5820858bf1d
devfileregistry-rhel8@sha256:e3c360c031d8e68b62d1a28a4d736f41c5bfbc17c23999b9e1f1e5820858bf1d
registry.redhat.io/codeready-workspaces/jwtproxy-rhel8@sha256:3f40bb8a2022545ac06a0b41cdb0239fdacfc34b37faffb21348a2041e96d0f2
jwtproxy-rhel8@sha256:3f40bb8a2022545ac06a0b41cdb0239fdacfc34b37faffb21348a2041e96d0f2
registry.redhat.io/codeready-workspaces/machineexec-rhel8@sha256:19a8daf7f9adde981dcd588b0526fa7682111097849f60a9b0e81137bdde8f6c
machineexec-rhel8@sha256:19a8daf7f9adde981dcd588b0526fa7682111097849f60a9b0e81137bdde8f6c
registry.redhat.io/codeready-workspaces/plugin-java11-openj9-rhel8@sha256:ee7c41053b4c8615886745566fc306dbf5bd1b1d367e525266477ae17a26673e
plugin-java11-openj9-rhel8@sha256:ee7c41053b4c8615886745566fc306dbf5bd1b1d367e525266477ae17a26673e
registry.redhat.io/codeready-workspaces/plugin-java11-openj9-rhel8@sha256:ee7c41053b4c8615886745566fc306dbf5bd1b1d367e525266477ae17a26673e
plugin-java11-openj9-rhel8@sha256:ee7c41053b4c8615886745566fc306dbf5bd1b1d367e525266477ae17a26673e
registry.redhat.io/codeready-workspaces/plugin-java11-openj9-rhel8@sha256:ee7c41053b4c8615886745566fc306dbf5bd1b1d367e525266477ae17a26673e
plugin-java11-openj9-rhel8@sha256:ee7c41053b4c8615886745566fc306dbf5bd1b1d367e525266477ae17a26673e
registry.redhat.io/codeready-workspaces/plugin-java11-rhel8@sha256:d93195134cef6351b1f9e3165fecc09f464dc99ab33d11b68fadd613d04d1636
plugin-java11-rhel8@sha256:d93195134cef6351b1f9e3165fecc09f464dc99ab33d11b68fadd613d04d1636
registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:8d8948134405e45bdd895932afa85b6cf0fbfe4e9bb58ae9753d233ddf74672b
plugin-java8-openj9-rhel8@sha256:8d8948134405e45bdd895932afa85b6cf0fbfe4e9bb58ae9753d233ddf74672b
registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:8d8948134405e45bdd895932afa85b6cf0fbfe4e9bb58ae9753d233ddf74672b
plugin-java8-openj9-rhel8@sha256:8d8948134405e45bdd895932afa85b6cf0fbfe4e9bb58ae9753d233ddf74672b
registry.redhat.io/codeready-workspaces/plugin-java8-openj9-rhel8@sha256:8d8948134405e45bdd895932afa85b6cf0fbfe4e9bb58ae9753d233ddf74672b
plugin-java8-openj9-rhel8@sha256:8d8948134405e45bdd895932afa85b6cf0fbfe4e9bb58ae9753d233ddf74672b
registry.redhat.io/codeready-workspaces/plugin-java8-rhel8@sha256:ecaa9ddef5ca8db9552f1b5e66f7aacb19d72e488d718d8135b1e1d9f66a1a7a
plugin-java8-rhel8@sha256:ecaa9ddef5ca8db9552f1b5e66f7aacb19d72e488d718d8135b1e1d9f66a1a7a
registry.redhat.io/codeready-workspaces/plugin-kubernetes-rhel8@sha256:cf1d0e24f8bae0f87cae0b1577dfd25e124437d78031d7076fabebb2dcf48d7f
plugin-kubernetes-rhel8@sha256:cf1d0e24f8bae0f87cae0b1577dfd25e124437d78031d7076fabebb2dcf48d7f
registry.redhat.io/codeready-workspaces/plugin-openshift-rhel8@sha256:13ce6d8fdeeea0cc5a220ebe8abd2811c31bb2a424736759be9a6df15c8f77fd
plugin-openshift-rhel8@sha256:13ce6d8fdeeea0cc5a220ebe8abd2811c31bb2a424736759be9a6df15c8f77fd
registry.redhat.io/codeready-workspaces/pluginbroker-artifacts-rhel8@sha256:cda306cb7e5c42faa6ab43218d39984d4955134b3ca9654968c28b05e0796c3a
pluginbroker-artifacts-rhel8@sha256:cda306cb7e5c42faa6ab43218d39984d4955134b3ca9654968c28b05e0796c3a
registry.redhat.io/codeready-workspaces/pluginbroker-metadata-rhel8@sha256:0143a80b869620af08a0d60165dc9d13357a79e7243502832326cf053c17ee38
pluginbroker-metadata-rhel8@sha256:0143a80b869620af08a0d60165dc9d13357a79e7243502832326cf053c17ee38
registry.redhat.io/codeready-workspaces/pluginregistry-rhel8@sha256:3f5163a2303de7f538eca2cc560403f38b920af1169821dfa06dbef695fb10c6
pluginregistry-rhel8@sha256:3f5163a2303de7f538eca2cc560403f38b920af1169821dfa06dbef695fb10c6
registry.redhat.io/codeready-workspaces/server-rhel8@sha256:6635e8c160c8c73c00c9b05eccab08a4ff23d344f102ef0097a3798bf108217a
server-rhel8@sha256:6635e8c160c8c73c00c9b05eccab08a4ff23d344f102ef0097a3798bf108217a
registry.redhat.io/codeready-workspaces/stacks-cpp-rhel8@sha256:06cd3600c3b6c3dca0451b10b46961fd0db4140c7dddc4f9637984022f5cfc09
stacks-cpp-rhel8@sha256:06cd3600c3b6c3dca0451b10b46961fd0db4140c7dddc4f9637984022f5cfc09
registry.redhat.io/codeready-workspaces/stacks-dotnet-rhel8@sha256:ea77974b206c7d7abcad5cd32149f6bb669d3cf867135553af4d7dddd24ba9cf
stacks-dotnet-rhel8@sha256:ea77974b206c7d7abcad5cd32149f6bb669d3cf867135553af4d7dddd24ba9cf
registry.redhat.io/codeready-workspaces/stacks-golang-rhel8@sha256:e01d32e58a55a552f0d35b9a6210b7a2cc8ed444f8ae54a24113dcc85f4d80db
stacks-golang-rhel8@sha256:e01d32e58a55a552f0d35b9a6210b7a2cc8ed444f8ae54a24113dcc85f4d80db
registry.redhat.io/codeready-workspaces/stacks-php-rhel8@sha256:95c324ed660924bf76e10b461d75aa5be2a323f26e5033239f7cbfe1ec10b26e
stacks-php-rhel8@sha256:95c324ed660924bf76e10b461d75aa5be2a323f26e5033239f7cbfe1ec10b26e
registry.redhat.io/codeready-workspaces/theia-endpoint-rhel8@sha256:60c84fca55a997a6aab4ca07b8ff7d859948c1f525adeba2ae624c84fe059a56
theia-endpoint-rhel8@sha256:60c84fca55a997a6aab4ca07b8ff7d859948c1f525adeba2ae624c84fe059a56
registry.redhat.io/codeready-workspaces/theia-rhel8@sha256:de36fdf140ba6367e6edf577d6dbaffa270e5e5ecf0890e498f5907f8287858f
theia-rhel8@sha256:de36fdf140ba6367e6edf577d6dbaffa270e5e5ecf0890e498f5907f8287858f
registry.redhat.io/codeready-workspaces/traefik-rhel8@sha256:0698a776c6ae2f08238cf011d69ac2c67f934b1e25ec38701a9e360430fd10f7
traefik-rhel8@sha256:0698a776c6ae2f08238cf011d69ac2c67f934b1e25ec38701a9e360430fd10f7
registry.redhat.io/jboss-eap-7/eap-xp2-openj9-11-openshift-rhel8@sha256:95d2ce73a0759de5befdbec115514a555752e2f20070fbfe356801da6d0a2bd6
eap-xp2-openj9-11-openshift-rhel8@sha256:95d2ce73a0759de5befdbec115514a555752e2f20070fbfe356801da6d0a2bd6
registry.redhat.io/jboss-eap-7/eap-xp2-openj9-11-openshift-rhel8@sha256:95d2ce73a0759de5befdbec115514a555752e2f20070fbfe356801da6d0a2bd6
eap-xp2-openj9-11-openshift-rhel8@sha256:95d2ce73a0759de5befdbec115514a555752e2f20070fbfe356801da6d0a2bd6
registry.redhat.io/jboss-eap-7/eap-xp2-openj9-11-openshift-rhel8@sha256:95d2ce73a0759de5befdbec115514a555752e2f20070fbfe356801da6d0a2bd6
eap-xp2-openj9-11-openshift-rhel8@sha256:95d2ce73a0759de5befdbec115514a555752e2f20070fbfe356801da6d0a2bd6
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:ed11770a85ca95fc9cbb2cade539a67ff0e127cff73a89a017415800e032bd5b
sso74-openj9-openshift-rhel8@sha256:ed11770a85ca95fc9cbb2cade539a67ff0e127cff73a89a017415800e032bd5b
registry.redhat.io/rh-sso-7/sso74-openj9-openshift-rhel8@sha256:ed11770a85ca95fc9cbb2cade539a67ff0e127cff73a89a017415800e032bd5b
sso74-openj9-openshift-rhel8@sha256:ed11770a85ca95fc9cbb2cade539a67ff0e127cff73a89a017415800e032bd5b
registry.redhat.io/rh-sso-7/sso74-openshift-rhel8@sha256:3154fd4f6ce080260de9d2b4c02930b67b57f1181f4e660f5ddfc9f6050420b1
sso74-openshift-rhel8@sha256:3154fd4f6ce080260de9d2b4c02930b67b57f1181f4e660f5ddfc9f6050420b1
registry.redhat.io/rhel8/postgresql-96@sha256:32d73d737acec3daabc3f5c8236588454c8f57f7a2656ac7a50cf3a04f520b9b
postgresql-96@sha256:32d73d737acec3daabc3f5c8236588454c8f57f7a2656ac7a50cf3a04f520b9b
registry.redhat.io/rhscl/mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73
mongodb-36-rhel7@sha256:9f799d356d7d2e442bde9d401b720600fd9059a3d8eefea6f3b2ffa721c0dc73
registry.redhat.io/ubi8/ubi-minimal@sha256:2f6b88c037c0503da7704bccd3fc73cb76324101af39ad28f16460e7bce98324
ubi8ubi-minimal@sha256:2f6b88c037c0503da7704bccd3fc73cb76324101af39ad28f16460e7bce98324
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 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.7 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.8 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.7 instance, save and push changes back to the Git repositories.
- Stop all workspaces in the CodeReady Workspaces 2.7 instance.
Run the following command:
$ crwctl server:update --che-operator-image=<image-registry>/<organization>/crw-2-rhel8-operator:2.8 -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.8 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.