CNV-62649: Update CNV modules to pass DITA validation #102522

jhradilek · 2025-11-13T23:14:48Z

Version(s): 4.21

Link to docs preview:

QE review:

QE has approved this change.

Additional information:
The PR replaces #96074. The PR may apply to older version, but I am not sure I am mentally prepared for manual cherry-picks all the way down to 4.14. It fixes all validation issues in modules/virt-*.adoc with the following notable exceptions:

It does not address CalloutList warnings as these should be addressed consistently with the rest of the docs.
It does not resolve NestedSection and DiscreteTitle warnings that require modules to be split into multiple files.
It does not resolve ShortDescription in a select few files that do not provide enough contents for me to write it.

Note that I slightly edited short descriptions that would not fit in the 300 character limit.

openshift-ci-robot · 2025-11-13T23:14:53Z

@jhradilek: This pull request references CNV-62649 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the epic to target the "4.21.0" version, but no target version was set.

In response to this:

Version(s): 4.21

Issue: CNV-62649

Link to docs preview:

QE review:

QE has approved this change.

Additional information:
The PR replaces #96074. The PR may apply to older version, but I am not sure I am mentally prepared for manual cherry-picks all the way down to 4.14. It fixes all validation issues in modules/virt-*.adoc with the following notable exceptions:

It does not address CalloutList warnings as these should be addressed consistently with the rest of the docs.

It does not resolve NestedSection and DiscreteTitle warnings that require modules to be split into multiple files.

It does not resolve ShortDescription in a select few files that do not provide enough contents for me to write it.

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.

jhradilek · 2025-11-13T23:15:10Z

/label cnv

openshift-ci-robot · 2025-11-13T23:16:36Z

@jhradilek: This pull request references CNV-62649 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the epic to target the "4.21.0" version, but no target version was set.

In response to this:

Version(s): 4.21

Issue: CNV-62649

Link to docs preview:

QE review:

QE has approved this change.

Additional information:
The PR replaces #96074. The PR may apply to older version, but I am not sure I am mentally prepared for manual cherry-picks all the way down to 4.14. It fixes all validation issues in modules/virt-*.adoc with the following notable exceptions:

It does not address CalloutList warnings as these should be addressed consistently with the rest of the docs.

It does not resolve NestedSection and DiscreteTitle warnings that require modules to be split into multiple files.

It does not resolve ShortDescription in a select few files that do not provide enough contents for me to write it.

Note that I slightly edited short descriptions that would not fit in the 300 character limit.

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.

jhradilek · 2025-11-13T23:27:33Z

modules/virt-creating-new-vm-from-cloned-pvc-using-datavolumetemplate.adoc

+Reference a
 `dataVolumeTemplate` in the virtual machine manifest and the `source` PVC is cloned to
 a data volume, which is then automatically used for the creation of the virtual
 machine.


Reference a dataVolumeTemplate in the virtual machine manifest and the source PVC is cloned to
a data volume, which is then automatically used for the creation of the virtual
machine.

This is not in the scope of my PR and I haven't changed this sentence, but it sounds off to me.

Yeah, I think it should be "If you reference a dataVolumeTemplate in the virtual machine manifest, the source PVC..." However, I'm not seeing this module in use, so I'm flagging it (in my own notes) as a candidate for removal.

ocpdocs-previewbot · 2025-11-13T23:27:46Z

🤖 Fri Nov 14 18:57:28 - Prow CI generated the docs preview:
https://102522--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

ocpdocs-vale-bot · 2025-11-13T23:52:13Z

modules/virt-about-tekton-tasks-operator.adoc


-The Tekton Tasks Operator, `tekton-tasks-operator`, deploys example pipelines showing the usage of OpenShift Pipelines for virtual machines (VMs). This operator also deploys additional OpenShift Pipeline tasks that allow users to create VMs from templates, copy and modify templates, and create data volumes.
+[role="_abstract"]
+The Tekton Tasks Operator, `tekton-tasks-operator`, deploys example pipelines showing the usage of OpenShift Pipelines for virtual machines (VMs). It also deploys additional OpenShift Pipeline tasks that allow users to create VMs from templates, copy and modify templates, and create data volumes.


🤖 [error] OpenShiftAsciiDoc.SuggestAttribute: Use the AsciiDoc attribute '{pipelines-shortname}' rather than the plain text product term 'OpenShift Pipelines', unless your use case is an exception.

ocpdocs-vale-bot · 2025-11-13T23:53:11Z

modules/virt-common-error-messages.adoc

+The following error messages might appear in {VirtProductName} logs.

