From 759295d45e9f59c160d228dc79dc0646541c9fa4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 27 Apr 2022 10:53:10 +0200 Subject: [PATCH] procedures: Configuring workspace target namespace, Provisioning namespaces (#2301) Co-authored-by: Ilya Buziuk Co-authored-by: Brian Burt <86380613+bburt-rh@users.noreply.github.com> --- modules/administration-guide/nav.adoc | 4 +- .../pages/configuring-che.adoc | 26 +-- .../configuring-namespace-provisioning.adoc | 17 ++ .../configuring-namespace-strategies.adoc | 167 ------------------ ...onfiguring-workspace-target-namespace.adoc | 61 +++++++ .../configuring-workspaces-globally.adoc | 5 +- .../provisioning-namespaces-in-advance.adoc | 33 ++++ 7 files changed, 119 insertions(+), 194 deletions(-) create mode 100644 modules/administration-guide/pages/configuring-namespace-provisioning.adoc delete mode 100644 modules/administration-guide/pages/configuring-namespace-strategies.adoc create mode 100644 modules/administration-guide/pages/configuring-workspace-target-namespace.adoc create mode 100644 modules/administration-guide/pages/provisioning-namespaces-in-advance.adoc diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index bf417f80a3..11ed6c06c6 100644 --- a/modules/administration-guide/nav.adoc +++ b/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[] diff --git a/modules/administration-guide/pages/configuring-che.adoc b/modules/administration-guide/pages/configuring-che.adoc index 4d56ed6d3e..a2aa92052f 100644 --- a/modules/administration-guide/pages/configuring-che.adoc +++ b/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}. diff --git a/modules/administration-guide/pages/configuring-namespace-provisioning.adoc b/modules/administration-guide/pages/configuring-namespace-provisioning.adoc new file mode 100644 index 0000000000..86220d4fd8 --- /dev/null +++ b/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[] + diff --git a/modules/administration-guide/pages/configuring-namespace-strategies.adoc b/modules/administration-guide/pages/configuring-namespace-strategies.adoc deleted file mode 100644 index edf8f38e0a..0000000000 --- a/modules/administration-guide/pages/configuring-namespace-strategies.adoc +++ /dev/null @@ -1,167 +0,0 @@ -:_content-type: CONCEPT -:navtitle: Configuring workspace target {orch-namespace} -:keywords: administration guide, configuring, namespace -:page-aliases: installation-guide:configuring-namespace-strategies - -[id="configuring-namespace-strategies_{context}"] -= Configuring workspace target {orch-namespace} - -The {platforms-namespace} where a new workspace is deployed depends on the {prod-short} server configuration. {prod-short} deploys each workspace into a user's dedicated {orch-namespace}, which hosts all {prod-short} workspaces created by the user. The name of a {platforms-namespace} must be provided as a {prod-short} server configuration property or pre-created by {prod-short} administrator. - -{platforms-namespace} names are configured using `server.workspaceNamespaceDefault` property. - -*Operator CheCluster CR patch* -[subs="+quotes,+attributes"] ----- -apiVersion: org.eclipse.che/v1 -kind: CheCluster -metadata: - name: -spec: - server: - workspaceNamespaceDefault: ____ <1> ----- -<1> - {prod-short} workspace {orch-namespace} configuration - - -NOTE: The underlying environment variable that {prod-short} server uses is `CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT`. - -WARNING: Only one workspace in the same {orch-namespace} can be running at one time. - -[WARNING] -==== -{kubernetes} limits the length of a {orch-namespace} name to 63 characters (this includes the evaluated placeholders). Additionally, the names (after placeholder evaluation) must be valid DNS names. - -On OpenShift with multihost server exposure strategy, the length is further limited to 49 characters. - -Be aware that the `__` placeholder is evaluated into a 36 character long UUID string. -==== - -[WARNING] -==== -Use <> when: - -* `che` ServiceAccount does not have enough permissions when creating new {orch-namespace} - -pass:[] - -* OpenShift OAuth with a `self-provisioner` cluster role is not linked to the `system:authenticated:oauth` group - -pass:[] - -* {prod-short} cannot create namespaces -==== - -== One {orch-namespace} per user strategy - -The strategy isolates each user in their own {orch-namespace}. - -To use the strategy, set the _{prod-short} workspace {orch-namespace} configuration_ value to contain one or more user identifiers. Currently supported identifiers are `__` and `__`. - -.One {orch-namespace} per user -==== -To assign {orch-namespace} names composed of a __`{prod-workspace}`__ prefix and individual usernames (`__{prod-workspace}__-user1`, `__{prod-workspace}__-user2`), set in CheCluster Custom Resource: - -[subs="+quotes,+attributes"] ----- -... -spec: - server: - workspaceNamespaceDefault: __{prod-workspace}__-____ -... ----- -==== - -== Handling incompatible usernames or user IDs - -{prod-short} server automatically checks usernames and IDs for compatibility with {orch-name} objects naming convention before creating a {orch-namespace} from a template. Incompatible usernames or IDs are reduced to the nearest valid name by replacing groups of unsuitable symbols with the `-` symbol. The addition of a random 6-symbol suffix prevents IDs from collisions. The result is stored in preferences for reuse. - -[#pre-creating-namespace] -== Pre-creating a {orch-namespace} for each user - -To pre-create a {orch-namespace} for each user, use {orch-name} labels and annotations. Such {orch-namespace} is used in preference to `CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT` variable. - ----- -metadata: - labels: - app.kubernetes.io/part-of: che.eclipse.org - app.kubernetes.io/component: workspaces-namespace - annotations: - che.eclipse.org/username: <1> ----- -<1> target user's username - -To configure the labels, set the `CHE_INFRA_KUBERNETES_NAMESPACE_LABELS` to desired labels. To configure the annotations, set the `CHE_INFRA_KUBERNETES_NAMESPACE_ANNOTATIONS` to desired annotations. See the xref:advanced-configuration-options-for-the-che-server-component.adoc[] for more details. - -[WARNING] -==== -Do not create multiple namespaces for a single user. It may lead to undefined behavior. -==== - -[IMPORTANT] -==== -On OpenShift with OAuth, the target user must have `admin` role privileges in the target namespace: ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: admin - namespace: <1> -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: admin -subjects: -- apiGroup: rbac.authorization.k8s.io - kind: User - name: <2> ----- -<1> pre-created namespace -<2> target user - -On {kubernetes}, `che` ServiceAccount must have a cluster-wide `list` and `get` `namespaces` permissions as well as an `admin` role in target namespace. -==== - -== Labeling the namespaces - -{prod-short} updates the workspace's {orch-namespace} on workspace startup by adding the labels defined in `CHE_INFRA_KUBERNETES_NAMESPACE_LABELS`. To do so, `che` ServiceAccount has to have the following cluster-wide permissions to `update` and `get` `namespaces`: - ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: <1> -rules: - - apiGroups: - - "" - resources: - - namespaces - verbs: - - update - - get ----- -<1> name of the cluster role - ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: <1> -subjects: - - kind: ServiceAccount - name: <2> - namespace: <3> -roleRef: - kind: ClusterRole - name: <4> - apiGroup: rbac.authorization.k8s.io ----- -<1> name of the cluster role binding -<2> name of the `che` ServiceAccount -<3> {prod-short} installation namespace -<4> name of the cluster role created in previous step - -[NOTE] -==== -A lack of permissions does not prevent a {prod-short} workspace from starting, it only logs the warning. If you see the warnings in {prod-short} logs, consider disabling the feature by defining `CHE_INFRA_KUBERNETES_NAMESPACE_LABEL=false`. -==== diff --git a/modules/administration-guide/pages/configuring-workspace-target-namespace.adoc b/modules/administration-guide/pages/configuring-workspace-target-namespace.adoc new file mode 100644 index 0000000000..9a1517c304 --- /dev/null +++ b/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 `` or `` 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 `` 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: ____ +# ... +---- ++ +.User workspaces {orch-namespace} name template examples +==== +[%header,cols="1,1"] +|=== +|User workspaces {orch-namespace} name template +|Resulting {orch-namespace} example + +|`-{prod-id-short}` (default) +|user1-{prod-id-short} + +|`-namespace` +|`cge1egvsb2nhba-namespace-ul1411` + +|`-aka--namespace` +|`cgezegvsb2nhba-aka-user1-namespace-6m2w2b` +|=== +==== + +.Additional resources + +* xref:understanding-the-checluster-custom-resource.adoc[] + diff --git a/modules/administration-guide/pages/configuring-workspaces-globally.adoc b/modules/administration-guide/pages/configuring-workspaces-globally.adoc index b311685db2..ef11fc5054 100644 --- a/modules/administration-guide/pages/configuring-workspaces-globally.adoc +++ b/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[] diff --git a/modules/administration-guide/pages/provisioning-namespaces-in-advance.adoc b/modules/administration-guide/pages/provisioning-namespaces-in-advance.adoc new file mode 100644 index 0000000000..c6971b32dd --- /dev/null +++ b/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 ____ 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: ____ +---- +<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[] +