feat: configuring a user namespace

modules/administration-guide/nav.adoc

@@ -42,6 +42,7 @@
 *** xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]
 *** xref:configuring-workspaces-nodeselector.adoc[]
 *** xref:configuring-the-open-vsx-registry-url.adoc[]
+*** xref:configuring-a-user-namespace.adoc[]
 ** xref:caching-images-for-faster-workspace-start.adoc[]
 *** xref:defining-the-list-of-images-to-pull.adoc[]
 *** xref:defining-the-memory-parameters-for-the-image-puller.adoc[]

modules/administration-guide/pages/configuring-a-user-namespace.adoc

@@ -0,0 +1,182 @@
+:_content-type: PROCEDURE
+:description: Configuring a user namespace
+:keywords: administration guide, configuring, user, namespace
+:navtitle: Configuring a user namespace
+:page-aliases:
+
+[id="configuring-a-user-namespace"]
+= Configuring a user namespace
+
+This procedure walks you through the process of using {prod-short}
+to replicate `ConfigMaps`, `Secrets` and `PersistentVolumeClaim` from `{prod-namespace}` namespace to numerous
+user-specific namespaces. The {prod-short} automates the synchronization of important configuration
+data such as passwords, SSH keys, and certificates to user namespaces.
+
+If you make changes to a {kubernetes} resource in an {prod-namespace} namespace,
+{prod-short} will immediately replicate the changes across all users namespaces.
+In reverse, if a {kubernetes} resource is modified in a user namespace,
+{prod-short} will immediately revert the changes.
+
+.Procedure
+
+. Create the `ConfigMap` below to replicate it to every user namespace.
+To enhance the configurability, you can customize the `ConfigMap` by adding additional labels and annotations.
+See the link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Automatically mounting volumes, configmaps, and secrets]
+for other possible labels and annotations.
++
+[source,yaml,subs="+attributes,+quotes"]
+----
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: user-configmap
+  namespace: {prod-namespace}
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: workspaces-config
+data:
+  ...
+----
++
+.Mounting a `settings.xml` file to a user workspace:
+====
+[source,yaml,subs="+attributes,+quotes"]
+----
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: user-settings-xml
+  namespace: {prod-namespace}
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: workspaces-config
+  annotations:
+    controller.devfile.io/mount-as: subpath
+    controller.devfile.io/mount-path: /home/user/.m2
+data:
+  settings.xml: |
+    <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
+      <localRepository>/home/user/.m2/repository</localRepository>
+      <interactiveMode>true</interactiveMode>
+      <offline>false</offline>
+    </settings>
+----
+====
+
+. Create the `Secret` below to replicate it to every user namespace.
+To enhance the configurability, you can customize the `Secret` by adding additional labels and annotations.
+See the link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Automatically mounting volumes, configmaps, and secrets]
+for other possible labels and annotations.
++
+[source,yaml,subs="+attributes,+quotes"]
+----
+kind: Secret
+apiVersion: v1
+metadata:
+  name: user-secret
+  namespace: {prod-namespace}
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: workspaces-config
+data:
+  ...
+----
++
+.Mounting certificates to a user workspace:
+====
+[source,yaml,subs="+attributes,+quotes"]
+----
+kind: Secret
+apiVersion: v1
+metadata:
+  name: user-certificates
+  namespace: {prod-namespace}
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: workspaces-config
+  annotations:
+    controller.devfile.io/mount-as: subpath
+    controller.devfile.io/mount-path: /etc/pki/ca-trust/source/anchors
+stringData:
+  trusted-certificates.crt: |
+    ...
+----
+NOTE: Run `update-ca-trust` command on workspace startup to import certificates.
+It can be achieved manually or by adding this command to a `postStart` event in a devfile.
+See the link:https://devfile.io/docs/2.2.2/adding-event-bindings#post-start-object[Adding event bindings in a devfile].
+====
++
+.Mounting environment variables to a user workspace:
+====
+[source,yaml,subs="+attributes,+quotes"]
+----
+kind: Secret
+apiVersion: v1
+metadata:
+  name: user-env
+  namespace: {prod-namespace}
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: workspaces-config
+  annotations:
+    controller.devfile.io/mount-as: env
+stringData:
+  ENV_VAR_1: value_1
+  ENV_VAR_2: value_2
+----
+====
+
+. Create the `PersistentVolumeClaim` below to replicate it to every user namespace.
++
+To enhance the configurability, you can customize the `PersistentVolumeClaim` by adding additional labels and annotations.
+See the link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Automatically mounting volumes, configmaps, and secrets]
+for other possible labels and annotations.
++
+To modify the 'PersistentVolumeClaim', delete it and create a new one in {prod-namespace} namespace.
++
+[source,yaml,subs="+attributes,+quotes"]
+----
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: user-pvc
+  namespace: {prod-namespace}
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: workspaces-config
+spec:
+  ...
+----
++
+.Mounting a `PersistentVolumeClaim` to a user workspace:
+====
+[source,yaml,subs="+attributes,+quotes"]
+----
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: user-pvc
+  namespace: {prod-namespace}
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: workspaces-config
+    controller.devfile.io/mount-to-devworkspace: 'true'
+  annotations:
+    controller.devfile.io/mount-path: /home/user/data
+    controller.devfile.io/read-only: 'true'
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 5Gi
+  volumeMode: Filesystem
+----
+====
+
+.Additional resources
+* xref:end-user-guide:mounting-configmaps.adoc[]
+* xref:end-user-guide:mounting-secrets.adoc[]
+* xref:end-user-guide:requesting-persistent-storage-for-workspaces.adoc[]
+* link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Automatically mounting volumes, configmaps, and secrets]
+