procedures: Configuring workspace target namespace, Provisioning name…

…spaces (#2301)

Co-authored-by: Ilya Buziuk <[email protected]>
Co-authored-by: Brian Burt <[email protected]>

modules/administration-guide/nav.adoc

@@ -31,13 +31,15 @@
 *** xref:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[]
 *** xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]
 *** xref:checluster-custom-resource-fields-reference.adoc[]
+** xref:configuring-namespace-provisioning.adoc[]
+*** xref:configuring-workspace-target-namespace.adoc[]
+*** xref:provisioning-namespaces-in-advance.adoc[]
 ** xref:configuring-server-components.adoc[]
 *** xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc[]
 *** xref:advanced-configuration-options-for-the-che-server-component.adoc[]
 ** xref:configuring-workspaces-globally.adoc[]
 *** xref:configuring-the-number-of-workspaces-that-a-user-can-create.adoc[]
 *** xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]
-*** xref:configuring-namespace-strategies.adoc[]
 *** xref:configuring-workspaces-nodeselector.adoc[]
 ** xref:caching-images-for-faster-workspace-start.adoc[]
 *** xref:defining-the-list-of-images-to-pull.adoc[]

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

@@ -6,29 +6,5 @@
 [id="configuring-che_{context}"]
 = Configuring {prod-short}
 
-The following chapter describes configuration methods and options for {prod}.
-
-* xref:advanced-configuration-options-for-the-che-server-component.adoc[] describes advanced configuration methods to use when the previous method is not applicable.
-
-Specific use-cases:
-
-* xref:configuring-namespace-strategies.adoc[]
-
-* xref:configuring-the-number-of-workspaces-that-a-user-can-create.adoc[]
-
-* xref:configuring-workspaces-nodeselector.adoc[]
-
-* xref:configuring-che-hostname.adoc[]
-
-* xref:configuring-ingresses.adoc[]
-
-* xref:configuring-routes.adoc[]
-
-* xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]
-
-* xref:installing-che-using-storage-classes.adoc[]
-
-* xref:importing-untrusted-tls-certificates.adoc[]
-
-* xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc[]
+This section describes configuration methods and options for {prod}.
 

modules/administration-guide/pages/configuring-namespace-provisioning.adoc

@@ -0,0 +1,17 @@
+:_content-type: CONCEPT
+:navtitle: Configuring {orch-namespace}s
+:keywords: administration guide, configuring, namespace
+:page-aliases: installation-guide:configuring-namespace-strategies, configuring-namespace-strategies
+
+[id="configuring-user-{orch-namespace}-provisioning_{context}"]
+= Configuring user {orch-namespace} provisioning
+
+For each user, {prod-short} isolates workspaces in a {orch-namespace}. 
+{prod-short} identifies the user {orch-namespace} by the presence of labels and annotations.
+When starting a workspace, if the required {orch-namespace} doesn't exist, {prod-short} creates the {orch-namespace} using a template name. 
+
+You can modify {prod-short} behavior by:
+
+* xref:configuring-workspace-target-namespace.adoc[]
+* xref:provisioning-namespaces-in-advance.adoc[]
+

modules/administration-guide/pages/configuring-workspace-target-namespace.adoc

@@ -0,0 +1,61 @@
+:_content-type: PROCEDURE
+:navtitle: Configuring {orch-namespace} name
+:keywords: administration guide, configuring, namespace
+:page-aliases: 
+
+[id="configuring-a-user-{orch-namespace}-name-for-automatic-provisioning_{context}"]
+= Configuring a user {orch-namespace} name for automatic provisioning
+
+You can configure the {orch-namespace} name template that {prod-short} uses to create the required {orch-namespace} when starting a workspace.
+
+A valid {orch-namespace} name template follows these conventions:
+
+* The `<username>` or `<userid>` placeholder is mandatory.
+
+* Usernames and IDs cannot contain invalid characters. If the formatting of a username or ID is incompatible with the naming conventions for {orch-name} objects, {prod-short} changes the username or ID to a valid name by replacing incompatible characters with the `-` symbol. 
+
+* {prod-short} evaluates the `<userid>` placeholder into a 14 character long string, and adds a random six character long suffix to prevent IDs from colliding. The result is stored in the user preferences for reuse.
+
+* {kubernetes} limits the length of a {orch-namespace} name to 63 characters. 
+
+* OpenShift limits the length further to 49 characters.
+
+
+
+.Procedure
+
+* Set the `server.workspaceNamespaceDefault` property in CheCluster Custom Resource:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+kind: CheCluster
+apiVersion: org.eclipse.che/v1
+# ...
+spec:
+  server:
+    workspaceNamespaceDefault: __<workspace_namespace_template_>__
+# ...
+----
++
+.User workspaces {orch-namespace} name template examples
+====
+[%header,cols="1,1"]  
+|=== 
+|User workspaces {orch-namespace} name template
+|Resulting {orch-namespace} example
+
+|`<username>-{prod-id-short}` (default)
+|user1-{prod-id-short}
+
+|`<userid>-namespace` 
+|`cge1egvsb2nhba-namespace-ul1411` 
+
+|`<userid>-aka-<username>-namespace`
+|`cgezegvsb2nhba-aka-user1-namespace-6m2w2b`
+|=== 
+====
+
+.Additional resources
+
+* xref:understanding-the-checluster-custom-resource.adoc[]
+

modules/administration-guide/pages/configuring-workspaces-globally.adoc

@@ -6,7 +6,10 @@
 [id="configuring-workspaces-globally_{context}"]
 = Configuring workspaces globally
 
+This section describes how an administrator can configure workspaces globally.
+
 * xref:configuring-the-number-of-workspaces-that-a-user-can-create.adoc[]
+
 * xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]
-* xref:configuring-namespace-strategies.adoc[]
+
 * xref:configuring-workspaces-nodeselector.adoc[]

modules/administration-guide/pages/provisioning-namespaces-in-advance.adoc

@@ -0,0 +1,33 @@
+:_content-type: PROCEDURE
+:navtitle: Provisioning {orch-namespace}s in advance
+:keywords: administration guide, provisioning, {orch-namespace}
+:page-aliases: 
+
+[id="preprovisioning-{orch-namespace}s_{context}"]
+= Provisioning {orch-namespace}s in advance
+
+You can provision workpaces {orch-namespace}s in advance, rather than relying on automatic provisioning. Repeat the procedure for each user.
+
+.Procedure
+
+* Create the __<{orch-namespace}_name>__ {orch-namespace} for __<username>__ user with the following labels and annotations:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+kind: Namespace
+apiVersion: v1
+metadata:
+  name: __<{orch-namespace}_name>__ <1>
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: workspaces-namespace
+  annotations:
+    che.eclipse.org/username: __<username>__
+----
+<1> Use a {orch-namespace} name of your choosing.
+
+.Additional resources
+
+* xref:understanding-the-checluster-custom-resource.adoc[]
+* xref:advanced-configuration-options-for-the-che-server-component.adoc[]
+