docs: Document mount-to-devworkspace-include/exclude annotations#3089
docs: Document mount-to-devworkspace-include/exclude annotations#3089
Conversation
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 <noreply@anthropic.com>
tolusha
requested review from
a team,
deerskindoll,
gtrivedi88 and
mkuznyetsov
as code owners
|
🎊 Navigate the preview: https://69fc443dd394257722cd3c77--eclipse-che-docs-pr.netlify.app 🎊 |
|
Click here to review and test in web IDE: |
-525C86?logo=eclipse-che&labelColor=red){kind=icon}
|
@gtrivedi88 Could you review pls? |
1 similar comment
|
@gtrivedi88 Could you review pls? |
gtrivedi88
left a comment
gtrivedi88
left a comment
There was a problem hiding this comment.
Documentation Review
Files reviewed: 3 modified documentation files
Issues found: 6 (2 errors, 3 warnings, 1 suggestion)
| Category | Count |
|---|---|
| AsciiDoc syntax errors (build-breaking) | 2 |
| Information loss (removed WARNING) | 1 |
| Technical completeness gaps | 2 |
| Wording inconsistency | 1 |
The restructuring from inline YAML blocks to tables is a clear improvement in scannability. Annotation descriptions are technically accurate against the source implementation.
🤖 RHAI docs Claude Code review
| .Optional annotations | ||
| |=== | ||
| |Annotation | Description | ||
| , |
There was a problem hiding this comment.
[REQUIRED] Stray , character on this line breaks the table rendering. This should be a blank line (as used in the Secret and PVC tables in this same file) or removed entirely.
Compare with the Secret table below which correctly uses a blank line after the header row.
🤖 RHAI docs Claude review
| ==== | ||
|
|
||
| .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] |
There was a problem hiding this comment.
[REQUIRED] Leading comma before * — ,* is invalid AsciiDoc list syntax and will break the bullet rendering.
Suggested fix:
* link:https://...
Remove the comma.
🤖 RHAI docs Claude review
| | 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. |
There was a problem hiding this comment.
The removed [WARNING] block stated that applying a Secret or ConfigMap with the mount-to-devworkspace label restarts all running workspaces by default. That critical safety information is now only implied by this table row ("prevents workspace restarts"), but the default behavior — that restarts DO happen without mount-on-start — is no longer explicitly stated.
Consider adding a NOTE before the first annotations table:
NOTE: By default, creating or modifying a ConfigMap or Secret with the `controller.devfile.io/mount-to-devworkspace: 'true'` label restarts all running workspaces in the namespace. To prevent automatic restarts, set the `controller.devfile.io/mount-on-start: 'true'` annotation.🤖 RHAI docs Claude review
| | 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. |
There was a problem hiding this comment.
The description says "name patterns" but does not document what pattern syntax is supported. The source implementation (MatchesWorkspaceTarget in devworkspace-operator) supports: exact match (name), prefix (name*), suffix (*name), contains (*name*), and wildcard (*).
Consider adding a brief note, e.g.:
Patterns support exact match, prefix (
name*), suffix (*name), contains (*name*), and wildcard (*).
Also, the behavior when both include and exclude are set is not documented. Per the implementation: a resource is mounted only to workspaces that match the include pattern AND do not match the exclude pattern.
🤖 RHAI docs Claude review
| | 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. |
There was a problem hiding this comment.
[GLOBAL] Wording inconsistency between include and exclude descriptions: include says "match at least one pattern" while exclude says "match a pattern" (singular). Both accept comma-separated lists, so both should say "at least one pattern" for consistency.
This inconsistency repeats in all 3 tables (ConfigMap, Secret, PVC) and in both mounting-configmaps.adoc and mounting-secrets.adoc.
🤖 RHAI docs Claude review
| ---- | ||
| controller.devfile.io/mount-on-start: "true" | ||
| ---- | ||
| Optional: Use the annotations to configure how the ConfigMap is mounted. |
There was a problem hiding this comment.
[SUGGESTION] "Use the annotations" — the definite article "the" implies the reader already knows which annotations, but this is their first introduction. Consider: "Use annotations to configure how the ConfigMap is mounted." or "Add the following annotations to configure how the ConfigMap is mounted."
This phrasing repeats for the Secret and PVC sections.
🤖 RHAI docs Claude review
2 participants
What does this pull request change?
Documents the new
controller.devfile.io/mount-to-devworkspace-includeandcontroller.devfile.io/mount-to-devworkspace-excludeannotations introduced in devfile/devworkspace-operator#1619. These annotations allow mounting ConfigMaps, Secrets, and PVCs only to specific DevWorkspaces by name pattern.Updated articles:
What issues does this pull request fix or reference?
Specify the version of the product this pull request applies to
next
Pull Request checklist
The author and the reviewers validate the content of this pull request with the following checklist, in addition to the automated tests.
Validate language on files added or modifiedstep reports no vale warnings.