Configuring storage strategies

This section describes how to configure storage strategies for Che workspaces.

Storage strategies for che workspaces

Storage strategy

A configurable method defining how Che workspaces use persistent volume claims (PVCs) and persistent volumes (PVs). This method defines the storage for workspace data, for example, projects, workspace logs, or additional volumes defined by a user.

Table 1. Storage strategies comparison
Storage strategy name common per-workspace unique

PV count

One per user

One per workspace

Multiple PVs per workspace






Maximum one running workspace per user when the PV is in the ReadWriteOnce access mode

PV count depends on the number of workspaces

Unpredictable PV count

Persistent volumes (PVs) access mode

The nature of the PV determines the available access mode: ReadWriteMany or ReadWriteOnce. See Kubernetes documentation - access mode. For example, Amazon EBS supports only the ReadWriteOnce access mode.

The common storage strategy

This is the default storage strategy. For each user, all workspaces use the same PV for the default data storage.

When the user starts a first non-ephemeral workspace, the workspace engine creates a common PV.

When the user starts another non-ephemeral workspace, the workspace engine uses the same common PV. The workspace only binds simultaneously to one node in the Kubernetes cluster. The workspace engine ignores user-defined volumes. The workspace engine replaces volumes related to user-defined volumes with a subPath in the common volume. SubPaths have a <workspace-ID> or <original-volume-name> prefix. See How subPaths are used in persistent volumes (PVs). The Che volume name is identical to the name of the user-defined PV. Therefore, if a workspace container uses a Che volume with the same name as the user-defined PV, they will use the same shared folder in the common PV.

When the user deletes a workspace, the workspace engine deletes the corresponding subdirectory (${ws-id}) in the PV directory.

When the user deletes the last workspace, the workspace engine removes the common PV.

Restrictions on the common storage strategy with the ReadWriteOnce access mode

The ReadWriteOnce access mode limits each user to run only one concurrent workspace. See Configuring the number of workspaces that a user can run.


The common storage strategy is not suitable for multi-node clusters with the 'ReadWriteOnce' access mode for PVs if the number of concurrently running workspaces per user is more than 1.

Persistent volumes (PV) provisioning

Create a large enough PV to accommodate all projects to prevent a situation in which one project depletes the resources of others.

The per-workspace storage strategy

Each workspace uses one dedicated PV. All Che volumes defined within a single workspace use the same PV.

Persistent volumes (PV) provisioning

Users can run multiple workspaces simultaneously. This action results in more PVs.

The unique storage strategy

Each Che volume defined in a workspace has its own PV.

When the user starts a workspace, the workspace engine creates the workspace PVs.

The workspace engine generates a unique name for each PV to prevent name conflicts with other PVs in the same namespace.

To ensure that different storage strategies use the same PV data structure, subPaths of the mounted PVs that reference user-defined PVs are prefixed with <workspace-ID> or <persistent-volume-name>. See How subPaths are used in persistent volumes (PVs).

When the user deletes a workspace, the workspace engine deletes all workspace PVs.

PV provisioning

This is the strategy, which creates the highest volume counts.

How subPaths are used in persistent volumes (PVs)

SubPaths illustrate the folder hierarchy in the PV.


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 <persistent-volume-name>, <workspace-ID>, or <original-volume-name>. Each component can have this location mounted on a different path in its containers.

Configuring a Che 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 Che storage configuration strategies:

  • Common

  • Per-workspace

  • Unique

The mounted PVC is displayed as a folder in a container file system.

Configuring a PVC strategy using the Operator

The following section describes how to configure workspace persistent volume claim (PVC) strategies of a Che server using the Operator.

It is not recommended to reconfigure PVC strategies on an existing Che cluster with existing workspaces. Doing so causes data loss.

Operators are software extensions to Kubernetes or OpenShift 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.

  • The kubectl tool is available.


The following procedure steps are available for Kubernetes or OpenShift command-line tool, `kubectl` or `oc`.

To do changes to the CheCluster YAML file, choose 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": "per-workspace"}]'

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