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 toget
theDevWorkspace
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.
TipYou can visit
"https://devspaces-<openshift_deployment_name>.<domain_name>"/api/kubernetes/namespace
to get your OpenShift Dev Spaces user namespace asname
.You are in the OpenShift Dev Spaces user namespace on the cluster.
TipOn 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
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 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.
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
andDevWorkspaceTemplate
custom resources on the cluster. -
Access to the workspace is secured by default with the
routingClass: che
in theDevWorkspace
of the workspace. -
Recognition of the
DevWorkspaceOperatorConfig
configuration is managed by OpenShift Dev Spaces. Recognition of configurations in
spec.devEnvironments
specified in theCheCluster
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
.
-
Persistent storage strategy is specified with
Prerequisites
-
An active
oc
session with permissions to createDevWorkspace
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.
TipYou can visit
"https://devspaces-<openshift_deployment_name>.<domain_name>"/api/kubernetes/namespace
to get your OpenShift Dev Spaces user namespace asname
.You are in the OpenShift Dev Spaces user namespace on the cluster.
TipOn OpenShift, you can use the command-line
oc
tool to display your current namespace or switch to a namespace.NoteOpenShift 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.4/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
TipFor more details, see the devfile v2 documentation.
Create a
DevWorkspace
custom resource, pasting the devfile contents from the previous step under thespec.template
field.Example 8.3. A
DevWorkspace
custom resourcekind: DevWorkspace apiVersion: workspace.devfile.io/v1alpha2 metadata: name: my-devworkspace1 namespace: user1-dev2 spec: routingClass: che started: true3 contributions:4 - name: ide uri: "https://devspaces-<openshift_deployment_name>.<domain_name>"/plugin-registry/v3/plugins/che-incubator/che-code/insiders/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
.$ 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
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.
-
Visit the URL provided in the INFO section of the output of the
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.
TipYou 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.
TipYou can visit
"https://devspaces-<openshift_deployment_name>.<domain_name>"/api/kubernetes/namespace
to get your OpenShift Dev Spaces user namespace asname
.You are in the OpenShift Dev Spaces user namespace on the cluster.
TipOn 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.
TipYou 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.
TipYou can visit
"https://devspaces-<openshift_deployment_name>.<domain_name>"/api/kubernetes/namespace
to get your OpenShift Dev Spaces user namespace asname
.You are in the OpenShift Dev Spaces user namespace on the cluster.
TipOn 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.
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
.
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.
TipYou 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.
TipYou can visit
"https://devspaces-<openshift_deployment_name>.<domain_name>"/api/kubernetes/namespace
to get your OpenShift Dev Spaces user namespace asname
.You are in the OpenShift Dev Spaces user namespace on the cluster.
TipOn 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
- 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.
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.
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.