Configuring workspace target namespace

The Kubernetes namespace or OpenShift project where a new workspace is deployed depends on the Che server configuration. Che deploys each workspace into a user’s dedicated namespace, which hosts all Che workspaces created by the user. The name of a Kubernetes namespace or OpenShift project must be provided as a Che server configuration property or pre-created by Che administrator.

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

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

The underlying environment variable that Che server uses is CHE_INFRA_KUBERNETES_NAMESPACE_DEFAULT.

By default, only one workspace in the same namespace can be running at one time. See Configuring the number of workspaces that a user can run.

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 multihost 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 in CheCluster Custom Resource:

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

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 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 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.

Do not create multiple namespaces for a single user. It may lead to undefined behavior.

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: <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 ServiceAccount 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` ServiceAccount
3	Che installation namespace
4	name of the cluster role created in previous step

A lack of permissions does not prevent a Che workspace from starting, it only logs the warning. If you see the warnings in Che logs, consider disabling the feature by defining CHE_INFRA_KUBERNETES_NAMESPACE_LABEL=false.