Ensure users can run more than one workspace (#1628)

* Ensure users can run more than one workspace

Signed-off-by: Anatolii Bazko <abazko@redhat.com>

* Update modules/installation-guide/partials/proc_configuring-namespace-strategies.adoc

Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com>

* Add procedure to run several workspaces at a time

Signed-off-by: Anatolii Bazko <abazko@redhat.com>

* Review

Signed-off-by: Michal Maléř <mmaler@redhat.com>

* fix

Signed-off-by: Michal Maléř <mmaler@redhat.com>

* Fix message

Signed-off-by: Anatolii Bazko <abazko@redhat.com>

* fix2

Signed-off-by: Michal Maléř <mmaler@redhat.com>

* fix3

Signed-off-by: Michal Maléř <mmaler@redhat.com>

* Apply suggestions from code review

Co-authored-by: Robert Krátký <rkratky@redhat.com>

* renaming the file name

Signed-off-by: Michal Maléř <mmaler@redhat.com>

Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com>
Co-authored-by: Michal Maléř <mmaler@redhat.com>
Co-authored-by: Michal Maléř <48474054+MichalMaler@users.noreply.github.com>
Co-authored-by: Robert Krátký <rkratky@redhat.com>

modules/administration-guide/examples/che-pvc-strategies.adoc

@@ -6,11 +6,11 @@
 One PVC for all workspaces in one {platforms-namespace}
 
 
-| Easy to manage and control storage | If PV does not support `ReadWriteMany` (RWX) access mode, the configuration will work only if one or both of the following apply: 
- 
+| Easy to manage and control storage | If PV does not support `ReadWriteMany` (RWX) access mode, the configuration will work only if one or both of the following apply:
+
 * Each workspace is in a separate {platforms-namespace}
 
-* Only one  workspace is running per {platforms-namespace} at the same time. See xref:installation-guide:configuring-namespace-strategies.adoc[].
+* Only one workspace is running per {platforms-namespace} at the same time. See xref:installation-guide:running-more-than-one-workspace-at-a-time.adoc[].
 |*per-workspace* |
 
 One PVC for one workspace

modules/administration-guide/partials/con_persistent-volume-configuration.adoc

@@ -14,7 +14,7 @@ include::example${project-context}-pvc-strategies.adoc[]
 [id="the-common-pvc-strategy_{context}"]
 == The `common` PVC strategy
 
-All workspaces inside a {platforms-namespace} use the same Persistent Volume Claim (PVC) as the default data storage when storing data such as the following in their declared volumes: 
+All workspaces inside a {platforms-namespace} use the same Persistent Volume Claim (PVC) as the default data storage when storing data such as the following in their declared volumes:
 
 * projects
 * workspace logs
@@ -38,9 +38,9 @@ If there are several nodes, you can use the `common` strategy, but:
 
 * The workspace PVC access mode must be reconfigured to `ReadWriteMany` (RWM), so multiple nodes can use this PVC simultaneously.
 
-* Only one workspace in the same {orch-namespace} may be running. See xref:installation-guide:configuring-namespace-strategies.adoc[].
+* Only one workspace in the same {orch-namespace} may be running. See xref:installation-guide:running-more-than-one-workspace-at-a-time.adoc[].
 
-The `common` PVC strategy is not suitable for large multi-node clusters. Therefore, it is best to use it in single-node clusters. However, in combination with `per-workspace` {orch-namespace} strategy, the `common` PVC strategy is usable for clusters with around 75 nodes. The PVC used in this strategy must be large enough to accommodate all projects since there is a risk of the event, in which one project depletes the resources of others. 
+The `common` PVC strategy is not suitable for large multi-node clusters. Therefore, it is best to use it in single-node clusters. However, in combination with the `per-workspace` {orch-namespace} strategy, the `common` PVC strategy is usable for clusters with not more than 75 nodes. The PVC used with this strategy must be large enough to accommodate all projects to prevent a situation in which one project depletes the resources of others.
 
 [id="the-per-workspace-pvc-strategy_{context}"]
 == The `per-workspace` PVC strategy
@@ -51,7 +51,7 @@ The `per-workspace` strategy is similar to the `common` PVC strategy. The only d
 * workspace logs
 * additional Volumes defined by a user
 
-It’s a strategy when {prod-short} keeps its workspace data in assigned PVs that are allocated by a single PVC. 
+With this strategy, {prod-short} keeps its workspace data in assigned PVs that are allocated by a single PVC.
 
 The `per-workspace` PVC strategy is the most universal strategy out of the PVC strategies available and acts as a proper option for large multi-node clusters with a higher amount of users. Using the `per-workspace` PVC strategy, users can run multiple workspaces simultaneously, results in more PVCs being created.
 
@@ -60,7 +60,7 @@ The `per-workspace` PVC strategy is the most universal strategy out of the PVC s
 
 When using the `unique `PVC strategy, every {prod-short} Volume of a workspace has its own PVC. This means that workspace PVCs are:
 
-Created when a workspace starts for the first time. 
+Created when a workspace starts for the first time.
 Deleted when a corresponding workspace is deleted.
 
 User-defined PVCs are created with the following specifics:

modules/installation-guide/nav.adoc

@@ -32,6 +32,7 @@
 
 ** xref:advanced-configuration-options-for-the-che-server-component.adoc[]
 ** xref:configuring-namespace-strategies.adoc[]
+** xref:running-more-than-one-workspace-at-a-time.adoc[]
 ** xref:configuring-workspace-exposure-strategies.adoc[]
 ** xref:configuring-workspaces-nodeselector.adoc[]
 ** xref:configuring-che-hostname.adoc[]

modules/installation-guide/pages/running-more-than-one-workspace-at-a-time.adoc

@@ -0,0 +1,8 @@
+[id="running-more-than-one-workspace-at-a-time"]
+// = Running more than one workspace at a time
+:navtitle: Running more than one workspace at a time
+:keywords: installation-guide, running-workspaces
+:page-aliases: .:running-more-than-one-workspace-at-a-time
+
+include::partial$proc_running-more-than-one-workspace-at-a-time.adoc[]
+

modules/installation-guide/partials/assembly_advanced-configuration.adoc

@@ -16,6 +16,8 @@ The next sections describe some specific user stories.
 
 * xref:configuring-namespace-strategies.adoc[]
 
+* xref:running-more-than-one-workspace-at-a-time.adoc[]
+
 * xref:configuring-workspaces-nodeselector.adoc[]
 
 * xref:configuring-che-hostname.adoc[]

modules/installation-guide/partials/proc_configuring-namespace-strategies.adoc

@@ -10,6 +10,9 @@ The {platforms-namespace} strategies are configured using the `CHE_INFRA_KUBERNE
 
 WARNING: `CHE_INFRA_KUBERNETES_NAMESPACE` and `CHE_INFRA_OPENSHIFT_PROJECT` are legacy variables. Keep these variables unset for a new installations. Changing these variables during an update can lead to data loss.
 
+WARNING: By default, only one workspace in the same {orch-namespace} can be running at one time. See xref:installation-guide:running-more-than-one-workspace-at-a-time.adoc[].
+
+
 == One {orch-namespace} per workspace strategy
 
 The strategy creates a new {orch-namespace} for each new workspace.
@@ -42,8 +45,6 @@ CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT=__{prod-workspace}__
 ----
 ====
 
-IMPORTANT: To run more than one workspace at a time when using this strategy together with the `common` PVC strategy, configure persistent volumes to use `ReadWriteMany` access mode.
-
 == One {orch-namespace} per user strategy
 
 The strategy isolates each user in their own {orch-namespace}.
@@ -60,23 +61,6 @@ CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT=__{prod-workspace}__-__<username>__
 ----
 ====
 
-[IMPORTANT]
-====
-To run more than one workspace at a time when using this strategy together with the `common` PVC strategy, configure persistent volumes to use `ReadWriteMany` access mode.
-
-To limit the number of concurrently running workspaces per user to one, set the `CHE_LIMITS_USER_WORKSPACES_RUN_COUNT` environment variable to `1`.
-
-// Links to Helm and Operator docs need to be added below:
-
-To limit the number of concurrently running workspaces per user to one (1):
-ifeval::["{project-context}" == "che"]
-
-* For Helm Chart deployments: set the `.global.workspace.number` parameter to `1`.
-endif::[]
-
-* For Operator deployments: set the `spec.server.cheCustomProperties.CHE_LIMITS_USER_WORKSPACE_RUN_COUNT` variable of the CheCluster Custom Resource (CR) to `1`.
-====
-
 == Allowing user-defined workspace {orch-namespace}s
 
 {prod-short} server can be configured to honor the user selection of a {orch-namespace} when a workspace is created. This feature is disabled by default. To allow user-defined workspace {orch-namespace}s:

modules/installation-guide/partials/proc_running-more-than-one-workspace-at-a-time.adoc

@@ -0,0 +1,45 @@
+// Module included in the following assemblies:
+//
+// advanced-configuration
+
+[id="running-more-than-one-workspace-at-a-time_{context}"]
+= Running more than one workspace at a time
+
+This procedure describes how to run more than one workspace simultaneously. This makes it possible for multiple workspace contexts per user to run in parallel.
+
+.Prerequisites
+
+* The `{platforms-cli}` tool is available.
+* An instance of {prod-short} running in {platforms-name}.
++
+[NOTE]
+====
+The following commands use the default {platforms-namespace}, `{prod-namespace}`, as a user's example for the `-n` option.
+====
+
+.Procedure
+
+. Change the default limit of `1` to `-1` to allow an unlimited number of concurrent workspaces per user:
+
+ifeval::["{project-context}" == "che"]
+* For Helm Chart deployments:
++
+[subs="+quotes,+attributes"]
+----
+$ helm upgrade che -n {prod-namespace} --set global.workspace.number=-1
+----
+* For Operator deployments:
++
+endif::[]
+[subs="+quotes,+attributes"]
+----
+$ {orch-cli} patch checluster {prod-checluster} -n {prod-namespace} --type merge \
+  -p '{ "spec": { "server": {"customCheProperties": {"CHE_LIMITS_USER_WORKSPACE_RUN_COUNT": "-1"} } }}'
+----
+
+. Set the `per-workspace` or `unique` PVC strategy. See xref:administration-guide:che-workspaces-architecture.adoc#configuring-a-{prod-id-short}-workspace-with-a-persistent-volume-strategy_{prod-id-short}-workspace-configuration[Configuring a {prod-short} workspace with a persistent volume strategy].
++
+[NOTE]
+====
+When using the _common PVC_ strategy, configure the persistent volumes to use the `ReadWriteMany` access mode. That way, any of the user's concurrent workspaces can read from and write to the common PVC.
+====