Configuring a user namespace

Learn how to use Che to synchronize ConfigMaps, Secrets, PersistentVolumeClaim and other Kubernetes objects from eclipse-che namespace to numerous user-specific namespaces. The Che automates the synchronization of important configuration data, such as shared credentials, configuration files, and certificates to user namespaces.

If you make changes to a Kubernetes resource in an eclipse-che namespace, Che will immediately synchronize the changes across all users namespaces. In reverse, if a Kubernetes resource is modified in a user namespace, Che will immediately revert the changes.

Applying or modifying a Secret or ConfigMap with the controller.devfile.io/mount-to-devworkspace: 'true' label restarts all running workspaces in the namespace.

To mount the Secret or ConfigMap only at workspace start and prevent automatic restarts, add the controller.devfile.io/mount-on-start: 'true' annotation.

Procedure

Create the ConfigMap below to create and mount it into every workspace.

kind: ConfigMap
apiVersion: v1
metadata:
  name: che-user-configmap
  namespace: eclipse-che
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: workspaces-config
data:
  ...

Optional: Use annotations to configure how the ConfigMap is mounted.

Table 1. Optional annotations
Annotation	Description
`che.eclipse.org/sync-retain-on-delete:`	When set to `"true"`, the ConfigMap is retained in a user namespace after being deleted from eclipse-che namespace.
`controller.devfile.io/mount-on-start:`	When set to `"true"`, the ConfigMap is mounted only at workspace start. This prevents workspace restarts when the ConfigMap is created.
`controller.devfile.io/mount-to-devworkspace-include:`	Specifies a comma-separated list of `DevWorkspace` name patterns. When set, the ConfigMap is mounted only to workspaces whose names match at least one pattern. Patterns support exact match, prefix (name), suffix (name), contains (name).
`controller.devfile.io/mount-to-devworkspace-exclude:`	Specifies a comma-separated list of `DevWorkspace` name patterns. When set, the ConfigMap is mounted to all workspaces except those whose names at least one pattern. Patterns support exact match, prefix (name), suffix (name), contains (name).

When both annotations controller.devfile.io/mount-to-devworkspace-include and controller.devfile.io/mount-to-devworkspace-exclude are set, the resource is mounted only to workspaces that match the include pattern and do not match the exclude pattern.

For other labels and annotations, see Mounting volumes, configmaps, and secrets.

For example, to mount a default SSH configuration into every workspace, you must create a ConfigMap:

kind: ConfigMap
apiVersion: v1
metadata:
  name: ssh-config-configmap
  namespace: eclipse-che
  labels:
    app.kubernetes.io/component: workspaces-config
    app.kubernetes.io/part-of: che.eclipse.org
  annotations:
    controller.devfile.io/mount-as: subpath
    controller.devfile.io/mount-path: /etc/ssh/ssh_config.d/
data:
  ssh.conf: <ssh config content>

