Skip to content

procedures: Update backup registry auth secret documentation #3090

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

Closed
tolusha wants to merge 1 commit into from
Closed

procedures: Update backup registry auth secret documentation #3090

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
51 changes: 36 additions & 15 deletions modules/administration-guide/pages/devworkspace-backup-regular-oci-registry.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,7 @@
[id="devworkspace-backup-regular-oci-registry"]
= Configuring backup with a regular OCI-compatible registry

To use a regular OCI-compatible registry for backups, you need to provide registry credentials. Depending on your
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.
Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[JTBD] Two issues with this intro paragraph:

  1. Missing [role="_abstract"] — every module must have a short description marked with [role="_abstract"]. Add it before this paragraph.

  2. "you need to" → "you must" — IBM Style Guide: use "must" for requirements, not "need to".

  3. 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


[source,yaml,subs="+attributes,+quotes"]
----
Expand All @@ -25,34 +22,58 @@ config:
workspace:
backupCronJob:
enable: true
copyOperatorAuthSecret: true <2>
registry:
authSecret: devworkspace-backup-registry-auth
authSecret: my-registry-auth <3>
path: quay.io/my-company-org
schedule: '0 */4 * * *'
imagePullPolicy: Always
----
<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`.

Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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

Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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

To create one, you can use the following command:
When `copyOperatorAuthSecret` is set to `true`, the operator automatically copies the registry authentication secret from the operator {namespace} to each {devworkspace} {namespace}.

The `authSecret` field specifies the name of the secret in the operator {namespace}. This secret must be of type `kubernetes.io/dockerconfigjson` and contain credentials to access the registry.

To create the secret in the operator {namespace}, use the following command:

[source,shell,subs="+attributes,+quotes"]
----
{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
Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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 secret must contain a label `controller.devfile.io/watch-secret=true` to be recognized by the {devworkspace} Operator.
The secret must contain a label `controller.devfile.io/watch-secret=true` to be recognized by the {devworkspace} Operator:

[source,shell,subs="+attributes,+quotes"]
----
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
Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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

----

[WARNING]
====
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`.

Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

== Manually creating secrets in workspace namespaces

Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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

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}.

Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Future tense "will not" — use present tense per IBM Style Guide.

Suggested fix — replace:

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}.

With:

If copyOperatorAuthSecret is set to false (the default), the operator does not automatically copy secrets. Instead, you must manually create a secret named devworkspace-backup-registry-auth in each {devworkspace} {namespace}.

(IBM Style Guide: use present tense for describing product behavior.)

🤖 RHAI docs Claude review

To create the secret in a {devworkspace} {namespace}, use the following command:

[source,shell,subs="+attributes,+quotes"]
----
{orch-cli} create secret docker-registry devworkspace-backup-registry-auth \
--namespace <workspace-namespace> \
--from-file=config.json
Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

<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

----

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.

Copy link
Copy Markdown
Contributor

@gtrivedi88 gtrivedi88 May 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Future tense "will never overwrite" — use present tense per IBM Style Guide.

Suggested fix — replace:

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.

With:

IMPORTANT: If a secret named devworkspace-backup-registry-auth already exists in a {devworkspace} {namespace}, the operator does not overwrite it, even when copyOperatorAuthSecret is set to true. This ensures that user-provided secrets are always respected.

(IBM Style Guide: use present tense for describing product behavior.)

🤖 RHAI docs Claude review

include::partial$snip_defining-dwo-namespace-for-backups.adoc[]
Loading