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.

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 the 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.
`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 match a 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 the 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 Secret is mounted only to workspaces whose names match at least one pattern.
`controller.devfile.io/mount-to-devworkspace-exclude:`	Specifies a comma-separated list of `DevWorkspace` name patterns. When set, the Secret is mounted to all workspaces except those whose names match a pattern.

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 the 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 `PersistentVolumeClaim` is mounted only to workspaces whose names match at least one pattern.
`controller.devfile.io/mount-to-devworkspace-exclude:`	Specifies a comma-separated list of `DevWorkspace` name patterns. When set, the `PersistentVolumeClaim` is mounted to all workspaces except those whose names match a pattern.

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