Configuring namespace strategies

The Kubernetes namespace or OpenShift project where a new workspace Pod is deployed depends on the Che server configuration. By default, every workspace is deployed in a distinct Kubernetes namespace or OpenShift project, but the user can configure the Che server to deploy all workspaces in one specific Kubernetes namespace or OpenShift project. The name of a Kubernetes namespace or OpenShift project must be provided as a Che server configuration property and cannot be changed at runtime.

The term namespace (Kubernetes) is used interchangeably with project (OpenShift).

With Operator installer, Kubernetes namespace or OpenShift project strategies are configured using server.workspaceNamespaceDefault property.

Operator CheCluster CR patch

apiVersion: org.eclipse.che/v1
kind: CheCluster
metadata:
  name: <che-cluster-name>
spec:
  server:
    workspaceNamespaceDefault: <workspace-namespace> (1)

1	- Che workspace namespace configuration

With Helm installer, Kubernetes namespaces strategies are configured using global.cheWorkspacesNamespace property.

Helm

$ helm install --namespace <namespace>
  --set global.cheWorkspacesNamespace=<workspace-namespace> (1)

$ helm upgrade --namespace <namespace>
  --set global.cheWorkspacesNamespace=<workspace-namespace> (1)

1	- Che workspace namespace configuration

The underlying environment variable that Che server uses is CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT.

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.

By default, only one workspace in the same namespace can be running at one time. See Running more than one workspace at a time.

The namespace strategies other than per user are deprecated and are subject to removal.

Kubernetes limits the length of a namespace name to 63 characters (this includes the evaluated placeholders). Additionally, the names (after placeholder evaluation) must be valid DNS names.

On OpenShift with multi-host server exposure strategy, the length is further limited to 49 characters.

Be aware that the <userid> placeholder is evaluated into a 36 character long UUID string.

Use Pre-creating a namespace for each user when:

che ServiceAccount does not have enough permissions when creating new namespace

OpenShift OAuth with a self-provisioner cluster role is not linked to the`system:authenticated:oauth` group

Che cannot create namespaces

One namespace per user strategy

The strategy isolates each user in their own namespace.

To use the strategy, set the Che workspace namespace configuration value to contain one or more user identifiers. Currently supported identifiers are <username> and <userid>.

Example 1. One namespace per user

To assign namespace names composed of a `che-ws` prefix and individual usernames (che-ws-user1, che-ws-user2), set:

Operator installer (CheCluster CustomResource)

...
spec:
  server:
    workspaceNamespaceDefault: che-ws-<username>
...

Helm

$ helm ... --set global.cheWorkspacesNamespace=che-ws-<username>

One namespace per workspace strategy

The strategy creates a new namespace for each new workspace.

To use the strategy, set the Che workspace namespace configuration value to contain the <workspaceID> identifier. It can be used alone or combined with other identifiers or any string.

Example 2. One namespace per workspace

To assign namespace names composed of a `che-ws` prefix and workspace id, set:

Operator installer (CheCluster CustomResource)

...
spec:
  server:
    workspaceNamespaceDefault: che-ws-<workspaceID>
...

Helm

$ helm ... --set global.cheWorkspacesNamespace=che-ws-<workspaceID>

This strategy is deprecated and is subject to removal.

One namespace for all workspaces strategy

The strategy uses one predefined namespace for all workspaces.

To use the strategy, set the Che workspace namespace configuration value to the name of the desired namespace to use.

Example 3. One namespace for all workspaces

To have all workspaces created in `che-ws` namespace, set:

Operator installer (CheCluster CustomResource)

...
spec:
  server:
    workspaceNamespaceDefault: che-ws
...

Helm

$ helm ... --set global.cheWorkspacesNamespace=che-ws

This strategy is deprecated and is subject to removal.

Allowing user-defined workspace namespaces

Che server can be configured to honor the user selection of a namespace when a workspace is created. This feature is disabled by default. To allow user-defined workspace namespaces:

For Helm Chart deployments, set the following environment variable in the Che ConfigMap:
```
CHE_INFRA_KUBERNETES_NAMESPACE_ALLOW__USER__DEFINED=true
```
For Operator deployments, set the following field in the CheCluster Custom Resource:
```
...
server:
  allowUserDefinedWorkspaceNamespaces: true
...
```
This parameter is deprecated and is subject to removal.

Handling incompatible usernames or user IDs

Che server automatically checks usernames and IDs for compatibility with Kubernetes objects naming convention before creating a namespace from a template. Incompatible username or IDs are reduced to the nearest valid name by replacing groups of unsuitable symbols with the - symbol. To avoid collisions, a random 6-symbol suffix is added and the result is stored in preferences for reuse.

Pre-creating a namespace for each user

To pre-create a namespace for each user, use Kubernetes labels and annotations. Such 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: <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 Che server component system properties reference for more details.

Avoid creating multiple namespaces for single user. It may lead to undefined behavior.

On OpenShift with OAuth, target user must have admin role privileges in target namespace:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: admin
  namespace: <namespace> (1)
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: admin
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: <username> (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

Che updates the workspace’s namespace on workspace startup by adding the labels defined in CHE_INFRA_KUBERNETES_NAMESPACE_LABELS. To do so, che ServiceAccout has to have the following cluster-wide permissions to update and get namespaces:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: <cluster-role-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: <cluster-role-binding-name> (1)
subjects:
  - kind: ServiceAccount
    name: <service-account-name> (2)
    namespace: <service-accout-namespace> (3)
roleRef:
  kind: ClusterRole
  name: <cluster-role-name> (4)
  apiGroup: rbac.authorization.k8s.io

1	name of the cluster role binding
2	name of the che service account
3	Che installation namespace
4	name of the cluster role created in previous step

Che does not fail to start a workspace for lack of permissions, it only logs the warning. If you see the warnings in Che logs, consider disabling the feature with setting CHE_INFRA_KUBERNETES_NAMESPACE_LABEL=false.