Skip to content

docs: Document mount-to-devworkspace-include/exclude annotations #3089

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

Open
tolusha wants to merge 1 commit into
base: main
Choose a base branch
from
+76 −67
Open

docs: Document mount-to-devworkspace-include/exclude annotations #3089

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
123 changes: 56 additions & 67 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 @@ -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.
Expand All @@ -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:
+
Expand All @@ -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.
Expand All @@ -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}.
+
Expand All @@ -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:
Expand Down
10 changes: 10 additions & 0 deletions modules/end-user-guide/pages/mounting-configmaps.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -83,3 +90,6 @@ data:

When you start a workspace, the `__<env_var_1>__` and `__<env_var_2>__` 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]
10 changes: 10 additions & 0 deletions modules/end-user-guide/pages/mounting-secrets.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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]
Loading