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)
or
$ 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. |
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 |
For strategies where creating new namespace is needed, make sure that che ServiceAccount has enough permissions to do so. With OpenShift OAuth, the authenticated User must have privileges to create new namespace.
|
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>
.
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.
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>
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.
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
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 ...
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 namespaces for users
To pre-create namespaces for users, use namespace 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.
We do not recommend to create multiple namespaces for single user. It may lead to undefined behavior. |
On OpenShift with OAuth, target user must have 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)
On Kubernetes, |
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 |