docs: merge .../che-docs/pull/2510 into main (#2545)

* edits * move the page from admin to user guide * Update modules/end-user-guide/pages/managing-workspaces-with-apis.adoc * Update modules/end-user-guide/pages/managing-workspaces-with-apis.adoc * docs: manage workspaces with kubectl (#2510) * docs: manage workspaces with kubectl Signed-off-by: dkwon17 <[email protected]> * Add more clarity to "Creating workspaces" section Signed-off-by: dkwon17 <[email protected]> * first edit * first edit * edits * edits * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Max Leonov <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Max Leonov <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Mario Loriedo <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Mario Loriedo <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Mario Loriedo <[email protected]> * Add new bullet points for benefits of using dashboard Signed-off-by: David Kwon <[email protected]> * name to lowercase (otherwise the devworkspace cannot be created) Signed-off-by: David Kwon <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Max Leonov <[email protected]> * Make bullet concise Signed-off-by: David Kwon <[email protected]> * Small rearranging Signed-off-by: David Kwon <[email protected]> * Remove . Signed-off-by: David Kwon <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Max Leonov <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Max Leonov <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Max Leonov <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Angel Misevski <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Angel Misevski <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc * PR feedback update Signed-off-by: David Kwon <[email protected]> * Add tip about referencing using IDE devfile Signed-off-by: David Kwon <[email protected]> * Add another tip Signed-off-by: David Kwon <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Valeriy Svydenko <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc * Reference IDE using devfile url Signed-off-by: David Kwon <[email protected]> * Remove DWT details Signed-off-by: David Kwon <[email protected]> * Update modules/end-user-guide/partials/proc_listing-workspaces.adoc * Update modules/end-user-guide/partials/proc_listing-workspaces.adoc * Replace TIP content with a link to OCP docs * Update modules/end-user-guide/partials/proc_stopping-workspaces.adoc * Update modules/end-user-guide/partials/proc_stopping-workspaces.adoc * Update modules/end-user-guide/pages/managing-workspaces-with-apis.adoc * Replace TIP content with a link to OCP docs * Apply suggestions from code review * Update modules/end-user-guide/partials/proc_listing-workspaces.adoc * Replace TIP content with a link to OCP docs * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc Co-authored-by: Max Leonov <[email protected]> * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc * Apply suggestions from code review * Apply suggestions from code review * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc * Update modules/end-user-guide/partials/proc_creating-workspaces.adoc * Remove /main from url path Signed-off-by: David Kwon <[email protected]> --------- Signed-off-by: dkwon17 <[email protected]> Signed-off-by: David Kwon <[email protected]> Co-authored-by: Max Leonov <[email protected]> Co-authored-by: Mario Loriedo <[email protected]> Co-authored-by: Angel Misevski <[email protected]> Co-authored-by: Valeriy Svydenko <[email protected]> --------- Signed-off-by: dkwon17 <[email protected]> Signed-off-by: David Kwon <[email protected]> Co-authored-by: Fabrice Flore-Thébault <[email protected]> Co-authored-by: Nick Boldt <[email protected]> Co-authored-by: David Kwon <[email protected]> Co-authored-by: Mario Loriedo <[email protected]> Co-authored-by: Angel Misevski <[email protected]> Co-authored-by: Valeriy Svydenko <[email protected]>
eclipse-che · Feb 3, 2023 · 1f50519 · 1f50519
1 parent 5676a66
commit 1f50519
Show file tree

Hide file tree

Showing 7 changed files with 323 additions and 0 deletions.
diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc
@@ -36,6 +36,7 @@
 *** xref:enabling-nuget-artifact-repositories.adoc[]
 * xref:requesting-persistent-storage-for-workspaces.adoc[]
 * xref:integrating-with-kubernetes.adoc[]
+** xref:managing-workspaces-with-apis.adoc[]
 ** xref:automatic-token-injection.adoc[]
 ** xref:navigating-che-from-openshift-developer-perspective.adoc[]
 ** xref:navigating-openshift-web-console-from-che.adoc[]

diff --git a/modules/end-user-guide/pages/managing-workspaces-with-apis.adoc b/modules/end-user-guide/pages/managing-workspaces-with-apis.adoc
@@ -0,0 +1,25 @@
+:_content-type: ASSEMBLY
+: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 {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.
+
+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_stopping-workspaces.adoc[leveloffset=+1]
+
+include::partial$proc_starting-stopped-workspaces.adoc[leveloffset=+1]
+
+include::partial$proc_removing-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
@@ -0,0 +1,128 @@
+
+[id="creating-workspaces"]
+= Creating workspaces
+
+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 __<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.
diff --git a/modules/end-user-guide/partials/proc_listing-workspaces.adoc b/modules/end-user-guide/partials/proc_listing-workspaces.adoc
@@ -0,0 +1,49 @@
+
+[id="listing-workspaces"]
+= Listing all workspaces
+
+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 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 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.
+====
diff --git a/modules/end-user-guide/partials/proc_removing-workspaces.adoc b/modules/end-user-guide/partials/proc_removing-workspaces.adoc
@@ -0,0 +1,40 @@
+
+[id="removing-workspaces"]
+= Removing workspaces
+
+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 __<workspace_name>__ -n __<user_namespace>__
+----
diff --git a/modules/end-user-guide/partials/proc_starting-stopped-workspaces.adoc b/modules/end-user-guide/partials/proc_starting-stopped-workspaces.adoc
@@ -0,0 +1,40 @@
+
+[id="starting-stopped-workspaces"]
+= 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 `{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 __<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>__
+----
diff --git a/modules/end-user-guide/partials/proc_stopping-workspaces.adoc b/modules/end-user-guide/partials/proc_stopping-workspaces.adoc
@@ -0,0 +1,40 @@
+
+[id="stopping-workspaces"]
+= Stopping workspaces
+
+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 __<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>__
+----