From d47859f02f3b1b436c6acb9f03db9bdf2ed19a8c Mon Sep 17 00:00:00 2001 From: Anatolii Bazko Date: Thu, 7 May 2026 09:44:22 +0200 Subject: [PATCH] docs: Document mount-to-devworkspace-include/exclude annotations Add documentation for the new `controller.devfile.io/mount-to-devworkspace-include` and `controller.devfile.io/mount-to-devworkspace-exclude` annotations that allow mounting ConfigMaps, Secrets, and PVCs only to specific DevWorkspaces by name pattern. Co-Authored-By: Claude Opus 4.6 --- .../pages/configuring-a-user-namespace.adoc | 123 ++++++++---------- .../pages/mounting-configmaps.adoc | 10 ++ .../pages/mounting-secrets.adoc | 10 ++ 3 files changed, 76 insertions(+), 67 deletions(-) diff --git a/modules/administration-guide/pages/configuring-a-user-namespace.adoc b/modules/administration-guide/pages/configuring-a-user-namespace.adoc index d39dcb1b87..a2a606f7e7 100644 --- a/modules/administration-guide/pages/configuring-a-user-namespace.adoc +++ b/modules/administration-guide/pages/configuring-a-user-namespace.adoc @@ -18,13 +18,6 @@ If you make changes to a {kubernetes} resource in an {prod-namespace} namespace, In reverse, if a {kubernetes} resource is modified in a user namespace, {prod-short} will immediately revert the changes. -[WARNING] -==== -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. @@ -44,24 +37,26 @@ data: ... ---- ==== -To enhance the configurability, you can customize the `ConfigMap` by adding additional labels and annotations. -+ -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"] ----- -che.eclipse.org/sync-retain-on-delete: "true" ----- -+ -Add the following annotation to prevent workspace restarts when the ConfigMap is created: -+ -[source,yaml,subs="+attributes,+quotes"] ----- -controller.devfile.io/mount-on-start: "true" ----- +Optional: Use the annotations to configure how the ConfigMap is mounted. ++ +.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 {prod-namespace} 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. +|=== + -With this annotation, the ConfigMap is mounted only at workspace start. +For other labels and annotations, see 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 example, to mount a default SSH configuration into every workspace, you must create a ConfigMap: + @@ -85,8 +80,6 @@ data: ==== + 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 link:https://man.openbsd.org/ssh_config#Include[Include] definition. -+ -For other labels and annotations, see link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Mounting volumes, configmaps, and secrets]. . Create the `Secret` below to create and mount it into every workspace. @@ -106,28 +99,26 @@ stringData: ... ---- ==== -To enhance the configurability, you can customize the `Secret` by adding additional labels and annotations. -+ -Add the annotation below if you want the Secret to be retained in a user {namespace} -after being deleted from {prod-namespace} namespace: +Optional: Use the annotations to configure how the Secret is mounted. + -[source,yaml,subs="+attributes,+quotes"] ----- -che.eclipse.org/sync-retain-on-delete: "true" ----- -+ -Add the following annotation to prevent workspace restarts when the Secret is created: -+ -[source,yaml,subs="+attributes,+quotes"] ----- -controller.devfile.io/mount-on-start: "true" ----- -+ -With this annotation, the Secret is mounted only at workspace start. -+ -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. +.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 {prod-namespace} 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 link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Mounting volumes, configmaps, and secrets]. . Create the `PersistentVolumeClaim` below to create it to every user {orch-namespace}. + @@ -145,30 +136,28 @@ spec: ... ---- + -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"] ----- -che.eclipse.org/sync-retain-on-delete: "false" ----- -+ -Add the following annotation to prevent workspace restarts when the `PersistentVolumeClaim` is created: -+ -[source,yaml,subs="+attributes,+quotes"] ----- -controller.devfile.io/mount-on-start: "true" ----- +Optional: Use the annotations to configure how the `PersistentVolumeClaim` is mounted. + -With this annotation, the `PersistentVolumeClaim` is mounted only at workspace start. -+ -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. +NOTE: The `PersistentVolumeClaim` is not deleted in a user {namespace} by default, if the one from {prod-namespace} is deleted. + +.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 {prod-namespace} 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 link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[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 {orch-namespace}. + Aside from the previously mentioned `ConfigMap`, `Secret`, and `PersistentVolumeClaim`, `Template` objects can include: diff --git a/modules/end-user-guide/pages/mounting-configmaps.adoc b/modules/end-user-guide/pages/mounting-configmaps.adoc index 8db698a81c..e71e511ab7 100644 --- a/modules/end-user-guide/pages/mounting-configmaps.adoc +++ b/modules/end-user-guide/pages/mounting-configmaps.adoc @@ -61,6 +61,13 @@ Defaults to `file`. | When set to `true`, the ConfigMap is mounted only when a workspace starts, not while it is already running. 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. + |=== .Mounting a ConfigMap as environment variables @@ -83,3 +90,6 @@ data: When you start a workspace, the `____` and `____` environment variables will be available in the `{devworkspace}` containers. ==== + +.Additional resources +,* 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] diff --git a/modules/end-user-guide/pages/mounting-secrets.adoc b/modules/end-user-guide/pages/mounting-secrets.adoc index ac2c9f324b..4057d35bd2 100644 --- a/modules/end-user-guide/pages/mounting-secrets.adoc +++ b/modules/end-user-guide/pages/mounting-secrets.adoc @@ -61,6 +61,13 @@ Defaults to `file`. | When set to `true`, the Secret is mounted only when a workspace starts, not while it is already running. 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. + |=== .Mounting a Secret as a file @@ -91,3 +98,6 @@ $ mvn --settings /home/user/.m2/settings.xml clean install ---- ==== + +.Additional resources +* 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]