The Che 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 tooling). The IDE services are deployed with the development tooling, packaged in containers and user runtime applications, which are defined as Kubernetes resources.

The source code of the projects of a Che workspace is persisted in a Kubernetes 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 Che workspace.

che workspaces
Figure 1. Che 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 Che workspace.

Che workspace components

This section describes the components of a Che workspace.

Che Plugin plug-ins

Che Plugin plug-ins are special services that extend Che 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, thus 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 Che workspace editor and augment its capabilities.

Visual Studio Code extensions packaged in containers are Che plug-ins for the Che-Theia editor.

Multiple Che 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).

Che Editor plug-in

A Che Editor plug-in is a Che workspace plug-in. It defines the web application that is used as an editor in a workspace. The default Che workspace editor is called 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


Che 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 Kubernetes or OpenShift resources can be included in a Che workspace. This makes it easy to test applications in the Che workspace.

To test an application in the Che 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.

Che workspace JWT proxy

The JWT proxy is responsible for securing the communication of the Che workspace services. The Che workspace JWT proxy is included in a Che workspace only if the Che server is configured in multi-user mode.

An HTTP proxy is used to sign outgoing requests from a workspace service to the Che server and to authenticate incoming requests from the IDE client running on a browser.

Source code

JWT proxy

Container image


Che 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 Che 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 Che plug-ins definitions from the actual plug-ins that Che can support. With brokers, Che can support different plug-ins without updating the Che server.

The Che server starts the plug-in broker. The plug-in broker runs in the same Kubernetes 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

Che Plug-in broker

Container image


Che workspace configuration

This section describes the properties of the Che server that affect the provisioning of a Che workspace.

Storage strategies for Che workspaces

Workspace pods use Persistent Volume Claims (PVCs), which are bound to the physical Persistent Volumes (PVs) with ReadWriteOnce access mode. The way how Che server uses PVCs for workspaces is configurable and it’s called PVC strategy:

strategy details pros cons


One PVC per workspace volume or user-defined PVC

Storage isolation

An undefined number of PVs is required


One PVC for one workspace

Easier to manage and control storage compared to unique stategy

PV count still is not known and depends on workspaces number

common (default)

One PVC for all workspaces in one kubernetes namespace

Easy to manage and control storage

If PV does not support ReadWriteMany (RWX) access mode then workspaces must be in a separate kubernetes namespaces

Or there must not be more than 1 running workspace per namespace at the same time

See how to configure namespace strategy

Unique PVC strategy

How the unique PVC strategy works

Every Che Volume of workspace gets its own PVC, which means workspace PVCs are created when a workspace starts for the first time. Workspace PVCs are deleted when a corresponding workspace is deleted.

User-defined PVCs are created with few modifications:

  • they are provisioned with generated names to guarantee that it is not conflicting with other PVCs in namespace;

  • subpaths of mount volumes that reference user-defined PVCs are prefixed with {workspace id}/{PVC name}. It is done to have the same data structure on PV on different PVC strategies(more);

Common PVC Strategy

How the common PVC strategy works

All workspaces (within one {k8s-namespace}) use the same PVC to store data in their declared volumes (projects and workspace logs by default and whatever additional volumes that a user can define.)

User-defined PVCs are ignored and volumes that reference PVCs are replaced with volume that references common PVC. The corresponding containers volume mounts are relinked to common volume and subpaths are prefixed with '{workspaceId}/{originalPVCName}' (more).

User-defined PVC name is used as Che Volume name. It means that if Machine is configured to use Che Volume with the same name as user-defined PVC has then they will use the same shared folder in 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. - the only one workspace in the same namespace may be running. See how to configure namespace strategy and running workspace count

Per workspace PVC strategy

How the per-workspace PVC strategy works

The per-workspace strategy works similarly to the common PVC strategy. The only difference is that all workspace volumes (but not all workspaces) use the same PVC to store data (projects and workspace logs by default and any additional volumes that a user can define).

How the subpaths are used in PVCs

    /<User-defined PVC name 1 | volume 3>

Volumes can be anything that a user defines as volumes for workspace machines. The volume name is equal to the directory name in ${PV}/${ws-id}.

Configuring a per-workspace strategy using the Helm chart

The following section describes how to configure workspace PVCs strategies of a Che server using the Helm chart.

Note: it’s not recommended to reconfigure PVC strategies on an existing Che cluster with existing workspaces. After that workspaces will lost their data.

A Helm Chart is a Kubernetes extension for defining, installing, and upgrading Kubernetes applications.

When deploying Che using the Helm chart, configure the workspace PVC strategy by setting values for global.pvcStrategy. To do so, add the following option to the helm install or helm upgrade command:

$ helm install --set global.pvcStrategy=<common>


$ helm upgrade --set global.pvcStrategy=<common>

Depending on the strategy used, replace the <common> option in the above example with unique or per-workspace.

Configuring a per-workspace strategy using the Operator

The following section describes how to configure workspace PVCs strategies of a Che server using the Operator.

Note: it’s not recommended to reconfigure PVC strategies on an existing Che cluster with existing workspaces. After that workspaces will lost their data.

Operators are software extensions to Kubernetes that use custom resources to manage applications and their components.

When deploying Che using the Operator, configure the intended strategy by modifying the property of the CheCluster custom resource object YAML file. To activate changes done to CheCluster YAML file, do one of the following:

  • Create a new cluster by executing the kubectl apply command. For example:

    $ kubectl apply -f <my-cluster.yaml>
  • Update the YAML file properties of an already running cluster by executing the kubectl patch command. For example:

    $ kubectl patch checluster eclipse-che --type=json -p '[{"op": "replace", "path": "/spec/storage/pvcStrategy", "value": "common"}]'

Depending on the strategy used, replace the <common> option in the above example with unique or per-workspace.

Workspace namespaces configuration

The Kubernetes namespace where a new workspace pod is deployed depends on the Che server configuration. By default, every workspace is deployed in a distinct namespace, but the user can configure the Che server to deploy all workspaces in one specific namespace. The name of a namespace must be provided as a Che server configuration property and cannot be changed at runtime.

Che workspace creation flow

che workspace creation flow

The following is a Che workspace creation flow:

  1. A user starts a Che workspace defined by:

    • An editor (the default is Che-Theia)

    • A list of plug-ins (for example, Java and Kubernetes tooling)

    • A list of runtime applications

  2. wsmaster retrieves the editor and plug-in metadata from the plug-in registry.

  3. For every plug-in type, wsmaster starts a specific plug-in broker.

  4. The Che plug-ins broker transforms the plug-in metadata into a Che Plugin definition. It executes the following steps:

    1. Downloads a plug-in and extracts its content.

    2. Processes the plug-in meta.yaml file and sends it back to wsmaster in the format of a Che Plugin.

  5. wsmaster starts the editor and the plug-in sidecars.

  6. The editor loads the plug-ins from the plug-in persistent volume.