-`ErrImagePull` or `ImagePullBackOff`:: Indicates an incorrect deployment configuration or problems with the images that are referenced.
+`ErrImagePull` or `ImagePullBackOff`:: Indicates an incorrect deployment configuration or problems with the images that are referenced.


🤖 [error] Vale.Avoid: Avoid using 'deployment configuration'.

ocpdocs-vale-bot · 2025-11-13T23:53:12Z

modules/virt-common-error-messages.adoc

+The following error messages might appear in {VirtProductName} logs.

-`ErrImagePull` or `ImagePullBackOff`:: Indicates an incorrect deployment configuration or problems with the images that are referenced.
+`ErrImagePull` or `ImagePullBackOff`:: Indicates an incorrect deployment configuration or problems with the images that are referenced.


🤖 [error] RedHat.TermsErrors: Use 'deployment' rather than 'deployment configuration'. For more information, see RedHat.TermsErrors.

ocpdocs-vale-bot · 2025-11-13T23:56:11Z

modules/virt-hot-plugging-bridge-network-interface-cli.adoc

🤖 [error] AsciiDocDITA.CalloutList: Callouts are not supported in DITA.

ocpdocs-vale-bot · 2025-11-13T23:56:37Z

modules/virt-maintaining-bare-metal-nodes.adoc

@@ -6,7 +6,10 @@
 [id="virt-maintaining-bare-metal-nodes_{context}"]
 = Maintaining bare metal nodes

-When you deploy {product-title} on bare metal infrastructure, there are additional considerations that must be taken into account compared to deploying on cloud infrastructure. Unlike in cloud environments where the cluster nodes are considered ephemeral, re-provisioning a bare metal node requires significantly more time and effort for maintenance tasks.
+[role="_abstract"]
+When you deploy {product-title} on bare metal infrastructure, there are additional considerations that must be taken into account compared to deploying on cloud infrastructure.


🤖 [error] RedHat.TermsErrors: Use 'bare-metal infrastructure' rather than 'bare metal infrastructure'. For more information, see RedHat.TermsErrors.

ocpdocs-vale-bot · 2025-11-13T23:56:37Z

modules/virt-maintaining-bare-metal-nodes.adoc

+[role="_abstract"]
+When you deploy {product-title} on bare metal infrastructure, there are additional considerations that must be taken into account compared to deploying on cloud infrastructure.
+
+Unlike in cloud environments where the cluster nodes are considered ephemeral, re-provisioning a bare metal node requires significantly more time and effort for maintenance tasks.


🤖 [error] RedHat.TermsErrors: Use 'bare-metal node' rather than 'bare metal node'. For more information, see RedHat.TermsErrors.

ousleyp

LGTM. My comments don't require resolution... they are just me externally processing. 😹 Thank you so much for making these fixes!

ousleyp · 2025-11-14T17:06:36Z

modules/virt-creating-new-vm-from-cloned-pvc-using-datavolumetemplate.adoc

+Reference a
 `dataVolumeTemplate` in the virtual machine manifest and the `source` PVC is cloned to
 a data volume, which is then automatically used for the creation of the virtual
 machine.


Yeah, I think it should be "If you reference a dataVolumeTemplate in the virtual machine manifest, the source PVC..." However, I'm not seeing this module in use, so I'm flagging it (in my own notes) as a candidate for removal.

ousleyp · 2025-11-14T17:27:50Z

modules/virt-dv-annotations.adoc

+
 If you want the importer pod to use both the default network from the cluster and the secondary multus network, use the `k8s.v1.cni.cncf.io/networks: <network_name>` annotation.

 .Multus network annotation example


Is this block title legal?

ousleyp · 2025-11-14T17:40:41Z

modules/virt-example-vm-node-placement-node-affinity.adoc


 If possible, the scheduler avoids nodes that have the label `example-node-label-key = example-node-label-value`. However, if all candidate nodes have this label, the scheduler ignores this constraint.

 .Example VM manifest


I'm guessing this is an example of In DITA 1.3, only the <example>, <fig>, and <table> elements can have a title.

Still getting used to the block title exceptions. :)

ousleyp · 2025-11-14T17:43:15Z

modules/virt-example-vm-node-placement-node-affinity.adoc

 If possible, the scheduler avoids nodes that have the label `example-node-label-key = example-node-label-value`. However, if all candidate nodes have this label, the scheduler ignores this constraint.

 .Example VM manifest
+====


Interesting/good to know that wrapping the contents of the example in ====s is necessary.

openshift-ci · 2025-11-14T19:06:44Z

@jhradilek: all tests passed!

