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 4a35141bce..d96d0715b8 100644 --- a/modules/end-user-guide/pages/managing-workspaces-with-apis.adoc +++ b/modules/end-user-guide/pages/managing-workspaces-with-apis.adoc @@ -7,16 +7,14 @@ [id="managing-workspaces-with-apis"] = Managing workspaces with {orch-name} APIs -On a {platforms-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 `DevWorkspace` named `my-workspace` in the user's {orch-namespace} on the {orch-name} cluster. +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. -Since `DevWorkspaces` on the cluster represent {prod-short} workspaces, this allows managing {prod-short} workspaces using {orch-name} APIs with clients such as {orch-cli}. +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 workspace project's devfile, such as workspace container configurations and devfile commands. +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` also references a `DevWorkspaceTemplate` custom resource using the `spec.contributions` field, which contains details about the editor for the workspace. - -To manage a workspace with {orch-name} APIs, you must determine the workspace `NAME` and the `NAMESPACE` it is located in. +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] diff --git a/modules/end-user-guide/partials/proc_creating-workspaces.adoc b/modules/end-user-guide/partials/proc_creating-workspaces.adoc index 6a5e2963ce..f67fbefe40 100644 --- a/modules/end-user-guide/partials/proc_creating-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_creating-workspaces.adoc @@ -2,38 +2,60 @@ [id="creating-workspaces"] = Creating workspaces -Since workspaces on the {orch-name} cluster are represented by custom resources, it is possible to create workspaces with {orch-name} APIs by applying custom resources to the cluster. +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. -It is recommended however, for users to create workspaces using the {prod-short} Dashboard instead of using {orch-name} APIs to manually create `DevWorkspace` and `DevWorkspaceTemplate` custom resources. +[NOTE] +==== -This is because creating workspaces using the {prod-short} Dashboard helps {prod-short} and its components convert the workspace project's devfile to `DevWorkspace` and `DevWorkspaceTemplate` custom resources on the cluster. - -Creating workspaces using the {prod-short} Dashboard allows {prod-short} to make the following additions to the newly created `DevWorkspaces`: +Using the {prod-short} dashboard is the default way to create workspaces because {prod-short} and its components automatically convert the target Git repository's devfile into the `DevWorkspace` and `DevWorkspaceTemplate` custom resources on the cluster with the following configuration benefits: * Recognition of configurations in `spec.devEnvironments` specified in the `CheCluster` custom resource including: -** persistent storage strategy specified with `devEnvironments.storage` -** default editor specified with `devEnvironments.defaultEditor` -** default plugins specified with `devEnvironments.defaultPlugins` -** container build configuration specified with `devEnvironments.containerBuildConfiguration` +** 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 {orch-name} cluster. See {orch-cli-link}. +* 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`. -NOTE: For admins creating workspaces for users, the `DevWorkspace` and `DevWorkspaceTemplate` custom resources should be created in a user namespace that is provisioned by {prod-short} or provisioned by the admin. See xref:administration-guide:configuring-namespace-provisioning.adoc[]. +* 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 ____` +==== ++ +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` for the editor. The example below creates a `DevWorkspaceTemplate` named `che-code` for the Che-Code Visual Studio Code editor. +. 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: ____ <2> + name: che-code#<1> + namespace: user1-dev#<2> spec: commands: - apply: @@ -70,7 +92,7 @@ spec: - name: checode path: /checode memoryLimit: 1024Mi - image: 'quay.io/che-incubator/che-code:insiders' # no-op ignored image + image: 'quay.io/che-incubator/che-code:insiders' endpoints: - attributes: cookiesAuthEnabled: true @@ -111,68 +133,92 @@ spec: preStart: - init-container-command ---- -<1> Name of the `DevWorkspaceTemplate`. This name will be used to reference the `DevWorkspaceTemplate` within the `DevWorkspace`. -<2> Target {orch-namespace} for the new workspace. -. To prepare the `DevWorkspace` custom resource, copy the contents of a project Devfile. The example used for this procedure is the following Devfile: +<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.1.0` +==== [source,yaml,subs="+quotes,+attributes"] ---- -schemaVersion: 2.1.0 components: - name: tooling-container container: image: quay.io/devfile/universal-developer-image:ubi8-latest ---- +==== + -For more details about Devfiles, see the link:https://devfile.io/docs/2.1.0/what-is-a-devfile[Devfile v2 documentation]. +TIP: For more details, see the link:https://devfile.io/docs/2.1.0/what-is-a-devfile[devfile v2 documentation]. -. Use the Devfile to create a `DevWorkspace` definition. +. Create a `DevWorkspace` custom resource definition, pasting the devfile contents from the previous step under the `spec.template` field. + +.A `DevWorkspace` custom resource definition +==== [source,yaml,subs="+quotes,+attributes"] ---- kind: DevWorkspace apiVersion: workspace.devfile.io/v1alpha2 metadata: - name: my-devworkspace <1> - namespace: ____ <2> + name: my-devworkspace#<1> + namespace: user1-dev#<2> spec: - started: true <3> - contributions: <4> - - name: editor + started: true#<3> + contributions:#<4> + - name: IDE kubernetes: - name: che-code <5> + name: che-code#<5> template: - projects: <6> + projects:#<6> - name: my-project-name git: remotes: origin: https://github.com/eclipse-che/che-docs - components: <7> + components:#<7> - name: tooling-container container: image: quay.io/devfile/universal-developer-image:ubi8-latest ---- -<1> Name of `DevWorkspace` resource. This is will be the name of the new workspace. -<2> Target {orch-namespace} for the new workspace. -<3> Determines whether the workspace should be started upon creating the `DevWorkspace` resource. -<4> Reference to the editor's `DevWorkspaceTemplate`. -<5> Name of the editor's `DevWorkspaceTemplate` from the previous step. -<6> Details about the Git project to clone upon workspace startup. The Git project that will be cloned for this example is https://github.com/eclipse-che/che-docs. +<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` to the cluster. -. Confirm that the workspace is starting by referring to the `PHASE` status of the `DevWorkspace`. +==== + +. 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 ____ --watch - +---- ++ +.Output +==== +[subs="+quotes,attributes"] +---- NAMESPACE NAME DEVWORKSPACE ID PHASE INFO -____ my-devworkspace workspacedf64e4a492cd4701 Starting Waiting for workspace deployment +user1-dev my-devworkspace workspacedf64e4a492cd4701 Starting Waiting for workspace deployment ---- -. Once the workspace starts, the workspace can be opened by accessing the URL provided in the `INFO` section of the output from `{orch-cli} get devworkspaces`, or by accessing the workspace from the {prod-short} Dashboard. +==== + +. 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 -____ my-devworkspace workspacedf64e4a492cd4701 Running https://url-to-workspace.com +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 01db9842db..70617950b3 100644 --- a/modules/end-user-guide/partials/proc_listing-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_listing-workspaces.adoc @@ -2,28 +2,56 @@ [id="listing-workspaces"] = Listing all workspaces -Run the following command to list all workspaces for all users. +You can list your workspaces on a command line. -[source,subs="+attributes"] ----- -$ {orch-cli} get devworkspaces +.Prerequisites -NAMESPACE NAME DEVWORKSPACE ID PHASE INFO -user1-dev golang-example workspacedf64e4a492cd4701 Stopped Stopped -user1-dev php-symfony workspace5a8f37a0a0d94ea3 Stopped Stopped ----- +* 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: -TIP: You can add the `--watch` flag to view updates when the workspace's `PHASE` changes. +* You can use the `oc` command-line tool to check your current namespace: ++ +`$ oc project` -Admins can add the `--all-namespaces` flag to list all workspaces from all users. +* You can switch to your {prod-short} user namespace on a command line if needed: ++ +`$ oc project ____` +==== +.Procedure + +* To list your workspaces, enter the following on a command line: ++ [source,subs="+attributes"] ---- -$ {orch-cli} get devworkspaces --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 php-symfony workspace5a8f37a0a0d94ea3 Stopped Stopped -user2-dev python-hello-world workspace69c26884bbc141f2 Failed Container tooling has state CrashLoopBackOff -user3-dev spring-petclinic workspace6d99e9ffb9784491 Running https://url-to-workspace.com +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. +==== \ 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 267832696e..cb4589125c 100644 --- a/modules/end-user-guide/partials/proc_removing-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_removing-workspaces.adoc @@ -2,11 +2,49 @@ [id="removing-workspaces"] = Removing workspaces -Removing a workspace only requires deleting the `DevWorkspace` custom resource. +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 {prod-short} such as the referenced `DevWorkspaceTemplate` and per-workspace `PersistentVolumeClaims`. +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`. -[source,subs="+attributes"] +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 ____` +==== + +.Procedure + +* Run the following command to remove the workspace: ++ +[subs="+quotes,attributes"] ---- -$ {orch-cli} delete devworkspace NAME -n NAMESPACE +$ {orch-cli} delete devworkspace ____ -n ____ ---- 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 068c5f2442..7ee03f9959 100644 --- a/modules/end-user-guide/partials/proc_starting-stopped-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_starting-stopped-workspaces.adoc @@ -2,14 +2,46 @@ [id="starting-stopped-workspaces"] = Starting stopped workspaces -A stopped workspace can be started by setting the `Devworkspace` 's `spec.started` field to `true`. +You can start a stopped workspace by setting the `spec.started` field in the `Devworkspace` custom resource to `true`. -To use the `wait` command to wait for the status change, a minimum version of `1.23` for `kubectl`, or a minimum version of `4.10` for `oc` is required. +.Prerequisites -After determining the `NAME` and `NAMESPACE` of the workspace to start, run: +* An active `{orch-cli}` session on the cluster. See {orch-cli-link}. -[source,subs="+attributes"] +* 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 ____` +==== + +.Procedure + +* Run the following command to start the stopped workspace: ++ +[subs="+quotes,attributes"] ---- -$ {orch-cli} patch devworkspace NAME -p '{"spec":{"started":true}}' --type=merge -n NAMESPACE && \ - {orch-cli} wait --for=jsonpath='{.status.phase}'=Running dw/NAME -n NAMESPACE +$ {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 2dc276c6a5..27cbeeb263 100644 --- a/modules/end-user-guide/partials/proc_stopping-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_stopping-workspaces.adoc @@ -2,14 +2,46 @@ [id="stopping-workspaces"] = Stopping workspaces -A workspace can be stopped by setting the `Devworkspace` 's `spec.started` field to `false`. +You can stop a workspace by setting the `spec.started` field in the `Devworkspace` custom resource to `false`. -To use the `wait` command to wait for the status change, a minimum version of `1.23` for `kubectl`, or a minimum version of `4.10` for `oc` is required. +.Prerequisites -After determining the `NAME` and `NAMESPACE` of the workspace to stop, run: +* An active `{orch-cli}` session on the cluster. See {orch-cli-link}. -[source,subs="+attributes"] +* 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 ____` +==== + +.Procedure + +* Run the following command to stop that workspace: ++ +[subs="+quotes,attributes"] ---- -$ {orch-cli} patch devworkspace NAME -p '{"spec":{"started":false}}' --type=merge -n NAMESPACE && \ - {orch-cli} wait --for=jsonpath='{.status.phase}'=Stopped dw/NAME -n NAMESPACE +$ {orch-cli} patch devworkspace ____ -p '{"spec":{"started":false}}' --type=merge -n ____ && \ + {orch-cli} wait --for=jsonpath='{.status.phase}'=Stopped dw/____ -n ____ ----