procedures: update admin docs for storage classes, storage strategies…

… and storage size (#2536)

Co-authored-by: Jana Vrbkova <[email protected]>

modules/administration-guide/nav.adoc

@@ -59,7 +59,9 @@
 *** xref:importing-untrusted-tls-certificates.adoc[]
 *** xref:adding-labels-and-annotations.adoc[]
 ** xref:configuring-storage.adoc[]
-*** xref:installing-che-using-storage-classes.adoc[]
+*** xref:configuring-storage-classes.adoc[]
+*** xref:configuring-the-storage-strategy.adoc[]
+*** xref:configuring-storage-sizes.adoc[]
 ** xref:managing-identities-and-authorizations.adoc[]
 *** xref:configuring-oauth-for-git-providers.adoc[]
 **** xref:configuring-oauth-2-for-github.adoc[]

modules/administration-guide/pages/installing-che-using-storage-classes.adoc → modules/administration-guide/pages/configuring-storage-classes.adoc

@@ -1,10 +1,10 @@
-:_content-type: CONCEPT
-:description: Installing {prod-short} using storage classes
-:keywords: administration guide, installing-che-using-storage-classes
-:navtitle: Installing {prod-short} using storage classes
-:page-aliases: installation-guide:installing-che-using-storage-classes.adoc
+:_content-type: PROCEDURE
+:description: Configuring storage classes
+:keywords: administration guide, configuring, {prod-id-short}, storage class, storage classes
+:navtitle: Configuring storage classes
+:page-aliases: installation-guide:configuring-storage-classes.adoc
 
-[id="installing-{prod-id-short}-using-storage-classes"]
+[id="configuring-storage-classes"]
 = Configuring storage classes
 
 To configure {prod-short} to use a configured infrastructure storage, install {prod-short} using storage classes. This is especially useful when you want to bind a persistent volume provided by a non-default provisioner.
@@ -18,10 +18,11 @@ To configure {prod-short} to use a configured infrastructure storage, install {p
 {prod-short} workspaces source code is stored in the persistent volume only if a workspace is not ephemeral.
 ====
 
-.Persistent volume claims facts:
+Persistent volume claims facts:
 
 * {prod-short} does not create persistent volumes in the infrastructure.
 * {prod-short} uses persistent volume claims (PVC) to mount persistent volumes.
+* The xref:devworkspace-operator.adoc[Dev Workspace operator] creates persistent volume claims.
 +
 Define a storage class name in the {prod-short} configuration to use the storage classes feature in the {prod-short} PVC.
 

modules/administration-guide/pages/configuring-storage-sizes.adoc

@@ -0,0 +1,56 @@
+:_content-type: PROCEDURE
+:description: Configuring storage sizes
+:keywords: administration guide, configuring, {prod-id-short}, storage sizes, PVC size, pvc
+:navtitle: Configuring storage sizes
+:page-aliases: installation-guide:configuring-storage-sizes.adoc
+
+[id="configuring-storage-sizes"]
+= Configuring storage sizes
+
+You can configure the persistent volume claim (PVC) size using the `per-user` or `per-workspace` storage strategies. You must specify the PVC sizes in the `CheCluster` Custom Resource in the format of a link:https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/[{kubernetes} resource quantity]. For more details on the available storage strategies, see xref:configuring-the-storage-strategy.adoc[this page].
+
+Default persistent volume claim sizes:
+
+* {empty}
++
+[source,yaml]
+----
+per-user: 10Gi
+----
+
+* {empty}
++
+[source,yaml]
+----
+per-workspace: 5Gi
+----
+
+
+.Procedure
+
+. Set the appropriate `claimSize` field for the desired storage strategy in the Che Cluster Custom Resource.
+
+[NOTE]
+====
+
+* You can set this field at installation. See xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[].
+
+* You can update this field on the command line. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
+
+====
+
+[source,yaml,subs="+quotes,+attributes"]
+----
+spec:
+  devEnvironments:
+    storage:
+      pvc:
+        pvcStrategy: '__<strategy_name>__'  <1>
+        perUserStrategyPvcConfig: <2>
+          claimSize: __<resource_quantity>__ <3>
+        perWorkspaceStrategyPvcConfig:  <2>
+          claimSize: __<resource_quantity>__ <3>
+----
+<1> Select the storage strategy: `per-user` or `per-workspace` or `ephemeral`. Note: the `ephemeral` storage strategy does not use persistent storage, therefore you cannot configure its storage size or other PVC-related attributes. 
+<2> Specify a claim size on the next line or omit the next line to set the default claim size value. The specified claim size is only used when you select this storage strategy.
+<3> The claim size must be specified as a link:https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/[{kubernetes} resource quantity]. The available quantity units include: `Ei`, `Pi`, `Ti`, `Gi`,  `Mi` and `Ki`.

modules/administration-guide/pages/configuring-storage.adoc

@@ -12,4 +12,6 @@
 {prod-short} does not support the Network File System (NFS) protocol.
 ====
 
-* xref:installing-che-using-storage-classes.adoc[]
+* xref:configuring-storage-classes.adoc[]
+* xref:configuring-the-storage-strategy.adoc[]
+* xref:configuring-storage-sizes.adoc[]

modules/administration-guide/pages/configuring-the-storage-strategy.adoc

@@ -0,0 +1,41 @@
+:_content-type: PROCEDURE
+:description: Configuring the storage strategy 
+:keywords: administration guide, configuring, {prod-short}, storage, strategy, per-user, per-workspace, ephemeral
+:navtitle: Configuring the storage strategy
+:page-aliases: installation-guide:configuring-the-storage-strategy.adoc
+
+[id="configuring-the-storage-strategy"]
+= Configuring the storage strategy
+
+{prod-short} can be configured to provide persistent or non-persistent storage to workspaces by selecting a storage strategy. The selected storage strategy will be applied to all newly created workspaces by default. Users can opt for a non-default storage strategy for their workspace in their xref:end-user-guide:requesting-persistent-storage-for-workspaces.adoc[devfile] or through the xref:end-user-guide:url-parameter-for-the-workspace-storage.adoc[URL parameter].
+
+Available storage strategies:
+
+* `per-user`: Use a single PVC for all workspaces created by a user.
+* `per-workspace`: Each workspace is given its own PVC.
+* `ephemeral`: Non-persistent storage; any local changes will be lost when the workspace is stopped.
+
+The default storage strategy used in {prod-short} is `per-user`. 
+
+.Procedure
+
+. Set the `pvcStrategy` field in the Che Cluster Custom Resource to `per-user`, `per-workspace` or `ephemeral`.
+
+[NOTE]
+====
+
+* You can set this field at installation. See xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[].
+
+* You can update this field on the command line. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[].
+
+====
+
+[source,yaml,subs="+quotes,+attributes"]
+----
+spec:
+  devEnvironments:
+    storage:
+      pvc:
+        pvcStrategy: 'per-user' <1>   
+----
+<1> The available storage strategies are `per-user`, `per-workspace` and `ephemeral`.