This ConfigMap propagates the SSH configuration as an extension to the existing default SSH configuration by using the Include /etc/ssh/ssh_config.d/*.conf argument. For more information, review the Include definition.

Create the Secret below to create and mount it into every workspace.

kind: Secret
apiVersion: v1
metadata:
  name: che-user-secret
  namespace: eclipse-che
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: workspaces-config
stringData:
    ...

Optional: Use annotations to configure how the Secret is mounted.

Table 2. Optional annotations
Annotation	Description
`che.eclipse.org/sync-retain-on-delete:`	When set to `"true"`, the Secret is retained in a user namespace after being deleted from eclipse-che namespace.
`controller.devfile.io/mount-on-start:`	When set to `"true"`, the Secret is mounted only at workspace start. This prevents workspace restarts when the Secret is created.
`controller.devfile.io/mount-to-devworkspace-include:`	Specifies a comma-separated list of `DevWorkspace` name patterns. When set, the ConfigMap is mounted only to workspaces whose names match at least one pattern. Patterns support exact match, prefix (name), suffix (name), contains (name).
`controller.devfile.io/mount-to-devworkspace-exclude:`	Specifies a comma-separated list of `DevWorkspace` name patterns. When set, the ConfigMap is mounted to all workspaces except those whose names at least one pattern. Patterns support exact match, prefix (name), suffix (name), contains (name).

For other labels and annotations, see Mounting volumes, configmaps, and secrets.

Create the PersistentVolumeClaim below to create it to every user namespace.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: che-user-pvc
  namespace: eclipse-che
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: workspaces-config
spec:
  ...

Optional: Use annotations to configure how the PersistentVolumeClaim is mounted.

The PersistentVolumeClaim is not deleted in a user namespace by default, if the one from eclipse-che is deleted.

Table 3. Optional annotations
Annotation	Description
`che.eclipse.org/sync-retain-on-delete:`	When set to `"false"`, the `PersistentVolumeClaim` is deleted in a user namespace when it is deleted from eclipse-che namespace.
`controller.devfile.io/mount-on-start:`	When set to `"true"`, the `PersistentVolumeClaim` is mounted only at workspace start. This prevents workspace restarts when the `PersistentVolumeClaim` is created.
`controller.devfile.io/mount-to-devworkspace-include:`	Specifies a comma-separated list of `DevWorkspace` name patterns. When set, the ConfigMap is mounted only to workspaces whose names match at least one pattern. Patterns support exact match, prefix (name), suffix (name), contains (name).
`controller.devfile.io/mount-to-devworkspace-exclude:`	Specifies a comma-separated list of `DevWorkspace` name patterns. When set, the ConfigMap is mounted to all workspaces except those whose names at least one pattern. Patterns support exact match, prefix (name), suffix (name), contains (name).

For other labels and annotations, see Mounting volumes, configmaps, and secrets.

To leverage the OpenShift Kubernetes Engine, you can create a Template object to replicate all resources defined within the template across each user namespace.

Aside from the previously mentioned ConfigMap, Secret, and PersistentVolumeClaim, Template objects can include:

LimitRange
NetworkPolicy
ResourceQuota
Role

RoleBinding

apiVersion: template.openshift.io/v1
kind: Template
metadata:
  name: che-user-namespace-configurator
  namespace: eclipse-che
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: workspaces-config
objects:
  ...
parameters:
- name: PROJECT_NAME
- name: PROJECT_ADMIN_USER

The parameters are optional and define which parameters can be used. Currently, only PROJECT_NAME and PROJECT_ADMIN_USER are supported. PROJECT_NAME is the name of the Che namespace, while PROJECT_ADMIN_USER is the Che user of the namespace.

The namespace name in objects will be replaced with the user’s namespace name during synchronization.

Example 1. Replicating Kubernetes resources to a user namespace:

apiVersion: template.openshift.io/v1
kind: Template
metadata:
  name: che-user-namespace-configurator
  namespace: eclipse-che
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: workspaces-config
objects:
- apiVersion: v1
  kind: ResourceQuota
  metadata:
    name: che-user-resource-quota
  spec:
    ...
- apiVersion: v1
  kind: LimitRange
  metadata:
    name: che-user-resource-constraint
  spec:
    ...
- apiVersion: rbac.authorization.k8s.io/v1
  kind: Role
  metadata:
    name: che-user-roles
  rules:
    ...
- apiVersion: rbac.authorization.k8s.io/v1
  kind: RoleBinding
  metadata:
    name: che-user-rolebinding
  roleRef:
    apiGroup: rbac.authorization.k8s.io
    kind: Role
    name: che-user-roles
  subjects:
  - kind: User
    apiGroup: rbac.authorization.k8s.io
    name: ${PROJECT_ADMIN_USER}
parameters:
- name: PROJECT_ADMIN_USER

Creating Template Kubernetes resources is supported only on OpenShift.

Additional resources