SupportConsoleDevelopersStart a trialContact

Chapter 8. Integrating with OpenShift

8.1. Managing workspaces with OpenShift APIs

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

Because each DevWorkspace custom resource on the cluster represents a OpenShift Dev Spaces workspace, you can manage OpenShift Dev Spaces workspaces by using OpenShift APIs with clients such as the command-line oc.

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.

8.1.1. Listing all workspaces

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

Prerequisites

  • An active oc session with permissions to get the DevWorkspace resources in your project on the cluster. See Getting started with the CLI.

  • You know the relevant OpenShift Dev Spaces user namespace on the cluster.

    Tip

    You can visit https://<openshift_dev_spaces_fqdn>/api/kubernetes/namespace to get your OpenShift Dev Spaces user namespace as name.

  • You are in the OpenShift Dev Spaces user namespace on the cluster.

    Tip

    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: 

    $ oc get devworkspaces

    Example 8.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
Tip

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

Note

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

8.1.2. Creating workspaces

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

Note

Creating workspaces through the OpenShift Dev Spaces 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.
  • OpenShift clients work automatically.
  • OpenShift Dev Spaces 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 OpenShift Dev Spaces.

  • 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

Procedure

  1. To prepare the DevWorkspace custom resource, copy the contents of the target Git repository’s devfile.

    Example 8.2. Copied devfile contents with schemaVersion: 2.2.0

    components:
  - name: tooling-container
    container:
      image: quay.io/devfile/universal-developer-image:ubi8-latest
    Tip

    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 8.3. A DevWorkspace custom resource

    kind: DevWorkspace
apiVersion: workspace.devfile.io/v1alpha2
metadata:
  name: my-devworkspace1
  namespace: user1-dev2
spec:
  routingClass: che
  started: true3
  contributions:4
    - name: ide
      uri: https://<openshift_dev_spaces_fqdn>/plugin-registry/v3/plugins/che-incubator/che-code/latest/devfile.yaml
  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 project 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 from the plugin registry.
    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.
  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. 

    $ oc get devworkspaces -n <user_project> --watch

    Example 8.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 oc get devworkspaces command.

    Example 8.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 oc get devworkspaces command.
    • Open the workspace from the OpenShift Dev Spaces dashboard.

8.1.3. Stopping workspaces

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

Prerequisites

  • An active oc session on the cluster. See Getting started with the CLI.

  • You know the workspace name.

    Tip

    You can find the relevant workspace name in the output of $ oc get devworkspaces.

  • You know the relevant OpenShift Dev Spaces user namespace on the cluster.

    Tip

    You can visit https://<openshift_dev_spaces_fqdn>/api/kubernetes/namespace to get your OpenShift Dev Spaces user namespace as name.

  • You are in the OpenShift Dev Spaces user namespace on the cluster.

    Tip

    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: 

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

8.1.4. 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 oc session on the cluster. See Getting started with the CLI.

  • You know the workspace name.

    Tip

    You can find the relevant workspace name in the output of $ oc get devworkspaces.

  • You know the relevant OpenShift Dev Spaces user namespace on the cluster.

    Tip

    You can visit https://<openshift_dev_spaces_fqdn>/api/kubernetes/namespace to get your OpenShift Dev Spaces user namespace as name.

  • You are in the OpenShift Dev Spaces user namespace on the cluster.

    Tip

    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: 

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

8.1.5. Removing workspaces

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

Warning

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

Tip

Remove workspaces by using the OpenShift Dev Spaces dashboard whenever possible.

Prerequisites

  • An active oc session on the cluster. See Getting started with the CLI.

  • You know the workspace name.

    Tip

    You can find the relevant workspace name in the output of $ oc get devworkspaces.

  • You know the relevant OpenShift Dev Spaces user namespace on the cluster.

    Tip

    You can visit https://<openshift_dev_spaces_fqdn>/api/kubernetes/namespace to get your OpenShift Dev Spaces user namespace as name.

  • You are in the OpenShift Dev Spaces user namespace on the cluster.

    Tip

    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: 

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

8.2. Automatic OpenShift token injection

This section describes how to use the OpenShift user token that is automatically injected into workspace containers which allows running OpenShift Dev Spaces CLI commands against OpenShift cluster.

Procedure

  1. Open the OpenShift Dev Spaces dashboard and start a workspace.
  2. Once the workspace is started, open a terminal in the container that contains the OpenShift Dev Spaces CLI.

  3. Execute OpenShift Dev Spaces CLI commands which allow you to run commands against OpenShift cluster. CLI can be used for deploying applications, inspecting and managing cluster resources, and viewing logs. OpenShift user token will be used during the execution of the commands.

    Token Injection in IDE
Warning

The automatic token injection currently works only on the OpenShift infrastructure.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.