Managing workspaces with Kubernetes APIs

On your organization’s Kubernetes cluster, Che workspaces are represented as DevWorkspace custom resources of the same name. As a result, if there is a workspace named my-workspace in the Che dashboard, there is a corresponding DevWorkspace custom resource named my-workspace in the user’s namespace on the cluster.

Because each DevWorkspace custom resource on the cluster represents a Che workspace, you can manage Che workspaces by using Kubernetes APIs with clients such as the command-line kubectl.

Each DevWorkspace custom resource contains details derived from the devfile of the Git repository cloned for the workspace. For example, a devfile might provide devfile commands and workspace container configurations.

Listing all workspaces

As a user, you can list your workspaces by using the command line.

Prerequisites

An active kubectl session with permissions to get the DevWorkspace resources in your namespace on the cluster. See Overview of kubectl.
You know the relevant Che user namespace on the cluster.

You can visit https://<che_fqdn>/api/kubernetes/namespace to get your Che user namespace as name.
You are in the Che user namespace on the cluster.

On OpenShift, you can use the command-line oc tool to display your current namespace or switch to a namespace.

Procedure

To list your workspaces, enter the following on a command line:

$ kubectl get devworkspaces

Example 1. Output

NAMESPACE   NAME                 DEVWORKSPACE ID             PHASE     INFO
user1-dev   spring-petclinic     workspace6d99e9ffb9784491   Running   https://url-to-workspace.com
user1-dev   golang-example       workspacedf64e4a492cd4701   Stopped   Stopped
user1-dev   python-hello-world   workspace69c26884bbc141f2   Failed    Container tooling has state CrashLoopBackOff

You can view PHASE changes live by adding the --watch flag to this command.

Users with administrative permissions on the cluster can list all workspaces from all Che users by including the --all-namespaces flag.

Creating workspaces

If your use case does not permit use of the Che dashboard, you can create workspaces with Kubernetes APIs by applying custom resources to the cluster.

Creating workspaces through the Che dashboard provides better user experience and configuration benefits compared to using the command line:

As a user, you are automatically logged in to the cluster.
Kubernetes or OpenShift clients work automatically.
Che and its components automatically convert the target Git repository’s devfile into the DevWorkspace and DevWorkspaceTemplate custom resources on the cluster.
Access to the workspace is secured by default with the routingClass: che in the DevWorkspace of the workspace.
Recognition of the DevWorkspaceOperatorConfig configuration is managed by Che.
Recognition of configurations in spec.devEnvironments specified in the CheCluster custom resource including:
- Persistent storage strategy is specified with devEnvironments.storage.
- Default IDE is specified with devEnvironments.defaultEditor.
- Default plugins are specified with devEnvironments.defaultPlugins.
- Container build configuration is specified with devEnvironments.containerBuildConfiguration.

Prerequisites

An active kubectl session with permissions to create DevWorkspace resources in your namespace on the cluster. See Overview of kubectl.
You know the relevant Che user namespace on the cluster.

You can visit https://<che_fqdn>/api/kubernetes/namespace to get your Che user namespace as name.

You are in the Che user namespace on the cluster.

On OpenShift, you can use the command-line oc tool to display your current namespace or switch to a namespace.

Che administrators who intend to create workspaces for other users must create the DevWorkspace custom resource in a user namespace that is provisioned by Che or by the administrator. See Configuring user namespace provisioning.

Procedure

To prepare the DevWorkspace custom resource, copy the contents of the target Git repository’s devfile.
Example 2. Copied devfile contents with schemaVersion: 2.2.0
components: - name: tooling-container container: image: quay.io/devfile/universal-developer-image:ubi8-latest
For more details, see the devfile v2 documentation.

Create a DevWorkspace custom resource, pasting the devfile contents from the previous step under the spec.template field.

Example 3. A DevWorkspace custom resource

kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: my-devworkspace(1)
  namespace: user1-dev(2)
spec:
  routingClass: che
  started: true(3)
  contributions:(4)
    - name: ide
      uri: http://che-dashboard.eclipse-che.svc.cluster.local:8080/dashboard/api/editors/devfile?che-editor=che-incubator/che-code/latest
  template:
    projects:(5)
      - name: my-project-name
        git:
          remotes:
            origin: https://github.com/eclipse-che/che-docs
    components:(6)
      - name: tooling-container
        container:
          image: quay.io/devfile/universal-developer-image:ubi8-latest

