docs: manage workspaces with kubectl

modules/end-user-guide/pages/managing-workspaces-with-apis.adoc

@@ -1,22 +1,25 @@
 :_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` 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.
+
+Each `DevWorkspace` custom resource also references a `DevWorkspaceTemplate` custom resource using the `spec.contributions` field, which provides details about the IDE for the workspace.
 
 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,215 @@
 [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 new 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.
+* Secures workspace access by default, using the `routingClass: che` in the workspace's `DevWorkspace`
+* Recognition of configurations in `spec.devEnvironments` specified in the `CheCluster` custom resource including:
+** Persistent storage strategy specified with `devEnvironments.storage`
+** Default IDE specified with `devEnvironments.defaultEditor`
+** Default plugins specified with `devEnvironments.defaultPlugins`
+** Container build configuration specified with `devEnvironments.containerBuildConfiguration`
+* Recognition of the `DevWorkspaceOperatorConfig` configuration managed by {prod-short}
+
+====
+
+.Prerequisites
+
+* An active `{orch-cli}` session with permissions to create `DevWorkspace` and `DevWorkspaceTemplate` 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 on the {prod-short} user namespace on the cluster.
++
+NOTE: {prod-short} administrators who intend to create workspaces for other users must create the `DevWorkspace` and `DevWorkspaceTemplate` custom resources in a user namespace that is provisioned by {prod-short} or by the administrator. See xref:administration-guide:configuring-namespace-provisioning.adoc[].
+
+.Procedure
+
+. Create a `DevWorkspaceTemplate` custom resource for the selected IDE.
++
+.Creating a `DevWorkspaceTemplate` named `che-code` for the link:https://github.com/microsoft/vscode[Microsoft Visual Studio Code - Open Source] IDE
+====
+[source,yaml,subs="+quotes,+attributes"]
+----
+apiVersion: workspace.devfile.io/v1alpha2
+kind: DevWorkspaceTemplate
+metadata:
+  name: che-code#<1>
+  namespace: user1-dev#<2>
+spec:
+  commands:
+    - apply:
+        component: vscode-injector
+      id: init-container-command
+  components:
+    - container:
+        command:
+          - /entrypoint-init-container.sh
+        cpuLimit: 500m
+        cpuRequest: 30m
+        image: 'quay.io/che-incubator/che-code:insiders'
+        memoryLimit: 128Mi
+        memoryRequest: 32Mi
+        sourceMapping: /projects
+        volumeMounts:
+          - name: checode
+      name: vscode-injector
+    - attributes:
+        app.kubernetes.io/component: vscode-runtime
+        app.kubernetes.io/part-of: vscode.eclipse.org
+        controller.devfile.io/container-contribution: true
+      container:
+        cpuRequest: 30m
+        command:
+          - /checode/entrypoint-volume.sh
+        env:
+          - name: CODE_HOST
+            value: 0.0.0.0
+        memoryRequest: 256Mi
+        sourceMapping: /projects
+        cpuLimit: 500m
+        volumeMounts:
+          - name: checode
+            path: /checode
+        memoryLimit: 1024Mi
+        image: 'quay.io/che-incubator/che-code:insiders'
+        endpoints:
+          - attributes:
+              cookiesAuthEnabled: true
+              discoverable: false
+              type: main
+              urlRewriteSupported: true
+            exposure: public
+            name: che-code
+            protocol: https
+            secure: false
+            targetPort: 3100
+          - attributes:
+              discoverable: false
+              urlRewriteSupported: true
+            exposure: public
+            name: code-redirect-1
+            protocol: http
+            targetPort: 13131
+          - attributes:
+              discoverable: false
+              urlRewriteSupported: true
+            exposure: public
+            name: code-redirect-2
+            protocol: http
+            targetPort: 13132
+          - attributes:
+              discoverable: false
+              urlRewriteSupported: true
+            exposure: public
+            name: code-redirect-3
+            protocol: http
+            targetPort: 13133
+      name: vscode-runtime-description
+    - name: checode
+      volume:
+        ephemeral: true
+  events:
+    preStart:
+      - init-container-command
+----
+<1> Name of the `DevWorkspaceTemplate` custom resource. This name will be used to reference the `DevWorkspaceTemplate` custom resource within the `DevWorkspace` custom resource.
+<2> User namespace, which is the target {orch-namespace} for the new workspace.
+====
+
+. 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.1.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"]
+----
+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
+      kubernetes:
+        name: che-code#<5>
+  template:
+    projects:#<6>
+      - name: my-project-name
+        git:
+          remotes:
+            origin: https://github.com/eclipse-che/che-docs
+    components:#<7>
+      - name: tooling-container
+        container:
+          image: quay.io/devfile/universal-developer-image:ubi8-latest
+----
+<1> Name of the `DevWorkspace` custom resource. This is 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> Reference to the `DevWorkspaceTemplate` custom resource of the selected IDE.
+<5> Name of the `DevWorkspaceTemplate` custom resource from the previous step.
+<6> Details about the Git repository to clone into the workspace when it starts.
+<7> 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,57 @@
 
 [id="listing-workspaces"]
-= Listing workspaces
+= Listing all workspaces
 
-Explain why `--all-namespaces`.
+You can list your workspaces on a command line.
 
+.Prerequisites
+
+* An active `{orch-cli}` session 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 on the {prod-short} user namespace on the cluster.
++
+[TIP]
+====
+On OpenShift:
+
+* You can use the `oc` command-line tool to check your current namespace:
++
+`$ oc project`
+
+* You can switch to your {prod-short} user namespace on a command line if needed:
++
+`$ oc project __<user_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,49 @@
 [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 the following command:
+
+`$ {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 on the {prod-short} user namespace on the cluster.
++
+[TIP]
+====
+On OpenShift:
+
+* You can use the `oc` command-line tool to check your current namespace:
++
+`$ oc project`
+
+* You can switch to your {prod-short} user namespace on a command line if needed:
++
+`$ oc project __<user_namespace>__`
+====
+
+.Procedure
+
+* Run the following command to remove the workspace:
++
+[subs="+quotes,attributes"]
+----
+$ {orch-cli} delete devworkspace __<workspace_name>__ -n __<user_namespace>__
+----