[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fix DITA errors in installing/installing_ocp/install-secured-cluster-config-options-ocp.adoc

[agantony]

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • rhacs-docs-4.11
  • rhacs-docs-4.10
  • rhacs-docs-4.9

[openshift-ci-robot]

@agantony: This pull request references ROX-33164 which is a valid jira issue.

Details

In response to this:

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • rhacs-docs-4.11
  • rhacs-docs-4.10
  • rhacs-docs-4.9

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[ocpdocs-previewbot]

🤖 Thu Aug 06 12:50:42 - Prow CI generated the docs preview:

https://117421--ocpdocs-pr.netlify.app/openshift-acs/latest/installing/installing_ocp/install-central-config-options-ocp.html
https://117421--ocpdocs-pr.netlify.app/openshift-acs/latest/installing/installing_ocp/install-secured-cluster-config-options-ocp.html

[openshift-ci]

@agantony: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[agantony]

PR Review Summary

Changes Made

• 19 files modified (2 assemblies, 2 existing modules with large content extraction, 15 new modules)
• Change categories: Large-scale inline subsection extraction into standalone modules, assembly restructuring with include comments, DITA abstract additions, header comment additions
• Module types affected: 2 ASSEMBLY files restructured, 7 new REFERENCE modules (parameter tables), 3 new CONCEPT modules (overlays), 5 new REFERENCE modules (overlay examples), 2 existing modules significantly reduced

Summary of Changes

File	Change Type	Details
installing/installing_ocp/install-secured-cluster-config-options-ocp.adoc	Assembly restructure	Added include comments; added 7 new config settings module includes (required-configuration-settings, admission-controller-settings, scanner-configuration-settings-operator, image-configuration-settings, per-node-settings, sensor-configuration-settings, general-and-miscellaneous-settings-secured-cluster at leveloffset=+2); added 8 overlay module includes (customize-installation-operator-overlays, overlays-overview, adding-an-overlay, overlay-examples-overview, 5 examples at various leveloffsets) (+48/−1)
installing/installing_ocp/install-central-config-options-ocp.adoc	Assembly restructure	Added include comments; added 8 overlay module includes (same set as secured cluster assembly) (+26/−1)
modules/secured-cluster-configuration-options-operator.adoc	Large content extraction	Extracted all 7 inline parameter table sections (Required settings, Admission controller, Scanner, Image config, Per node, Sensor, General/misc) into standalone modules; added [role="_abstract"]; retained only overview sentence (+2/−367)
modules/customize-installation-operator-overlays.adoc	Large content extraction	Added header comments; extracted all inline content (Overlays overview, Adding an overlay, 5 overlay examples) into standalone modules; retained only abstract (+5/−193)
modules/required-configuration-settings.adoc	New module (REFERENCE)	Extracted: centralEndpoint and clusterName parameters (+26 lines)
modules/admission-controller-settings.adoc	New module (REFERENCE)	Extracted: admissionControl.* parameters (enforcement, deprecated listeners, nodeSelector, tolerations, hostAliases, resources, bypass, failurePolicy, timeoutSeconds) (+59 lines)
modules/scanner-configuration-settings-operator.adoc	New module (REFERENCE)	Extracted: scanner.* and scannerV4.* parameters (analyzer settings, DB settings, scaling, PVC, monitoring, scannerComponent) (+133 lines)
modules/image-configuration-settings.adoc	New module (REFERENCE)	Extracted: imagePullSecrets.name parameter (+19 lines)
modules/per-node-settings.adoc	New module (REFERENCE)	Extracted: perNode.* parameters (collector settings, compliance resources, SFA agent, taintToleration) (+47 lines)
modules/sensor-configuration-settings.adoc	New module (REFERENCE)	Extracted: sensor.* parameters (nodeSelector, tolerations, hostAliases, resources) (+30 lines)
modules/general-and-miscellaneous-settings-secured-cluster.adoc	New module (REFERENCE)	Extracted: customize.*, egress.*, misc.*, network.*, overlays, tls.* parameters with NOTE blocks and YAML examples (+94 lines)
modules/overlays-overview.adoc	New module (CONCEPT)	Extracted overlays concept: patch mechanism, WARNING block about support limitations, overlay structure example with definition list (+46 lines)
modules/adding-an-overlay.adoc	New module (CONCEPT)	Extracted overlay addition guidance: Central/SecuredCluster customization via CLI or web console (+15 lines)
modules/overlay-examples-overview.adoc	New module (CONCEPT)	Extracted examples introduction: brief overview of overlay configurations (+11 lines)
modules/adding-eks-role-arn-annotation.adoc	New module (REFERENCE)	Extracted YAML example: EKS pod role ARN annotation (+29 lines)
modules/adding-an-environment-variable-to-a-deployment.adoc	New module (REFERENCE)	Extracted YAML example: environment variable injection (+30 lines)
modules/adding-an-ingress-to-a-network-policy.adoc	New module (REFERENCE)	Extracted YAML example: network policy ingress rule (+31 lines)
modules/changing-configmap-data.adoc	New module (REFERENCE)	Extracted YAML example: ConfigMap data modification with verbatim key (+38 lines)
modules/adding-a-container-to-a-deployment.adoc	New module (REFERENCE)	Extracted YAML example: nginx container addition (+34 lines)

Navigation Guide — Review Changes

1. Open the Secured Cluster config options page in the Netlify preview:

   • Secured Cluster configuration options
   • Verify the page loads with all restructured sections

2. Check the "Secured Cluster services configuration options" section:

   • Verify overview sentence renders with abstract
   • Verify 7 parameter table subsections at h2:
     • "Required configuration settings" — 2 parameters
     • "Admission controller settings" — ~12 parameters
     • "Scanner configuration settings for the Operator" — ~30 parameters
     • "Image configuration" — 1 parameter
     • "Per node settings" — ~8 parameters
     • "Sensor configuration" — 5 parameters
     • "General and miscellaneous settings" — ~10 parameters with NOTE blocks and YAML example

3. Check the "Customizing the installation" section:

   • Verify "Overlays" renders at h2 with WARNING block and overlay structure example
   • Verify "Adding an overlay" renders at h3
   • Verify "Overlay examples" renders at h2 with 5 example subsections at h3

4. Check the YAML examples in overlay sections:

   • Verify all 5 YAML code blocks render correctly with syntax highlighting

5. Open the Central config options page:

   • Central configuration options
   • Verify the overlay sections render identically (same 8 overlay modules)

Verification Checklists

Structural verification:

• secured-cluster-configuration-options-operator.adoc now contains only abstract (no parameter tables)
• customize-installation-operator-overlays.adoc now contains only abstract (no inline subsections)
• 7 config settings modules render at h2 under "Secured Cluster services configuration options"
• 8 overlay modules render at correct heading levels on both assembly pages
• Include comments present for all includes in both assemblies

Content verification:

• All parameter tables preserved exactly (~68 total parameters across 7 tables)
• WARNING block preserved in overlays overview
• NOTE blocks preserved in general settings (pinToNodes, nodeSelector, tolerations)
• YAML code blocks preserved (overlay structure + 5 overlay examples + pinToNodes)
• Definition list preserved in overlays overview (apiVersion, kind, name, patches.path, patches.value)

DITA compliance verification:

• All 15 new modules have proper content types, IDs with _{context}, and [role="_abstract"]
• Content types: 7 REFERENCE (config tables), 3 CONCEPT (overlays), 5 REFERENCE (overlay examples)
• [role="_abstract"] added to secured-cluster-configuration-options-operator.adoc
• Header comments added to customize-installation-operator-overlays.adoc

Quick Visual Review Guide

• Parameter tables: 7 tables with 2-column format (Parameter | Description) — verify all render correctly
• YAML code blocks: 6 YAML examples (1 overlay structure + 5 overlay examples) — verify syntax highlighting
• WARNING block: Overlays support limitation warning — verify admonition rendering
• NOTE blocks: 3 notes in general settings (pinToNodes, nodeSelector, tolerations) — verify rendering with embedded YAML
• Definition list: Overlay structure explanation — verify bold terms and descriptions
• Shared modules: Overlay sections appear on both Central and Secured cluster config pages — verify identical rendering