1	Name of the `DevWorkspace` custom resource. This will be the name of the new workspace.
2	User namespace, which is the target namespace for the new workspace.
3	Determines whether the workspace must be started when the `DevWorkspace` custom resource is created.
4	URL reference to the Microsoft Visual Studio Code - Open Source IDE devfile.
5	Details about the Git repository to clone into the workspace when it starts.
6	List of components such as workspace containers and volume components.

Apply the DevWorkspace custom resource to the cluster.

Verification

Verify that the workspace is starting by checking the PHASE status of the DevWorkspace.

$ kubectl get devworkspaces -n <user_namespace> --watch

Example 4. Output

NAMESPACE        NAME                  DEVWORKSPACE ID             PHASE      INFO
user1-dev        my-devworkspace       workspacedf64e4a492cd4701   Starting   Waiting for workspace deployment

When the workspace has successfully started, its PHASE status changes to Running in the output of the kubectl get devworkspaces command.
Example 5. Output
NAMESPACE NAME DEVWORKSPACE ID PHASE INFO user1-dev my-devworkspace workspacedf64e4a492cd4701 Running https://url-to-workspace.com
You can then open the workspace by using one of these options:
- Visit the URL provided in the INFO section of the output of the kubectl get devworkspaces command.
- Open the workspace from the Che dashboard.

Stopping workspaces

You can stop a workspace by setting the spec.started field in the Devworkspace custom resource to false.

Prerequisites

An active kubectl session on the cluster. See Overview of kubectl.
You know the workspace name.

You can find the relevant workspace name in the output of $ kubectl get devworkspaces.
You know the relevant Che user namespace on the cluster.

You can visit https://<che_fqdn>/api/kubernetes/namespace to get your Che user namespace as name.
You are in the Che user namespace on the cluster.

On OpenShift, you can use the command-line oc tool to display your current namespace or switch to a namespace.

Procedure

Run the following command to stop a workspace:

$ kubectl patch devworkspace <workspace_name> \
-p '{"spec":{"started":false}}' \
--type=merge -n <user_namespace> && \
kubectl wait --for=jsonpath='{.status.phase}'=Stopped \
dw/<workspace_name> -n <user_namespace>

Starting stopped workspaces

You can start a stopped workspace by setting the spec.started field in the Devworkspace custom resource to true.

Prerequisites

An active kubectl session on the cluster. See Overview of kubectl.
You know the workspace name.

You can find the relevant workspace name in the output of $ kubectl get devworkspaces.
You know the relevant Che user namespace on the cluster.

You can visit https://<che_fqdn>/api/kubernetes/namespace to get your Che user namespace as name.
You are in the Che user namespace on the cluster.

On OpenShift, you can use the command-line oc tool to display your current namespace or switch to a namespace.

Procedure

Run the following command to start a stopped workspace:

$ kubectl patch devworkspace <workspace_name> \
-p '{"spec":{"started":true}}' \
--type=merge -n <user_namespace> && \
kubectl wait --for=jsonpath='{.status.phase}'=Running \
dw/<workspace_name> -n <user_namespace>

Removing workspaces

You can remove a workspace by simply deleting the DevWorkspace custom resource.

Deleting the DevWorkspace custom resource will also delete other workspace resources if they were created by Che: for example, the referenced DevWorkspaceTemplate and per-workspace PersistentVolumeClaims.

Remove workspaces by using the Che dashboard whenever possible.

Prerequisites

An active kubectl session on the cluster. See Overview of kubectl.
You know the workspace name.

You can find the relevant workspace name in the output of $ kubectl get devworkspaces.
You know the relevant Che user namespace on the cluster.

You can visit https://<che_fqdn>/api/kubernetes/namespace to get your Che user namespace as name.
You are in the Che user namespace on the cluster.

On OpenShift, you can use the command-line oc tool to display your current namespace or switch to a namespace.

Procedure

Run the following command to remove a workspace:

$ kubectl delete devworkspace <workspace_name> -n <user_namespace>