Requesting persistent storage for workspaces

Che workspaces and workspace data are ephemeral and are lost when the workspace stops.

To preserve the workspace state in persistent storage while the workspace is stopped, request a Kubernetes PersistentVolume (PV) for the DevWorkspace containers in the Kubernetes cluster of your organization’s Che instance.

You can request a PV by using the devfile or a Kubernetes PersistentVolumeClaim (PVC).

An example of a PV is the /projects/ directory of a workspace, which is mounted by default for non-ephemeral workspaces.

Persistent Volumes come at a cost: attaching a persistent volume slows workspace startup.

Starting another, concurrently running workspace with a ReadWriteOnce PV might fail.

Additional resources

Requesting persistent storage in a devfile

When a workspace requires its own persistent storage, request a PersistentVolume (PV) in the devfile, and Che will automatically manage the necessary PersistentVolumeClaims.

Prerequisites

You have not started the workspace.

Procedure

Add a volume component in the devfile:

...
components:
  ...
  - name: <chosen_volume_name>
    volume:
      size: <requested_volume_size>G
  ...

Add a volumeMount for the relevant container in the devfile:

...
components:
  - name: ...
    container:
      ...
      volumeMounts:
        - name: <chosen_volume_name_from_previous_step>
          path: <path_where_to_mount_the_PV>
      ...

Example 1. A devfile that provisions a PV for a workspace to a container

When a workspace is started with the following devfile, the cache PV is provisioned to the golang container in the ./cache container path:

schemaVersion: 2.1.0
metadata:
  name: mydevfile
components:
  - name: golang
    container:
      image: golang
      memoryLimit: 512Mi
      mountSources: true
      command: ['sleep', 'infinity']
      volumeMounts:
        - name: cache
          path: /.cache
  - name: cache
    volume:
      size: 2Gi

Requesting persistent storage in a PVC

You can opt to apply a PersistentVolumeClaim (PVC) to request a PersistentVolume (PV) for your workspaces in the following cases:

Not all developers of the project need the PV.
The PV lifecycle goes beyond the lifecycle of a single workspace.
The data included in the PV are shared across workspaces.

You can apply a PVC to the DevWorkspace containers even if the workspace is ephemeral and its devfile contains the controller.devfile.io/storage-type: ephemeral attribute.

Prerequisites

You have not started the workspace.
An active kubectl session with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.
A PVC is created in your user namespace to mount to all DevWorkspace containers.

Procedure

Add the controller.devfile.io/mount-to-devworkspace: true label to the PVC.

$ kubectl label persistentvolumeclaim <PVC_name> \
          controller.devfile.io/mount-to-devworkspace=true

Optional: Use the annotations to configure how the PVC is mounted:

Table 1. Optional annotations
Annotation	Description
`controller.devfile.io/mount-path:`	The mount path for the PVC. Defaults to `/tmp/<PVC_name>`.
`controller.devfile.io/read-only:`	Set to `'true'` or `'false'` to specify whether the PVC is to be mounted as read-only. Defaults to `'false'`, resulting in the PVC mounted as read/write.

Example 2. Mounting a read-only PVC

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <pvc_name>
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
  annotations:
    controller.devfile.io/mount-path: </example/directory> (1)
    controller.devfile.io/read-only: 'true'
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 3Gi (2)
  storageClassName: <storage_class_name> (3)
  volumeMode: Filesystem

1	The mounted PV is available at `</example/directory>` in the workspace.
2	Example size value of the requested storage.
3	The name of the StorageClass required by the claim. Remove this line if you want to use a default StorageClass.