Full PR test history. Your PR dashboard.

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.

jhradilek · 2025-11-14T19:08:12Z

/cherrypick enterprise-4.21

jhradilek · 2025-11-14T19:08:33Z

/cherrypick enterprise-4.20

openshift-cherrypick-robot · 2025-11-14T19:08:59Z

@jhradilek: Failed to get PR patch from GitHub. This PR will need to be manually cherrypicked.

Error message

status code 406 not one of [200], body: {"message":"Sorry, the diff exceeded the maximum number of files (300). Consider using 'List pull requests files' API or locally cloning the repository instead.","errors":[{"resource":"PullRequest","field":"diff","code":"too_large"}],"documentation_url":"https://docs.github.com/rest/pulls/pulls#list-pull-requests-files","status":"406"}

In response to this:

/cherrypick enterprise-4.21

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.

openshift-cherrypick-robot · 2025-11-14T19:09:17Z

@jhradilek: Failed to get PR patch from GitHub. This PR will need to be manually cherrypicked.

Error message

status code 406 not one of [200], body: {"message":"Sorry, the diff exceeded the maximum number of files (300). Consider using 'List pull requests files' API or locally cloning the repository instead.","errors":[{"resource":"PullRequest","field":"diff","code":"too_large"}],"documentation_url":"https://docs.github.com/rest/pulls/pulls#list-pull-requests-files","status":"406"}

In response to this:

/cherrypick enterprise-4.20

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.

openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label Nov 13, 2025

openshift-ci bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 13, 2025

openshift-ci bot added the CNV Label for all CNV PRs label Nov 13, 2025

jhradilek requested a review from ousleyp November 13, 2025 23:16

jhradilek mentioned this pull request Nov 13, 2025

CNV-62649: Update CNV modules to pass DITA validation #96074

Closed

1 task

jhradilek commented Nov 13, 2025

View reviewed changes

jhradilek force-pushed the cnv-modules-dita-prep branch from 4f0d550 to afec182 Compare November 13, 2025 23:36

ocpdocs-vale-bot reviewed Nov 13, 2025

View reviewed changes

ousleyp added the branch/enterprise-4.21 label Nov 14, 2025

ousleyp added this to the Planned for 4.21 GA milestone Nov 14, 2025

ousleyp reviewed Nov 14, 2025

View reviewed changes

CNV-62649: Updated CNV modules to pass DITA validation

c61435e

jhradilek force-pushed the cnv-modules-dita-prep branch from afec182 to c61435e Compare November 14, 2025 18:43

ousleyp added the branch/enterprise-4.20 label Nov 14, 2025

jhradilek merged commit f0be10a into openshift:main Nov 14, 2025
2 checks passed

jhradilek mentioned this pull request Nov 18, 2025

[enterprise-4.21] CNV-62649: Updated CNV modules to pass DITA validation #102690

Merged

1 task

jhradilek mentioned this pull request Nov 18, 2025

[enterprise-4.20] CNV-62649: Updated CNV modules to pass DITA validation #102691

Merged

1 task

jhradilek deleted the cnv-modules-dita-prep branch November 18, 2025 16:18


		If you want the importer pod to use both the default network from the cluster and the secondary multus network, use the `k8s.v1.cni.cncf.io/networks: <network_name>` annotation.

		.Multus network annotation example


		If possible, the scheduler avoids nodes that have the label `example-node-label-key = example-node-label-value`. However, if all candidate nodes have this label, the scheduler ignores this constraint.

		.Example VM manifest

CNV-62649: Update CNV modules to pass DITA validation #102522

CNV-62649: Update CNV modules to pass DITA validation #102522

Uh oh!

Conversation

jhradilek commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci-robot commented Nov 13, 2025 • edited by openshift-ci bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jhradilek commented Nov 13, 2025

Uh oh!

openshift-ci-robot commented Nov 13, 2025 • edited by openshift-ci bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ocpdocs-previewbot commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ousleyp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-ci bot commented Nov 14, 2025

Uh oh!

Uh oh!

jhradilek commented Nov 14, 2025

Uh oh!

jhradilek commented Nov 14, 2025

Uh oh!

openshift-cherrypick-robot commented Nov 14, 2025

Uh oh!

openshift-cherrypick-robot commented Nov 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

jhradilek commented Nov 13, 2025 •

edited

Loading

openshift-ci-robot commented Nov 13, 2025 •

edited by openshift-ci bot

Loading

openshift-ci-robot commented Nov 13, 2025 •

edited by openshift-ci bot

Loading

ocpdocs-previewbot commented Nov 13, 2025 •

edited

Loading