Chapter 10. CodeReady Workspaces architectural elements
This section contains information about the CodeReady Workspaces architecture. Section starts with a High-level CodeReady Workspaces architecture overview and continues with providing information about the CodeReady Workspaces workspace controller and CodeReady Workspaces workspace architecture.
10.1. High-level CodeReady Workspaces architecture
Figure 10.1. High-level CodeReady Workspaces architecture
At a high-level, CodeReady Workspaces is composed of one central workspace controller that manages the CodeReady Workspaces workspaces through the OpenShift API.
When CodeReady Workspaces is installed on a OpenShift cluster, the workspace controller is the only component that is deployed. A CodeReady Workspaces workspace is created immediately after a user requests it.
This section describes the different services that create the workspaces controller and the CodeReady Workspaces workspaces.
10.2. CodeReady Workspaces workspace controller
The workspaces controller manages the container-based development environments: CodeReady Workspaces workspaces. It can be deployed in the following distinct configurations:
- Single-user: No authentication service is set up. Development environments are not secured. This configuration requires fewer resources. It is more adapted for local installations, such as when using Minikube.
- Multi-user: This is a multi-tenant configuration. Development environments are secured, and this configuration requires more resources. Appropriate for cloud installations.
The different services that are a part of the CodeReady Workspaces workspaces controller are shown in the following diagram. Note that RH-SSO and PostgreSQL are only needed in the multi-user configuration.
Figure 10.2. CodeReady Workspaces workspaces controller
10.2.1. CodeReady Workspaces server
The CodeReady Workspaces server, also known as wsmaster, is the central service of the workspaces controller. It is a Java web service that exposes an HTTP REST API to manage CodeReady Workspaces workspaces and, in multi-user mode, CodeReady Workspaces users.
| Source code | |
| Container image |
|
| Environment variables |
10.2.2. CodeReady Workspaces user dashboard
The user dashboard is the landing page of Red Hat CodeReady Workspaces. It is an Angular front-end application. CodeReady Workspaces users create, start, and manage CodeReady Workspaces workspaces from their browsers through the user dashboard.
| Source code | |
| Container image |
|
10.2.3. Devfile registry
The CodeReady Workspaces devfile registry is a service that provides a list of CodeReady Workspaces stacks to create ready-to-use workspaces. This list of stacks is used in the Dashboard → Create Workspace window. The devfile registry runs in a container and can be deployed wherever the user dashboard can connect.
For more information about devfile registry customization, see the Customizing devfile registry section.
| Source code | |
| Container image |
|
10.2.4. CodeReady Workspaces plug-in registry
The CodeReady Workspaces plug-in registry is a service that provides the list of plug-ins and editors for the CodeReady Workspaces workspaces. A devfile only references a plug-in that is published in a CodeReady Workspaces plug-in registry. It runs in a container and can be deployed wherever wsmaster connects.
For more information about plug-in registry customization, see the Chapter 1, Customizing the devfile and plug-in registries section.
| Source code | |
| Container image |
|
10.2.5. CodeReady Workspaces and PostgreSQL
The PostgreSQL database is a prerequisite to configure CodeReady Workspaces in multi-user mode. The CodeReady Workspaces administrator can choose to connect CodeReady Workspaces to an existing PostgreSQL instance or let the CodeReady Workspaces deployment start a new dedicated PostgreSQL instance.
The CodeReady Workspaces server uses the database to persist user configurations (workspaces metadata, Git credentials). RH-SSO uses the database as its back end to persist user information.
| Source code | |
| Container image |
|
10.2.6. CodeReady Workspaces and RH-SSO
RH-SSO is a prerequisite to configure CodeReady Workspaces in multi-user mode. The CodeReady Workspaces administrator can choose to connect CodeReady Workspaces to an existing RH-SSO instance or let the CodeReady Workspaces deployment start a new dedicated RH-SSO instance.
The CodeReady Workspaces server uses RH-SSO as an OpenID Connect (OIDC) provider to authenticate CodeReady Workspaces users and secure access to CodeReady Workspaces resources.
| Source code | |
| Container image |
|
10.3. CodeReady Workspaces workspaces architecture
A CodeReady Workspaces deployment on the cluster consists of the CodeReady Workspaces server component, a database for storing user profile and preferences, and a number of additional deployments hosting workspaces. The CodeReady Workspaces server orchestrates the creation of workspaces, which consist of a deployment containing the workspace containers and enabled plug-ins, plus related components, such as:
- configmaps
- services
- endpoints
- ingresses/routes
- secrets
- PVs
The CodeReady Workspaces workspace is a web application. It is composed of microservices running in containers that provide all the services of a modern IDE (an editor, language auto-completion, debugging tools). The IDE services are deployed with the development tools, packaged in containers and user runtime applications, which are defined as OpenShift resources.
The source code of the projects of a CodeReady Workspaces workspace is persisted in a OpenShift PersistentVolume. Microservices run in containers that have read-write access to the source code (IDE services, development tools), and runtime applications have read-write access to this shared directory.
The following diagram shows the detailed components of a CodeReady Workspaces workspace.
Figure 10.3. CodeReady Workspaces workspace components
In the diagram, there are three running workspaces: two belonging to User A and one to User C. A fourth workspace is getting provisioned where the plug-in broker is verifying and completing the workspace configuration.
Use the devfile format to specify the tools and runtime applications of a CodeReady Workspaces workspace.
10.3.1. CodeReady Workspaces workspace components
This section describes the components of a CodeReady Workspaces workspace.
10.3.1.1. Che Plugin plug-ins
Che Plugin plug-ins are special services that extend CodeReady Workspaces workspace capabilities. Che Plugin plug-ins are packaged as containers. Packaging plug-ins into a container has the following benefits:
- It isolates the plug-ins from the main IDE, therefore limiting the resources that a plug-in has access to.
- It uses the consolidated standard of container registries to publish and distribute plug-ins (as with any container image).
The containers that plug-ins are packaged into run as sidecars of the CodeReady Workspaces workspace editor and augment its capabilities.
Visual Studio Code extensions packaged in containers are CodeReady Workspaces plug-ins for the Che-Theia editor.
Multiple CodeReady Workspaces plug-ins can run in the same container (for better resource use), or a Che Plugin can run in its dedicated container (for better isolation).
10.3.1.2. Che Editor plug-in
A Che Editor plug-in is a CodeReady Workspaces workspace plug-in. It defines the web application that is used as an editor in a workspace. The default CodeReady Workspaces workspace editor is Che-Theia.
The Che-Theia source-code repository is at Che-Theia Github. It is based on the Eclipse Theia open-source project.
Che-Theia is written in TypeScript and is built on the Microsoft Monaco editor. It is a web-based source-code editor similar to Visual Studio Code (VS Code). It has a plug-in system that supports VS Code extensions.
| Source code | |
| Container image |
|
| Endpoints |
|
10.3.1.3. CodeReady Workspaces user runtimes
Use any non-terminating user container as a user runtime. An application that can be defined as a container image or as a set of OpenShift resources can be included in a CodeReady Workspaces workspace. This makes it easy to test applications in the CodeReady Workspaces workspace.
To test an application in the CodeReady Workspaces workspace, include the application YAML definition used in stage or production in the workspace specification. It is a 12-factor app dev/prod parity.
Examples of user runtimes are Node.js, SpringBoot or MongoDB, and MySQL.
10.3.1.4. CodeReady Workspaces workspace JWT proxy
The JWT proxy is responsible for securing the communication of the CodeReady Workspaces workspace services. The CodeReady Workspaces workspace JWT proxy is included in a CodeReady Workspaces workspace only if the CodeReady Workspaces server is configured in multi-user mode.
An HTTP proxy is used to sign outgoing requests from a workspace service to the CodeReady Workspaces server and to authenticate incoming requests from the IDE client running on a browser.
| Source code | |
| Container image |
|
10.3.1.5. CodeReady Workspaces plug-ins broker
Plug-in brokers are special services that, given a plug-in meta.yaml file:
- Gather all the information to provide a plug-in definition that the CodeReady Workspaces server knows.
- Perform preparation actions in the workspace namespace (download, unpack files, process configuration).
The main goal of the plug-in broker is to decouple the CodeReady Workspaces plug-ins definitions from the actual plug-ins that CodeReady Workspaces can support. With brokers, CodeReady Workspaces can support different plug-ins without updating the CodeReady Workspaces server.
The CodeReady Workspaces server starts the plug-in broker. The plug-in broker runs in the same OpenShift namespace as the workspace. It has access to the plug-ins and project persistent volumes.
A plug-ins broker is defined as a container image (for example, eclipse/che-plugin-broker). The plug-in type determines the type of the broker that is started. Two types of plug-ins are supported: Che Plugin and Che Editor.
| Source code | |
| Container image |
|
10.3.2. CodeReady Workspaces workspace configuration
This section describes the properties of the CodeReady Workspaces server that affect the provisioning of a CodeReady Workspaces workspace.
10.3.2.1. Storage strategies for codeready-workspaces workspaces
Workspace Pods use Persistent Volume Claims (PVCs), which are bound to the physical Persistent Volumes (PVs) with ReadWriteOnce access mode. It is possible to configure how the CodeReady Workspaces server uses PVCs for workspaces. The individual methods for this configuration are called PVC strategies:
| strategy | details | pros | cons |
|---|---|---|---|
| unique | One PVC per workspace volume or user-defined PVC | Storage isolation | An undefined number of PVs is required |
| per-workspace (default) | One PVC for one workspace | Easier to manage and control storage compared to unique strategy | PV count still is not known and depends on workspaces number |
| common | One PVC for all workspaces in one OpenShift namespace | Easy to manage and control storage | If PV does not support ReadWriteMany (RWX) access mode then workspaces must be in a separate OpenShift namespaces Or there must not be more than 1 running workspace per namespace at the same time See how to configure namespace strategy |
Red Hat CodeReady Workspaces uses the common PVC strategy in combination with the "one namespace per user" namespace strategy when all CodeReady Workspaces workspaces operate in the user’s namespace, sharing one PVC.
10.3.2.1.1. The common PVC strategy
All workspaces inside a OpenShift-native namespace use the same Persistent Volume Claim (PVC) as the default data storage when storing data such as the following in their declared volumes:
- projects
- workspace logs
- additional Volumes defined by a use
When the common PVC strategy is in use, user-defined PVCs are ignored and volumes that refer to these user-defined PVCs are replaced with a volume that refers to the common PVC. In this strategy, all {prod-short) workspaces use the same PVC. When the user runs one workspace, it only binds to one node in the cluster at a time.
The corresponding containers volume mounts link to a common volume, and sub-paths are prefixed with '{workspaceID}/{originalPVCName}'. For more details, see Section 10.3.2.1.4, “How subpaths are used in PVCs”.
The CodeReady Workspaces Volume name is identical to the name of the user-defined PVC. It means that if a machine is configured to use a CodeReady Workspaces volume with the same name as the user-defined PVC has, they will use the same shared folder in the common PVC.
When a workspace is deleted, a corresponding subdirectory (${ws-id}) is deleted in the PV directory.
Restrictions on using the common PVC strategy
When the common strategy is used and a workspace PVC access mode is ReadWriteOnce (RWO), only one {admin-context} node can simultaneously use the PVC.
If there are several nodes, you can use the common strategy, but:
-
The workspace PVC access mode must be reconfigured to
ReadWriteMany(RWM), so multiple nodes can use this PVC simultaneously. - Only one workspace in the same namespace may be running. See Configuring namespace strategies.
The common PVC strategy is not suitable for large multi-node clusters. Therefore, it is best to use it in single-node clusters. However, in combination with per-workspace namespace strategy, the common PVC strategy is usable for clusters with around 75 nodes. The PVC used in this strategy must be large enough to accommodate all projects since there is a risk of the event, in which one project depletes the resources of others.
10.3.2.1.2. The per-workspace PVC strategy
The per-workspace strategy is similar to the common PVC strategy. The only difference is that all workspace Volumes, but not all the workspaces, use the same PVC as the default data storage for:
- projects
- workspace logs
- additional Volumes defined by a user
It’s a strategy when CodeReady Workspaces keeps its workspace data in assigned PVs that are allocated by a single PVC.
The per-workspace PVC strategy is the most universal strategy out of the PVC strategies available and acts as a proper option for large multi-node clusters with a higher amount of users. Using the per-workspace PVC strategy, users can run multiple workspaces simultaneously, results in more PVCs being created.
10.3.2.1.3. The unique PVC strategy
When using the `unique `PVC strategy, every CodeReady Workspaces Volume of a workspace has its own PVC. This means that workspace PVCs are:
Created when a workspace starts for the first time. Deleted when a corresponding workspace is deleted.
User-defined PVCs are created with the following specifics:
- They are provisioned with generated names to prevent naming conflicts with other PVCs in a namespace.
-
Subpaths of the mounted Physical persistent volumes that reference user-defined PVCs are prefixed with
{workspace id}/{PVC name}. This ensures that the same PV data structure is set up with different PVC strategies. For details, see Section 10.3.2.1.4, “How subpaths are used in PVCs”.
The unique PVC strategy is suitable for larger multi-node clusters with a lesser amount of users. Since this strategy operates with separate PVCs for each volume in a workspace, vastly more PVCs are created.
10.3.2.1.4. How subpaths are used in PVCs
Subpaths illustrate the folder hierarchy in the Persistent Volumes (PV).
/pv0001
/workspaceID1
/workspaceID2
/workspaceIDn
/che-logs
/projects
/<volume1>
/<volume2>
/<User-defined PVC name 1 | volume 3>
...
When a user defines volumes for components in the devfile, all components that define the volume of the same name will be backed by the same directory in the PV as ${PV}/${ws-id}/${volume-name}. Each component can have this location mounted on a different path in its containers.
Example
Using the common PVC strategy, user-defined PVCs are replaced with subpaths on the common PVC. When the user references a volume as my-volume, it is mounted in the common-pvc with the /workspace-id/my-volume subpath.
10.3.2.2. Configuring a CodeReady Workspaces workspace with a persistent volume strategy
A persistent volume (PV) acts as a virtual storage instance that adds a volume to a cluster.
A persistent volume claim (PVC) is a request to provision persistent storage of a specific type and configuration, available in the following CodeReady Workspaces storage configuration strategies:
- Common
- Per-workspace
- Unique
The mounted PVC is displayed as a folder in a container file system.
10.3.2.2.1. Configuring a PVC strategy using the Operator
The following section describes how to configure workspace persistent volume claim (PVC) strategies of a CodeReady Workspaces server using the Operator.
It is not recommended to reconfigure PVC strategies on an existing CodeReady Workspaces cluster with existing workspaces. Doing so causes data loss.
Operators are software extensions to OpenShift that use custom resources to manage applications and their components.
When deploying CodeReady Workspaces using the Operator, configure the intended strategy by modifying the spec.storage.pvcStrategy property of the CheCluster Custom Resource object YAML file.
Prerequisites
-
A OpenShift orchestration tool, the OpenShift command-line tool,
oc, is installed.
Procedure
The following procedure steps are available for:
-
OpenShift command-line tool,
oc
To do changes to the CheCluster YAML file, choose one of the following:
Create a new cluster by executing the
oc applycommand. For example:$ oc apply -f <my-cluster.yaml>Update the YAML file properties of an already running cluster by executing the
oc patchcommand. For example:$ oc patch checluster codeready-workspaces --type=json \ -p '[{"op": "replace", "path": "/spec/storage/pvcStrategy", "value": "<per-workspace>"}]'
Depending on the strategy used, replace the <per-workspace> option in the above example with unique or common.
10.3.2.3. Workspace namespaces configuration
The OpenShift namespace where a new workspace Pod is deployed depends on the CodeReady Workspaces server configuration. By default, every workspace is deployed in a distinct namespace, but the user can configure the CodeReady Workspaces server to deploy all workspaces in one specific namespace. The name of a namespace must be provided as a CodeReady Workspaces server configuration property and cannot be changed at runtime.
10.3.3. CodeReady Workspaces workspace creation flow
The following is a CodeReady Workspaces workspace creation flow:
A user starts a CodeReady Workspaces workspace defined by:
- An editor (the default is Che-Theia)
- A list of plug-ins (for example, Java and OpenShift tools)
- A list of runtime applications
- wsmaster retrieves the editor and plug-in metadata from the plug-in registry.
- For every plug-in type, wsmaster starts a specific plug-in broker.
The CodeReady Workspaces plug-ins broker transforms the plug-in metadata into a Che Plugin definition. It executes the following steps:
- Downloads a plug-in and extracts its content.
-
Processes the plug-in
meta.yamlfile and sends it back to wsmaster in the format of a Che Plugin.
- wsmaster starts the editor and the plug-in sidecars.
- The editor loads the plug-ins from the plug-in persistent volume.
