docs: manage workspaces with kubectl

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]

modules/end-user-guide/partials/proc_creating-workspaces.adoc

@@ -2,4 +2,121 @@
 [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 {orch-name} 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.
++
+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/main/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.
+
+. Verify that the workspace is starting by checking the *PHASE* status of the `DevWorkspace`.
++
+[subs="+quotes,attributes"]
+----
+$ {orch-cli} get devworkspaces -n __<user_{orch-namespace}>__ --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.

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 link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-project[the `oc` command-line tool] to 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.
+====

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 link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-project[the `oc` command-line tool] to display your current namespace or switch to a namespace.
+====
+
+.Procedure
+
+* Run the following command to remove the workspace:
++
+[subs="+quotes,attributes"]
+----
+$ {orch-cli} delete devworkspace __<workspace_name>__ -n __<user_namespace>__
+----

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 link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-project[the `oc` command-line tool] to display your current namespace or switch to a namespace.
+====
+
+.Procedure
+
+* Run the following command to start the stopped workspace:
++
+[subs="+quotes,attributes"]
+----
+$ {orch-cli} patch devworkspace __<workspace_name>__ \
+-p '{"spec":{"started":true}}' \
+--type=merge -n __<user_namespace>__ && \
+{orch-cli} wait --for=jsonpath='{.status.phase}'=Running \
+dw/__<workspace_name>__ -n __<user_namespace>__
+----

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 link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/developer-cli-commands.html#oc-project[the `oc` command-line tool] to display your current namespace or switch to a namespace.
+====
+
+.Procedure
+
+* Run the following command to stop that workspace:
++
+[subs="+quotes,attributes"]
+----
+$ {orch-cli} patch devworkspace __<workspace_name>__ \
+-p '{"spec":{"started":false}}' \
+--type=merge -n __<user_namespace>__ && \
+{orch-cli} wait --for=jsonpath='{.status.phase}'=Stopped \
+dw/__<workspace_name>__ -n __<user_namespace>__
+----