Configuring storage strategies

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

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. It is possible to configure how the Che server uses PVCs for workspaces. The individual methods for this configuration are called PVC strategies:

Strategy Details Pros Cons

common (default)

One PVC for all workspaces in one Kubernetes namespace or OpenShift project

Easy to manage and control storage

If PV does not support ReadWriteMany (RWX) access mode, the configuration will work only if one or both of the following apply:

* Each workspace is in a separate Kubernetes namespace or OpenShift project

* Only one workspace is running per Kubernetes namespace or OpenShift project at the same time. See Running more than one workspace at a time.

per-workspace

One PVC for one workspace

Easier to manage and control storage compared to unique strategy

PV count is not known and depends on workspaces number

unique

One PVC per workspace volume or user-defined PVC

Storage isolation

An undefined number of PVs is required

Eclipse Che uses the common PVC strategy in combination with the "one namespace per user" namespace strategy when all Che workspaces operate in the user’s namespace, sharing one PVC.

The common PVC strategy

All workspaces inside a Kubernetes namespace or OpenShift project 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 Che 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 <workspace-ID> or <original-PVC-name>. For more details, see How subpaths are used in PVCs.

The Che Volume name is identical to the name of the user-defined PVC. It means that if a machine is configured to use a Che 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 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 Running more than one workspace at a time.

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 the per-workspace namespace strategy, the common PVC strategy is usable for clusters with not more than 75 nodes. The PVC used with this strategy must be large enough to accommodate all projects to prevent a situation in which one project depletes the resources of others.

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

With this strategy, Che 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.

The unique PVC strategy

When using the `unique `PVC strategy, every Che 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> or <PVC-name>. This ensures that the same PV data structure is configure with different PVC strategies. For details, see 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.

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-name>, <workspace-ID>, or `<original-PVC-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.

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 Helm chart

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

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

When deploying Che using Helm Chart, configure the workspace PVC strategy by setting values for the global.cheWorkspacesPVCStrategy option.

  • For a new installation, use the helm install command with the global.cheWorkspacesPVCStrategy option:

    $ helm install --set global.cheWorkspacesPVCStrategy=per-workspace

  • For an already installed instance, use the helm upgrade command with the global.cheWorkspacesPVCStrategy option:

    $ helm upgrade --set global.cheWorkspacesPVCStrategy=per-workspace

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

Configuring a PVC strategy strategy by editing a configMap

Based on the Che installation method, configMaps can be used to customize the working environment. A configMap is provided as an editable file that lists options to customize the Che environment. This method of configuring a persistent volume claim (PVC) strategy for a Che workspace is available only for the Helm installation.

Changes to a configMap created during Operator installation are not permanent because the Operator overwrites them back to default.

Prerequisites

  • The helm tool method was used to deploy Che.

  • The kubectl tool is available.

Procedure

  1. Set the configMap variable to reflect the requested PVC strategy:

    CHE_INFRA_KUBERNETES_PVC_STRATEGY=per-workspace

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

  2. Restart Che by scaling the deployment to zero and then back to one again:

    $ oc scale --replicas=0 deployment {prod-deployment}
$ oc scale --replicas=1 deployment {prod-deployment}

  3. Restart the workspace for the changes to take effect.

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 spec.storage.pvcStrategy property of the CheCluster Custom Resource object YAML file.

Prerequisites

  • The kubectl tool is available.

Procedure

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.