Manage workspaces from the command line

Manage Che workspaces with kubectl and kubectl to list, create, stop, start, and remove workspaces without using the dashboard.

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.

List all workspaces

List your workspaces from the command line to check their status, identify stopped or failed workspaces, and monitor resource usage across your Che environment.

Prerequisites

  • You have 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. 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 Kubernetes, use kubectl to display your current namespace or switch to a namespace.

Procedure

  1. List your workspaces:

    $ 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

  2. Optional: Add the --watch flag to show PHASE changes live:

    $ kubectl get devworkspaces --watch

  3. Optional: Add the --all-namespaces flag to list workspaces from all Che users. This requires administrative permissions on the cluster.

    $ kubectl get devworkspaces --all-namespaces

Create workspaces

If your use case does not permit use of the Che dashboard, 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.

    • Available AI providers are configured through an ai-tool-registry ConfigMap in the eclipse-che namespace.
Prerequisites

  • You have an active kubectl session with permissions to create DevWorkspace resources in your namespace on the cluster. See Overview of kubectl.

  • You know your Che user namespace on the cluster. Visit https://<che_fqdn>/api/kubernetes/namespace to get your Che user namespace as name.

  • You are in your Che user namespace on the cluster. On Kubernetes, use kubectl 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

  1. Copy the contents of the target Git repository’s devfile to prepare the DevWorkspace custom resource.

    Example 2. Copied devfile contents with schemaVersion: 2.2.0
    components:
  - name: tooling-container
    container:
      image: quay.io/devfile/universal-developer-image:ubi9-latest
    For more details, see the devfile v2 documentation.

  2. 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:ubi9-latest
          env:
            - name: CHE_DASHBOARD_URL
              value: https://<che_fqdn>/dashboard/ (7)
    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.
    7 URL to Che dashboard

  3. Apply the DevWorkspace custom resource to the cluster.

Verification

  1. 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

  2. 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.

Stop workspaces

Stop a workspace by setting the spec.started field in the DevWorkspace custom resource to false.

Prerequisites

  • You have an active kubectl session on the cluster. See Overview of kubectl.

  • You have the workspace name. Run kubectl get devworkspaces to list workspace names.

  • You have the relevant Che user namespace on the cluster. 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 Kubernetes, use kubectl to display your current namespace or switch to a namespace.

Procedure

  1. 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>

Start stopped workspaces

Start a stopped workspace by setting the spec.started field in the DevWorkspace custom resource to true.

Prerequisites

  • You have an active kubectl session on the cluster. See Overview of kubectl.

  • You have the workspace name. Run kubectl get devworkspaces to list workspace names.

  • You have the relevant Che user namespace on the cluster. 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 Kubernetes, use kubectl to display your current namespace or switch to a namespace.

Procedure

  1. 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>

Remove workspaces

Remove a workspace from the command line by deleting its DevWorkspace custom resource. The Che dashboard is the recommended method for routine operations.

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

  • You have an active kubectl session on the cluster. See Overview of kubectl.

  • You know the workspace name. Run kubectl get devworkspaces to list workspace names.

  • You know the relevant Che user namespace on the cluster. Visit https://<che_fqdn>/api/kubernetes/namespace to get your Che user namespace as name. On Kubernetes, use kubectl to display your current namespace or switch to a namespace.

  • You are in the Che user namespace on the cluster.

Procedure

  • Run the following command to remove a workspace:

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