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://<openshift_dev_spaces_fqdn>/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://<openshift_dev_spaces_fqdn>/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.13/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://<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
.$ 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://<openshift_dev_spaces_fqdn>/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://<openshift_dev_spaces_fqdn>/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://<openshift_dev_spaces_fqdn>/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.