Chapter 8. Integrating with OpenShift
Chapter 8. Integrating with OpenShift Section 8.2, "Automatic OpenShift token injection" Section 8.3, "Navigating Dev Spaces from OpenShift Developer Perspective" Section 8.4, "Navigating OpenShift web console from Dev Spaces" 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: Example 8.1. Output 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 An active oc session with permissions to create 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 . Note OpenShift Dev Spaces administrators who intend to create workspaces for other users must create the DevWorkspace custom resource in a user namespace that is provisioned by OpenShift Dev Spaces or by the administrator. See https://access.redhat.com/documentation/en-us/red_hat_openshift_dev_spaces/3.14/html-single/administration_guide/index#administration-guide:configuring-namespace-provisioning . Procedure 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 . Create a DevWorkspace custom resource, pasting the devfile contents from the step under the spec.template field. Example 8.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: 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. Apply the DevWorkspace custom resource to the cluster. Verification Verify that the workspace is starting by checking the PHASE status of the DevWorkspace . Example 8.4. Output 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 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 USD 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: 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 USD 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: 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 USD 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: 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 Open the OpenShift Dev Spaces dashboard and start a workspace. Once the workspace is started, open a terminal in the container that contains the OpenShift Dev Spaces CLI. 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. Warning The automatic token injection currently works only on the OpenShift infrastructure. 8.3. Navigating Dev Spaces from OpenShift Developer Perspective The OpenShift Container Platform web console provides two perspectives; the Administrator perspective and the Developer perspective. The Developer perspective provides workflows specific to developer use cases, such as the ability to: Create and deploy applications on the OpenShift Container Platform by importing existing codebases, images, and Dockerfiles. Visually interact with applications, components, and services associated with them within a project and monitor their deployment and build status. Group components within an application and connect the components within and across applications. Integrate serverless capabilities (Technology Preview). Create workspaces to edit your application code using OpenShift Dev Spaces. 8.3.1. OpenShift Developer Perspective integration with OpenShift Dev Spaces This section provides information about OpenShift Developer Perspective support for OpenShift Dev Spaces. When the OpenShift Dev Spaces Operator is deployed into OpenShift Container Platform 4.2 and later, it creates a ConsoleLink Custom Resource (CR). This adds an interactive link to the Red Hat Applications menu for accessing the OpenShift Dev Spaces installation using the OpenShift Developer Perspective console. To access the Red Hat Applications menu, click the three-by-three matrix icon on the main screen of the OpenShift web console. The OpenShift Dev Spaces Console Link , displayed in the drop-down menu, creates a new workspace or redirects the user to an existing one. Note OpenShift Container Platform console links are not created when OpenShift Dev Spaces is used with HTTP resources When installing OpenShift Dev Spaces with the From Git option, the OpenShift Developer Perspective console link is only created if OpenShift Dev Spaces is deployed with HTTPS. The console link will not be created if an HTTP resource is used. 8.3.2. Editing the code of applications running in OpenShift Container Platform using OpenShift Dev Spaces This section describes how to start editing the source code of applications running on OpenShift using OpenShift Dev Spaces. Prerequisites OpenShift Dev Spaces is deployed on the same OpenShift 4 cluster. Procedure Open the Topology view to list all projects. In the Select an Application search field, type workspace to list all workspaces. Click the workspace to edit. The deployments are displayed as graphical circles surrounded by circular buttons. One of these buttons is Edit Source Code . To edit the code of an application using OpenShift Dev Spaces, click the Edit Source Code button. This redirects to a workspace with the cloned source code of the application component. 8.3.3. Accessing OpenShift Dev Spaces from Red Hat Applications menu This section describes how to access OpenShift Dev Spaces workspaces from the Red Hat Applications menu on the OpenShift Container Platform. Prerequisites The OpenShift Dev Spaces Operator is available in OpenShift 4. Procedure Open the Red Hat Applications menu by using the three-by-three matrix icon in the upper right corner of the main screen. The drop-down menu displays the available applications. Click the OpenShift Dev Spaces link to open the Dev Spaces Dashboard. 8.4. Navigating OpenShift web console from Dev Spaces This section describes how to access OpenShift web console from OpenShift Dev Spaces. Prerequisites The OpenShift Dev Spaces Operator is available in OpenShift 4. Procedure Open the OpenShift Dev Spaces dashboard and click the three-by-three matrix icon in the upper right corner of the main screen. The drop-down menu displays the available applications. Click the OpenShift console link to open the OpenShift web console.
oc get devworkspaces 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 components: - name: tooling-container container: image: quay.io/devfile/universal-developer-image:ubi8-latest 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: 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 oc get devworkspaces -n <user_project> --watch NAMESPACE NAME DEVWORKSPACE ID PHASE INFO user1-dev my-devworkspace workspacedf64e4a492cd4701 Starting Waiting for workspace deployment NAMESPACE NAME DEVWORKSPACE ID PHASE INFO user1-dev my-devworkspace workspacedf64e4a492cd4701 Running https://url-to-workspace.com oc patch devworkspace <workspace_name> -p '{"spec":{"started":false}}' --type=merge -n <user_namespace> && wait --for=jsonpath='{.status.phase}'=Stopped dw/ <workspace_name> -n <user_namespace> oc patch devworkspace <workspace_name> -p '{"spec":{"started":true}}' --type=merge -n <user_namespace> && wait --for=jsonpath='{.status.phase}'=Running dw/ <workspace_name> -n <user_namespace> oc delete devworkspace <workspace_name> -n <user_namespace>