Skip to content

chore: Update configuring-a-user-namespace.adoc #2979

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tolusha merged 4 commits into from
Oct 15, 2025
Merged

chore: Update configuring-a-user-namespace.adoc #2979

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
30e938d
chore: Update configuring-a-user-namespace.adoc
tolusha Oct 13, 2025
d666ec0
Update modules/administration-guide/pages/configuring-a-user-namespac…
tolusha Oct 15, 2025
5e62fba
Update modules/administration-guide/pages/configuring-a-user-namespac…
tolusha Oct 15, 2025
a1dd97f
Update modules/administration-guide/pages/configuring-a-user-namespac…
tolusha Oct 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 46 additions & 115 deletions modules/administration-guide/pages/configuring-a-user-namespace.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,30 +7,21 @@
[id="configuring-a-user-namespace"]
= Configuring a user namespace

This procedure walks you through the process of using {prod-short}
to replicate `ConfigMaps`, `Secrets`, `PersistentVolumeClaim` and other {kubernetes} objects from `{prod-namespace}` namespace to numerous user-specific namespaces. The {prod-short} automates the synchronization of important configuration data such as shared credentials, configuration files, and certificates to user namespaces.
Learn how to use {prod-short}
to synchronize `ConfigMaps`, `Secrets`, `PersistentVolumeClaim` and other {kubernetes} objects
from `{prod-namespace}` namespace to numerous user-specific namespaces.
The {prod-short} 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 {prod-namespace} namespace,
{prod-short} will immediately replicate the changes across all users namespaces.
{prod-short} will immediately synchronize 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 into every user {orch-namespace}.
To enhance the configurability, you can customize the `ConfigMap` by adding additional labels and annotations.
By default, the ConfigMap is automatically mounted into user workspaces.
If you do not want the ConfigMap to be mounted, explicitly add the following labels to override the behavior:
. Create the `ConfigMap` below to create and mount it into every workspace.
+
[source,yaml,subs="+attributes,+quotes"]
----
controller.devfile.io/watch-configmap: "false"
controller.devfile.io/mount-to-devworkspace: "false"
----
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.
+
.Replicate a ConfigMap into every user {orch-namespace}:
====
[source,yaml,subs="+attributes,+quotes"]
----
Expand All @@ -42,52 +33,34 @@ metadata:
labels:
app.kubernetes.io/part-of: che.eclipse.org
app.kubernetes.io/component: workspaces-config
controller.devfile.io/watch-configmap: "false"
controller.devfile.io/mount-to-devworkspace: "false"
data:
...
----
====
To enhance the configurability, you can customize the `ConfigMap` by adding additional labels and annotations.
+
Add the following labels if you do not want the ConfigMap to be mounted automatically:
+
.Replicate a ConfigMap into every user {orch-namespace} and automatically mount a `settings.xml` file into every user container by path `/home/user/.m2`:
====
[source,yaml,subs="+attributes,+quotes"]
----
kind: ConfigMap
apiVersion: v1
metadata:
name: {prod-id-short}-user-configmap
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>
controller.devfile.io/watch-configmap: "false"
controller.devfile.io/mount-to-devworkspace: "false"
----
====

. Create the `Secret` below to replicate into every user {orch-namespace}.
To enhance the configurability, you can customize the `Secret` by adding additional labels and annotations.
By default, the Secret is automatically mounted into user workspaces.
If you do not want the Secret to be mounted, explicitly add the following labels to override the behavior:
+
Add the annotation below if you want the ConfigMap to be retained in a user {namespace}
after being deleted from {prod-namespace} namespace:
+
[source,yaml,subs="+attributes,+quotes"]
----
controller.devfile.io/watch-secret: "false"
controller.devfile.io/mount-to-devworkspace: "false"
che.eclipse.org/sync-retain-on-delete: "true"
----
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]
+
See the link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[mounting volumes, configmaps, and secrets]
for other possible labels and annotations.


. Create the `Secret` below to create and mount it into every workspace.
+
.Replicate a Secret into every user {orch-namespace}:
====
[source,yaml,subs="+attributes,+quotes"]
----
Expand All @@ -99,64 +72,33 @@ metadata:
labels:
app.kubernetes.io/part-of: che.eclipse.org
app.kubernetes.io/component: workspaces-config
controller.devfile.io/watch-secret: "false"
controller.devfile.io/mount-to-devworkspace: "false"
annotations:
controller.devfile.io/mount-as: env
stringData:
...
...
----
====
To enhance the configurability, you can customize the `Secret` by adding additional labels and annotations.
+
Add the labels if you do not want the Secret to be mounted automatically:
+
.Replicate a Secret into every user {orch-namespace} and automatically mount a `secret.data` file into every user container by path `/home/user/secrets`:
====
[source,yaml,subs="+attributes,+quotes"]
----
kind: Secret
apiVersion: v1
metadata:
name: {prod-id-short}-user-secret
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/secrets
stringData:
secret.data: |
...
controller.devfile.io/watch-secret: "false"
controller.devfile.io/mount-to-devworkspace: "false"
----
====
+
.Replicate a Secret into every user {orch-namespace} and automatically mount as environment variables into every user container:
====
Add the annotation below if you want the Secret to be retained in a user {namespace}
after being deleted from {prod-namespace} namespace:
+
[source,yaml,subs="+attributes,+quotes"]
----
kind: Secret
apiVersion: v1
metadata:
name: {prod-id-short}-user-secret
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
che.eclipse.org/sync-retain-on-delete: "true"
----
====


. Create the `PersistentVolumeClaim` below to replicate it to every user {orch-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]
See the link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[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.


. Create the `PersistentVolumeClaim` below to create it to every user {orch-namespace}.
+
[source,yaml,subs="+attributes,+quotes"]
----
Expand All @@ -172,31 +114,20 @@ spec:
...
----
+
.Mounting a `PersistentVolumeClaim` to a user workspace:
====
To enhance the configurability, you can customize the `PersistentVolumeClaim` by adding additional labels and annotations.
+
The `PersistentVolumeClaim` is not deleted in a user {namespace} by default, if the one from {prod-namespace} is deleted.
Add the annotation below if you want the `PersistentVolumeClaim` to be deleted in a user {namespace} as well:

+
[source,yaml,subs="+attributes,+quotes"]
----
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: {prod-id-short}-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
che.eclipse.org/sync-retain-on-delete: "false"
----
====
+
See the link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[mounting volumes, configmaps, and secrets]
for other possible labels and annotations.
+

. To leverage the OpenShift Kubernetes Engine, you can create a `Template` object to replicate all resources defined within the template across each user {orch-namespace}.
+
Expand Down