diff --git a/modules/end-user-guide/pages/managing-workspaces-with-apis.adoc b/modules/end-user-guide/pages/managing-workspaces-with-apis.adoc index 8dc7a7ee1d..8e610dd4b5 100644 --- a/modules/end-user-guide/pages/managing-workspaces-with-apis.adoc +++ b/modules/end-user-guide/pages/managing-workspaces-with-apis.adoc @@ -1,22 +1,23 @@ :_content-type: ASSEMBLY -:navtitle: Managing workspaces with OpenShift APIs -:description: Managing workspaces with OpenShift APIs +:navtitle: Managing workspaces with {orch-name} APIs +:description: Managing workspaces with {orch-name} APIs :keywords: api, list workspaces, create workspace, restart workspace, stop workspace, start workspace, remove workspace // :page-aliases: [id="managing-workspaces-with-apis"] -= Managing workspaces with OpenShift APIs += Managing workspaces with {orch-name} APIs -... +On your organization's {orch-name} cluster, {prod-short} workspaces are represented as `DevWorkspace` custom resources of the same name. +As a result, if there is a workspace named `my-workspace` in the {prod-short} dashboard, there is a corresponding `DevWorkspace` custom resource named `my-workspace` in the user's {orch-namespace} on the cluster. -Consider writing this entire page as a reference. (If so, then rename all the files in `/partials/` and in the `include::` statements below from `proc_` to `ref_`.) +Because each `DevWorkspace` custom resource on the cluster represents a {prod-short} workspace, you can manage {prod-short} workspaces by using {orch-name} APIs with clients such as the command-line `{orch-cli}`. + +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. include::partial$proc_listing-workspaces.adoc[leveloffset=+1] include::partial$proc_creating-workspaces.adoc[leveloffset=+1] -include::partial$proc_restarting-workspaces.adoc[leveloffset=+1] - include::partial$proc_stopping-workspaces.adoc[leveloffset=+1] include::partial$proc_starting-stopped-workspaces.adoc[leveloffset=+1] diff --git a/modules/end-user-guide/partials/proc_creating-workspaces.adoc b/modules/end-user-guide/partials/proc_creating-workspaces.adoc index 6ec486ba7f..09747814dc 100644 --- a/modules/end-user-guide/partials/proc_creating-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_creating-workspaces.adoc @@ -2,4 +2,127 @@ [id="creating-workspaces"] = Creating workspaces -Rough technical info to be dumped here by the assigned SME. +If your use case does not permit use of the {prod-short} dashboard, you can create workspaces with {orch-name} APIs by applying custom resources to the cluster. + +[NOTE] +==== + +Creating workspaces through the {prod-short} 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. +* {platforms-name} clients work automatically. +* {prod-short} 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 {prod-short}. +* 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 `{orch-cli}` session with permissions to create `DevWorkspace` resources in your {orch-namespace} on the cluster. See {orch-cli-link}. + +* You know the relevant {prod-short} user namespace on the cluster. ++ +TIP: You can visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`. + +* You are in the {prod-short} user namespace on the cluster. ++ +[TIP] +==== +On OpenShift, you can use the command-line `oc` tool to link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-project[display your current namespace or switch to a namespace]. +==== ++ +NOTE: {prod-short} administrators who intend to create workspaces for other users must create the `DevWorkspace` custom resource in a user namespace that is provisioned by {prod-short} or by the administrator. See xref:administration-guide:configuring-namespace-provisioning.adoc[]. + +.Procedure + +. To prepare the `DevWorkspace` custom resource, copy the contents of the target Git repository's devfile. ++ +.Copied devfile contents with `schemaVersion: 2.2.0` +==== +[source,yaml,subs="+quotes,+attributes"] +---- +components: + - name: tooling-container + container: + image: quay.io/devfile/universal-developer-image:ubi8-latest +---- +==== ++ +TIP: For more details, see the link:https://devfile.io/docs/2.2.0/what-is-a-devfile[devfile v2 documentation]. + +. Create a `DevWorkspace` custom resource, pasting the devfile contents from the previous step under the `spec.template` field. ++ +.A `DevWorkspace` custom resource +==== +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +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: pass:c,a,q[{prod-url}]/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 {orch-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 link:https://github.com/microsoft/vscode[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`. ++ +[subs="+quotes,attributes"] +---- +$ {orch-cli} get devworkspaces -n ____ --watch +---- ++ +.Output +==== +[subs="+quotes,attributes"] +---- +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 `{orch-cli} get devworkspaces` command. ++ +.Output +==== +[subs="+quotes,attributes"] +---- +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 `{orch-cli} get devworkspaces` command. +** Open the workspace from the {prod-short} dashboard. diff --git a/modules/end-user-guide/partials/proc_listing-workspaces.adoc b/modules/end-user-guide/partials/proc_listing-workspaces.adoc index b284f39e33..5057e7e860 100644 --- a/modules/end-user-guide/partials/proc_listing-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_listing-workspaces.adoc @@ -1,15 +1,49 @@ [id="listing-workspaces"] -= Listing workspaces += Listing all workspaces -Explain why `--all-namespaces`. +As a user, you can list your workspaces by using the command line. +.Prerequisites + +* An active `{orch-cli}` session with permissions to `get` the `DevWorkspace` resources in your {orch-namespace} on the cluster. See {orch-cli-link}. + +* You know the relevant {prod-short} user namespace on the cluster. ++ +TIP: You can visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`. + +* You are in the {prod-short} user namespace on the cluster. ++ +[TIP] +==== +On OpenShift, you can use the command-line `oc` tool to link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-project[display your current namespace or switch to a namespace]. +==== + +.Procedure + +* To list your workspaces, enter the following on a command line: ++ [source,subs="+attributes"] ---- -$ {orch-cli} get devworkspace --all-namespaces +$ {orch-cli} get devworkspaces ---- ++ +.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 add the `--watch` flag. - -To be confirmed by the assigned SME. +[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 {prod-short} users by including the `--all-namespaces` flag. +==== \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_removing-workspaces.adoc b/modules/end-user-guide/partials/proc_removing-workspaces.adoc index b9eea94b97..07494db078 100644 --- a/modules/end-user-guide/partials/proc_removing-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_removing-workspaces.adoc @@ -2,4 +2,39 @@ [id="removing-workspaces"] = Removing workspaces -Rough technical info to be dumped here by the assigned SME. +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 {prod-short}: for example, the referenced `DevWorkspaceTemplate` and per-workspace `PersistentVolumeClaims`. + +TIP: Remove workspaces by using the {prod-short} dashboard whenever possible. + +.Prerequisites + +* An active `{orch-cli}` session on the cluster. See {orch-cli-link}. + +* You know the workspace name. ++ +[TIP] +==== +You can find the relevant workspace name in the output of `$ {orch-cli} get devworkspaces`. +==== + +* You know the relevant {prod-short} user namespace on the cluster. ++ +TIP: You can visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`. + +* You are in the {prod-short} user namespace on the cluster. ++ +[TIP] +==== +On OpenShift, you can use the command-line `oc` tool to link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-project[display your current namespace or switch to a namespace]. +==== + +.Procedure + +* Run the following command to remove a workspace: ++ +[subs="+quotes,attributes"] +---- +$ {orch-cli} delete devworkspace ____ -n ____ +---- diff --git a/modules/end-user-guide/partials/proc_restarting-workspaces.adoc b/modules/end-user-guide/partials/proc_restarting-workspaces.adoc deleted file mode 100644 index f8cb99310e..0000000000 --- a/modules/end-user-guide/partials/proc_restarting-workspaces.adoc +++ /dev/null @@ -1,5 +0,0 @@ - -[id="restarting-workspaces"] -= Restarting workspaces - -Rough technical info to be dumped here by the assigned SME. diff --git a/modules/end-user-guide/partials/proc_starting-stopped-workspaces.adoc b/modules/end-user-guide/partials/proc_starting-stopped-workspaces.adoc index eeeb12037a..2472b238c4 100644 --- a/modules/end-user-guide/partials/proc_starting-stopped-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_starting-stopped-workspaces.adoc @@ -2,4 +2,39 @@ [id="starting-stopped-workspaces"] = Starting stopped workspaces -Rough technical info to be dumped here by the assigned SME. +You can start a stopped workspace by setting the `spec.started` field in the `Devworkspace` custom resource to `true`. + +.Prerequisites + +* An active `{orch-cli}` session on the cluster. See {orch-cli-link}. + +* You know the workspace name. ++ +[TIP] +==== +You can find the relevant workspace name in the output of `$ {orch-cli} get devworkspaces`. +==== + +* You know the relevant {prod-short} user namespace on the cluster. ++ +TIP: You can visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`. + +* You are in the {prod-short} user namespace on the cluster. ++ +[TIP] +==== +On OpenShift, you can use the command-line `oc` tool to link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-project[display your current namespace or switch to a namespace]. +==== + +.Procedure + +* Run the following command to start a stopped workspace: ++ +[subs="+quotes,attributes"] +---- +$ {orch-cli} patch devworkspace ____ \ +-p '{"spec":{"started":true}}' \ +--type=merge -n ____ && \ +{orch-cli} wait --for=jsonpath='{.status.phase}'=Running \ +dw/____ -n ____ +---- diff --git a/modules/end-user-guide/partials/proc_stopping-workspaces.adoc b/modules/end-user-guide/partials/proc_stopping-workspaces.adoc index f89176068e..13798ae00c 100644 --- a/modules/end-user-guide/partials/proc_stopping-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_stopping-workspaces.adoc @@ -2,4 +2,39 @@ [id="stopping-workspaces"] = Stopping workspaces -Rough technical info to be dumped here by the assigned SME. +You can stop a workspace by setting the `spec.started` field in the `Devworkspace` custom resource to `false`. + +.Prerequisites + +* An active `{orch-cli}` session on the cluster. See {orch-cli-link}. + +* You know the workspace name. ++ +[TIP] +==== +You can find the relevant workspace name in the output of `$ {orch-cli} get devworkspaces`. +==== + +* You know the relevant {prod-short} user namespace on the cluster. ++ +TIP: You can visit `pass:c,a,q[{prod-url}]/api/kubernetes/namespace` to get your {prod-short} user namespace as `name`. + +* You are in the {prod-short} user namespace on the cluster. ++ +[TIP] +==== +On OpenShift, you can use the command-line `oc` tool to link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-project[display your current namespace or switch to a namespace]. +==== + +.Procedure + +* Run the following command to stop a workspace: ++ +[subs="+quotes,attributes"] +---- +$ {orch-cli} patch devworkspace ____ \ +-p '{"spec":{"started":false}}' \ +--type=merge -n ____ && \ +{orch-cli} wait --for=jsonpath='{.status.phase}'=Stopped \ +dw/____ -n ____ +----