procedures: Update backup registry auth secret documentation#3090
procedures: Update backup registry auth secret documentation#3090tolusha wants to merge 1 commit into
Conversation
Update the article to reflect the new behavior introduced by devfile/devworkspace-operator#1618: - Add the new copyOperatorAuthSecret configuration field - Clarify that authSecret can be any name in the operator namespace - Document that the secret in workspace namespace always uses the canonical name devworkspace-backup-registry-auth - Split documentation into two approaches: automatic copying vs manual creation - Update the IMPORTANT note about non-overwriting behavior Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
tolusha
requested review from
a team,
deerskindoll,
gtrivedi88 and
mkuznyetsov
as code owners
|
🎊 Navigate the preview: https://6a0137fc2d99e06e2cc1591d--eclipse-che-docs-pr.netlify.app 🎊 |
|
Click here to review and test in web IDE: |
-525C86?logo=eclipse-che&labelColor=red){kind=icon}
gtrivedi88
left a comment
gtrivedi88
left a comment
There was a problem hiding this comment.
Documentation Review
Files reviewed: 1 modified procedure file
Issues found: 7 (2 errors, 4 warnings, 1 suggestion)
| Category | Count |
|---|---|
| Modular docs structure | 2 |
| IBM Style Guide (tense, modal verbs) | 2 |
| Red Hat SSG (user-replaced values) | 2 |
| JTBD (abstract) | 1 |
🤖 RHAI docs Claude Code review
| RBAC policy, the token can be provided via a secret in the Operator {namespace} or in each {devworkspace} {namespace}. | ||
| Having the secret in the {devworkspace} {namespace} allows for using different registry accounts per {namespace} with more | ||
| granular access control. | ||
| To use a regular OCI-compatible registry for backups, you need to provide registry credentials. You can configure the {devworkspace} operator to automatically copy a registry authentication secret from the operator {namespace} to {devworkspace} {namespaces}, or you can manually create secrets in each {devworkspace} {namespace}. Having separate secrets in each {devworkspace} {namespace} allows for using different registry accounts per {namespace} with more granular access control. |
There was a problem hiding this comment.
[JTBD] Two issues with this intro paragraph:
-
Missing
[role="_abstract"]— every module must have a short description marked with[role="_abstract"]. Add it before this paragraph. -
"you need to" → "you must" — IBM Style Guide: use "must" for requirements, not "need to".
-
Weak WHY — the abstract explains WHAT (provide credentials) but the core benefit (ensuring workspace data is backed up and recoverable) is absent. JTBD-aligned abstract should explain the user's job.
Suggested fix:
[role="_abstract"]
To use a regular OCI-compatible registry for backups, you must provide registry credentials. You can configure the {devworkspace} operator to automatically copy a registry authentication secret from the operator {namespace} to {devworkspace} {namespaces}, or you can manually create secrets in each {devworkspace} {namespace} for more granular access control.🤖 RHAI docs Claude review
| The `authSecret` must be named `devworkspace-backup-registry-auth`. It must reference a {kubernetes} Secret of type `kubernetes.io/dockerconfigjson` that contains credentials to access the registry. | ||
| The secret should be created in the installation {namespace} for the {devworkspace} operator. | ||
| == Configuring automatic secret copying | ||
|
|
There was a problem hiding this comment.
[REQUIRED] Custom == subheading == Configuring automatic secret copying is not allowed in a procedure module. Procedure modules only permit .Prerequisites, .Procedure, .Verification, .Troubleshooting, .Next steps, and .Additional resources.
Suggested fix — restructure both approaches as alternatives within the .Procedure section. Remove both == subheadings and present the two paths as numbered steps:
. Configure how the operator provides registry credentials to {devworkspace} {namespaces}:
+
* *Option A: Automatic secret copying* — Set `copyOperatorAuthSecret: true` in the {devworkspace} operator configuration. The operator copies the registry authentication secret from the operator {namespace} to each {devworkspace} {namespace}.
+
Create the secret in the operator {namespace}:
+
...existing code blocks...
+
* *Option B: Manual secret creation* — Leave `copyOperatorAuthSecret` at the default (`false`) and manually create a secret named `devworkspace-backup-registry-auth` in each {devworkspace} {namespace}.
+
...existing code blocks...(Modular docs: procedure modules — no custom subheadings, only allowed sections.)
🤖 RHAI docs Claude review
| {orch-cli} create secret docker-registry devworkspace-backup-registry-auth --from-file=config.json | ||
| {orch-cli} create secret docker-registry my-registry-auth \ | ||
| --namespace $OPERATOR_INSTALL_NAMESPACE \ | ||
| --from-file=config.json |
There was a problem hiding this comment.
[REQUIRED] $OPERATOR_INSTALL_NAMESPACE is not formatted as a user-replaced value. Per Red Hat SSG, user-replaced values must use italic with angle brackets: __<operator_namespace>__.
This issue also occurs on line ~57 in the label command.
Suggested fix:
{orch-cli} create secret docker-registry my-registry-auth \
--namespace __<operator_namespace>__ \
--from-file=config.json
(Red Hat SSG Formatting: user-replaced values use __<description>__ syntax.)
🤖 RHAI docs Claude review
| The {devworkspace} Operator copies the `devworkspace-backup-registry-auth` secret to each {devworkspace} {namespace} so that backups from user workspaces can be pushed to the registry. If you do not want that secret copied automatically, create a `devworkspace-backup-registry-auth` secret with user-specific credentials in each {devworkspace} {namespace} instead. | ||
| ==== | ||
| The operator will copy this secret to each {devworkspace} {namespace} with the canonical name `devworkspace-backup-registry-auth`. | ||
|
|
There was a problem hiding this comment.
Future tense "will copy" — use present tense per IBM Style Guide.
Suggested fix — replace:
The operator will copy this secret to each {devworkspace} {namespace} with the canonical name
devworkspace-backup-registry-auth.
With:
The operator copies this secret to each {devworkspace} {namespace} with the canonical name
devworkspace-backup-registry-auth.
(IBM Style Guide: use present tense for describing product behavior.)
🤖 RHAI docs Claude review
| ---- | ||
| {orch-cli} create secret docker-registry devworkspace-backup-registry-auth \ | ||
| --namespace <workspace-namespace> \ | ||
| --from-file=config.json |
There was a problem hiding this comment.
<workspace-namespace> is not formatted as a user-replaced value.
Suggested fix — replace:
{orch-cli} create secret docker-registry devworkspace-backup-registry-auth \\
--namespace <workspace-namespace> \\
--from-file=config.json
With:
{orch-cli} create secret docker-registry devworkspace-backup-registry-auth \\
--namespace __<workspace_namespace>__ \\
--from-file=config.json
(Red Hat SSG Formatting: user-replaced values use __<description>__ syntax with double underscores for italic rendering.)
🤖 RHAI docs Claude review
| <1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:devworkspace-operator.adoc[{devworkspace} operator overview]. | ||
| <2> Set to `true` to enable automatic copying of the registry authentication secret from the operator {namespace} to {devworkspace} {namespaces}. The default value is `false`. | ||
| <3> The name of the secret in the operator {namespace} that contains registry credentials. This secret will be copied to {devworkspace} {namespaces} with the canonical name `devworkspace-backup-registry-auth`. | ||
|
|
There was a problem hiding this comment.
[REQUIRED] Callouts <2> and <3> use future tense. Use present tense per IBM Style Guide.
Suggested fix — replace:
<2> Set to `true` to enable automatic copying of the registry authentication secret from the operator {namespace} to {devworkspace} {namespaces}. The default value is `false`.
<3> The name of the secret in the operator {namespace} that contains registry credentials. This secret will be copied to {devworkspace} {namespaces} with the canonical name `devworkspace-backup-registry-auth`.With:
<2> When set to `true`, the operator copies the registry authentication secret from the operator {namespace} to each {devworkspace} {namespace}. The default is `false`.
<3> The name of the secret in the operator {namespace} that contains registry credentials. The operator copies this secret to each {devworkspace} {namespace} with the canonical name `devworkspace-backup-registry-auth`.(IBM Style Guide: use present tense for describing product behavior.)
🤖 RHAI docs Claude review
There was a problem hiding this comment.
Suggested fix for callouts <2> and <3>:
Replace the current callouts:
<2> Set to `true` to enable automatic copying of the registry authentication secret from the operator {namespace} to {devworkspace} {namespaces}. The default value is `false`.
<3> The name of the secret in the operator {namespace} that contains registry credentials. This secret will be copied to {devworkspace} {namespaces} with the canonical name `devworkspace-backup-registry-auth`.With:
<2> When set to `true`, the operator copies the registry authentication secret from the operator {namespace} to each {devworkspace} {namespace}. The default is `false`.
<3> The name of the secret in the operator {namespace} that contains registry credentials. The operator copies this secret to each {devworkspace} {namespace} with the canonical name `devworkspace-backup-registry-auth`.🤖 RHAI docs Claude review
| kubectl label secret devworkspace-backup-registry-auth controller.devfile.io/watch-secret=true | ||
| {orch-cli} label secret my-registry-auth \ | ||
| --namespace $OPERATOR_INSTALL_NAMESPACE \ | ||
| controller.devfile.io/watch-secret=true |
There was a problem hiding this comment.
[REQUIRED] $OPERATOR_INSTALL_NAMESPACE is not formatted as a user-replaced value.
Suggested fix — replace:
{orch-cli} label secret my-registry-auth \
--namespace $OPERATOR_INSTALL_NAMESPACE \
controller.devfile.io/watch-secret=true
With:
{orch-cli} label secret my-registry-auth \
--namespace __<operator_namespace>__ \
controller.devfile.io/watch-secret=true
(Red Hat SSG Formatting: user-replaced values use __<description>__ syntax.)
🤖 RHAI docs Claude review
| The operator will copy this secret to each {devworkspace} {namespace} with the canonical name `devworkspace-backup-registry-auth`. | ||
|
|
||
| == Manually creating secrets in workspace namespaces | ||
|
|
There was a problem hiding this comment.
[REQUIRED] Custom == subheading == Manually creating secrets in workspace namespaces is not allowed in a procedure module.
Suggested fix — remove this == heading and present this as Option B within the .Procedure section (see comment on line 37 for the full restructuring approach).
(Modular docs: procedure modules — no custom subheadings, only allowed sections.)
🤖 RHAI docs Claude review
| == Manually creating secrets in workspace namespaces | ||
|
|
||
| If `copyOperatorAuthSecret` is set to `false` (the default), the operator will not automatically copy secrets. Instead, you must manually create a secret named `devworkspace-backup-registry-auth` in each {devworkspace} {namespace}. | ||
|
|
There was a problem hiding this comment.
Future tense "will not" — use present tense per IBM Style Guide.
Suggested fix — replace:
If
copyOperatorAuthSecretis set tofalse(the default), the operator will not automatically copy secrets. Instead, you must manually create a secret nameddevworkspace-backup-registry-authin each {devworkspace} {namespace}.
With:
If
copyOperatorAuthSecretis set tofalse(the default), the operator does not automatically copy secrets. Instead, you must manually create a secret nameddevworkspace-backup-registry-authin each {devworkspace} {namespace}.
(IBM Style Guide: use present tense for describing product behavior.)
🤖 RHAI docs Claude review
| This approach allows you to use different registry credentials for different {devworkspace} {namespaces}. | ||
|
|
||
| IMPORTANT: If a secret named `devworkspace-backup-registry-auth` already exists in a {devworkspace} {namespace}, the operator will never overwrite it, even when `copyOperatorAuthSecret` is set to `true`. This ensures that user-provided secrets are always respected. | ||
|
|
There was a problem hiding this comment.
Future tense "will never overwrite" — use present tense per IBM Style Guide.
Suggested fix — replace:
IMPORTANT: If a secret named
devworkspace-backup-registry-authalready exists in a {devworkspace} {namespace}, the operator will never overwrite it, even whencopyOperatorAuthSecretis set totrue. This ensures that user-provided secrets are always respected.
With:
IMPORTANT: If a secret named
devworkspace-backup-registry-authalready exists in a {devworkspace} {namespace}, the operator does not overwrite it, even whencopyOperatorAuthSecretis set totrue. This ensures that user-provided secrets are always respected.
(IBM Style Guide: use present tense for describing product behavior.)
🤖 RHAI docs Claude review
2 participants
What does this pull request change?
Updates the "Configuring backup with a regular OCI-compatible registry" article to reflect the new behavior introduced by devfile/devworkspace-operator#1618.
Key changes:
copyOperatorAuthSecretconfiguration field (defaults tofalse)authSecretcan be any name in the operator namespacedevworkspace-backup-registry-authcopyOperatorAuthSecret: true)copyOperatorAuthSecret: false)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.