Merge pull request #1038 from klgill/fix-vale-warnings

openshift-merge-bot[bot] · web-flow · commit d904b91a2cbc · 2025-08-25T20:20:58.000Z
fixed warnings for DITA conversion
diff --git a/docs_user/modules/con_adoption-limitations.adoc b/docs_user/modules/con_adoption-limitations.adoc
@@ -6,16 +6,16 @@
 [role="_abstract"]
 Before you proceed with the adoption, check which features are Technology Previews or unsupported.
 
-.Technology Preview
-
+Technology Preview::
++
 The following features are Technology Previews and have not been tested within the context of the {rhos_long_noacro} adoption:
-
++
 * NFS Ganesha back end for {rhos_component_storage_file_first_ref}
 * iSCSI and FC-based drivers for {block_storage_first_ref}
 * {block_storage} back end for the {image_service_first_ref}
-
++
 The following {compute_service_first_ref} features are Technology Previews:
-
++
 * Compute hosts with `/var/lib/nova/instances` on NFS
 * NUMA-aware vswitches
 * PCI passthrough by flavor
@@ -28,10 +28,10 @@ The following {compute_service_first_ref} features are Technology Previews:
 * File-backed memory
 * Defining a custom inventory of resources in a YAML file, `provider.yaml`
 
-.Unsupported features
-
+Unsupported features::
++
 The adoption process does not support the following features:
-
++
 * instanceHA
 * DCN
 * Designate
diff --git a/docs_user/modules/con_adoption-prerequisites.adoc b/docs_user/modules/con_adoption-prerequisites.adoc
@@ -7,7 +7,7 @@
 Before you begin the adoption procedure, complete the following prerequisites:
 
 Planning information::
-
++
 * Review the xref:adoption-limitations_{context}[Adoption limitations].
 * Review the {rhocp_long} requirements, data plane node requirements, Compute node requirements, and so on. For more information, see link:{planning}/index[{planning-t}].
 * Review the adoption-specific networking requirements. For more information, see xref:configuring-network-for-RHOSO-deployment_planning[Configuring the network for the RHOSO deployment].
@@ -24,6 +24,7 @@ endif::[]
 ifeval::["{build_variant}" == "ospdo"]
 * In director Operator adoption, the source {rhos_prev_long} {rhos_prev_ver} namespace is `openstack`. In order to successfully adopt the {OpenStackShort} {rhos_prev_ver} environment, the destination {rhos_acro} {rhos_curr_ver} namespace must be different, for example, `rhoso`.
 endif::[]
++
 [source, shell]
 ----
 ifeval::["{build_variant}" == "ospdo"]
@@ -36,32 +37,32 @@ endif::[]
 * Familiarize yourself with mapping RHOSO versions to OpenStack Operators and OpenStackVersion custom resources (CRs). For more information, see the Red Hat Knowledgebase article link:https://access.redhat.com/articles/7125383[How RHOSO versions map to OpenStack Operators and OpenStackVersion CRs].
 
 Back-up information::
-
++
 * Back up your {rhos_prev_long} ({OpenStackShort}) {rhos_prev_ver} environment by using one of the following options:
 ** The Relax-and-Recover tool. For more information, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_platform/17.1/html/backing_up_and_restoring_the_undercloud_and_control_plane_nodes/assembly_backing-up-the-undercloud-and-the-control-plane-nodes-using-the-relax-and-recover-tool_br-undercloud-ctlplane[Backing up the undercloud and the control plane nodes by using the Relax-and-Recover tool] in _Backing up and restoring the undercloud and control plane nodes_.
 ** The Snapshot and Revert tool. For more information, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_platform/17.1/html/backing_up_and_restoring_the_undercloud_and_control_plane_nodes/assembly_snapshot-and-revert-appendix_snapshot-and-revert-appendix[Backing up your Red Hat OpenStack Platform cluster by using the Snapshot and Revert tool] in _Backing up and restoring the undercloud and control plane nodes_.
 ** A third-party backup and recovery tool. For more information about certified backup and recovery tools, see the link:https://catalog.redhat.com/[Red Hat Ecosystem Catalog].
 * Back up the configuration files from the {OpenStackShort} services and {OpenStackPreviousInstaller} on your file system. For more information, see xref:pulling-configuration-from-tripleo-deployment_adopt-control-plane[Pulling the configuration from a {OpenStackPreviousInstaller} deployment].
 
 Compute::
-
++
 * Upgrade your Compute nodes to Red Hat Enterprise Linux {rhel_prev_ver}. For more information, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_platform/17.1/html-single/framework_for_upgrades_16.2_to_17.1/index#upgrading-compute-nodes_upgrading-the-compute-node-operating-system[Upgrading all Compute nodes to RHEL 9.2] in _Framework for upgrades (16.2 to 17.1)_.
 * Perform a minor update to the latest {OpenStackShort} version. For more information, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_platform/17.1/html/performing_a_minor_update_of_red_hat_openstack_platform/index[Performing a minor update of Red Hat OpenStack Platform].
 * Install the `systemd-container` package on your Compute hosts. For more information, see xref:installing-the-systemd-container-package-on-compute-hosts_{context}[Installing the `systemd-container` package on Compute hosts].
 
 ML2/OVS::
-
++
 * If you use the Modular Layer 2 plug-in with Open vSwitch mechanism driver (ML2/OVS), migrate it to the Modular Layer 2 plug-in with Open Virtual Networking (ML2/OVN) mechanism driver. For more information, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_platform/17.1/html/migrating_to_the_ovn_mechanism_driver/index[Migrating to the OVN mechanism driver].
 
 Tools::
-
++
 * Install the `oc` command line tool on your workstation.
 * Install the `podman` command line tool on your workstation.
 
 {OpenStackShort} {rhos_prev_ver} release::
-
++
 * The {OpenStackShort} {rhos_prev_ver} cloud is updated to the latest minor version of the {rhos_prev_ver} release.
 
 {OpenStackShort} {rhos_prev_ver} hosts::
-
++
 * All control plane and data plane hosts of the {OpenStackShort} {rhos_prev_ver} cloud are up and running, and continue to run throughout the adoption procedure.
diff --git a/docs_user/modules/con_adoption-process-overview.adoc b/docs_user/modules/con_adoption-process-overview.adoc
@@ -6,8 +6,8 @@
 [role="_abstract"]
 Familiarize yourself with the steps of the adoption process and the optional post-adoption tasks.
 
-.Main adoption process
-
+Main adoption process::
++
 . xref:migrating-tls-everywhere_configuring-network[Migrate TLS everywhere (TLS-e) to the Red Hat OpenStack Services on OpenShift (RHOSO) deployment].
 . xref:migrating-databases-to-the-control-plane_configuring-network[Migrate your existing databases to the new control plane].
 . xref:adopting-openstack-control-plane-services_configuring-network[Adopt your Red Hat OpenStack Platform 17.1 control plane services to the new RHOSO 18.0 deployment].
@@ -22,8 +22,8 @@ endif::[]
 .. xref:migrating-ceph-rgw_migrating-ceph-monitoring[Migrate {Ceph} RGW to external RHEL nodes].
 .. xref:migrating-ceph-rbd_migrating-ceph-monitoring[Migrate {Ceph} RBD to external RHEL nodes].
 
-.Post-adoption tasks
-
+Post-adoption tasks::
++
 * Optional: Run tempest to verify that the entire adoption process is working properly. For more information, see link:{defaultURL}/validating_and_troubleshooting_the_deployed_cloud/index[Validating and troubleshooting the deployed cloud].
 * Optional: Perform a minor update from RHEL 9.2 to 9.4. You can perform a minor update any time after you complete the adoption procedure. For more information, see link:{defaultURL}/updating_your_environment_to_the_latest_maintenance_release/index[Updating your environment to the latest maintenance release].
 * Optional: Verify that you migrated all services from the Controller nodes, and then power off the nodes. If any services are still running in the Controller nodes, such as Open Virtual Networking (ML2/OVN), {object_storage_first_ref}, or {Ceph}, do not power off the nodes.
diff --git a/docs_user/modules/proc_adopting-the-networking-service.adoc b/docs_user/modules/proc_adopting-the-networking-service.adoc
@@ -12,6 +12,10 @@ The {networking_service} adoption is complete if you see the following results:
 * The `NeutronAPI` service is running.
 * The {identity_service_first_ref} endpoints are updated, and the same back end of the source cloud is available.
 
+ifeval::["{build}" != "downstream"]
+The {networking_service} adoption follows a similar pattern to https://github.com/openstack-k8s-operators/data-plane-adoption/blob/main/keystone_adoption.md[Keystone].
+endif::[]
+
 .Prerequisites
 
 * Ensure that Single Node OpenShift or OpenShift Local is running in the {rhocp_long} cluster.
@@ -20,9 +24,6 @@ The {networking_service} adoption is complete if you see the following results:
 
 
 .Procedure
-ifeval::["{build}" != "downstream"]
-The {networking_service} adoption follows a similar pattern to https://github.com/openstack-k8s-operators/data-plane-adoption/blob/main/keystone_adoption.md[Keystone].
-endif::[]
 
 * Patch the `OpenStackControlPlane` CR to deploy the {networking_service}:
 +
diff --git a/docs_user/modules/proc_adopting-the-orchestration-service.adoc b/docs_user/modules/proc_adopting-the-orchestration-service.adoc
@@ -9,6 +9,10 @@ is disabled. The patch starts the service with the configuration parameters that
 
 After you complete the adoption process, you have CRs for `Heat`, `HeatAPI`, `HeatEngine`, and `HeatCFNAPI`, and endpoints within the {identity_service_first_ref} to facilitate these services.
 
+ifeval::["{build}" != "downstream"]
+The Heat Adoption follows a similar workflow to https://github.com/openstack-k8s-operators/data-plane-adoption/blob/main/keystone_adoption.md[Keystone].
+endif::[]
+
 .Prerequisites
 
 * The source {OpenStackPreviousInstaller} environment is running.
@@ -17,9 +21,6 @@ After you complete the adoption process, you have CRs for `Heat`, `HeatAPI`, `He
 * If your existing {orchestration} stacks contain resources from other services such as {networking_first_ref}, {compute_service_first_ref}, {object_storage_first_ref}, and so on, adopt those sevices before adopting the {orchestration}.
 
 .Procedure
-ifeval::["{build}" != "downstream"]
-The Heat Adoption follows a similar workflow to https://github.com/openstack-k8s-operators/data-plane-adoption/blob/main/keystone_adoption.md[Keystone].
-endif::[]
 
 . Retrieve the existing `auth_encryption_key` and `service` passwords. You use these passwords to patch the `osp-secret`. In the following example, the `auth_encryption_key` is used as `HeatAuthEncryptionKey` and the `service` password is used as `HeatPassword`:
 +
diff --git a/docs_user/modules/proc_configuring-openshift-worker-nodes.adoc b/docs_user/modules/proc_configuring-openshift-worker-nodes.adoc
@@ -8,6 +8,21 @@ To connect service pods to isolated networks on {rhocp_long} worker nodes that r
 
 This configuration is managed by the NMState operator, which uses `NodeNetworkConfigurationPolicy` custom resources (CRs) to define the desired network configuration for the nodes.
 
+// TODO: Move this to the IPv6 section once it is fully documented, both upstream and downstream.
+ifeval::["{build}" != "downstream"]
+[WARNING]
+In IPv6, {rhocp_long} worker nodes need a `/64` prefix allocation due to OVN
+limitations (RFC 4291). For dynamic IPv6 configuration, you need to change the
+prefix allocation on the Router Advertisement settings. If you want to use
+manual configuration for IPv6, define a similar CR to the
+`NodeNetworkConfigurationPolicy` CR example in this procedure, and define an
+IPv6 address and disable IPv4. Because the constraint for the `/64` prefix did
+not exist in {OpenstackPreviousInstaller}, your {OpenStackShort}
+control plane network might not have enough capacity to allocate these
+networks. If that is the case, allocate a prefix that fits a large enough number
+of addresses, for example, `/60`. The prefix depends on the number of worker nodes you have.
+endif::[]
+
 .Procedure
 
 * For each {OpenShiftShort} worker node, define a `NodeNetworkConfigurationPolicy` CR that describes the desired network configuration. For example:
@@ -72,18 +87,3 @@ items:
       kubernetes.io/hostname: ocp-worker-0
       node-role.kubernetes.io/worker: ""
 ----
-
-// TODO: Move this to the IPv6 section once it is fully documented, both upstream and downstream.
-ifeval::["{build}" != "downstream"]
-[WARNING]
-In IPv6, {rhocp_long} worker nodes need a `/64` prefix allocation due to OVN
-limitations (RFC 4291). For dynamic IPv6 configuration, you need to change the
-prefix allocation on the Router Advertisement settings. If you want to use
-manual configuration for IPv6, define a similar CR to the
-`NodeNetworkConfigurationPolicy` CR example in this procedure, and define an
-IPv6 address and disable IPv4. Because the constraint for the `/64` prefix did
-not exist in {OpenstackPreviousInstaller}, your {OpenStackShort}
-control plane network might not have enough capacity to allocate these
-networks. If that is the case, allocate a prefix that fits a large enough number
-of addresses, for example, `/60`. The prefix depends on the number of worker nodes you have.
-endif::[]
diff --git a/docs_user/modules/proc_deploying-backend-services.adoc b/docs_user/modules/proc_deploying-backend-services.adoc
@@ -351,7 +351,7 @@ spec:
         customIssuer: rootca-internal
       enabled: true
 ----
-
++
 [NOTE]
 ====
 If you use IPv6, change the load balancer IPs to the IPs in your environment, for example:
diff --git a/docs_user/modules/proc_migrating-ceph-mds.adoc b/docs_user/modules/proc_migrating-ceph-mds.adoc
@@ -250,9 +250,8 @@ mds.mds.cephstorage-2.gnfhfe  cephstorage-2.redhat.local                     run
 ----
 
 ifeval::["{build}" != "downstream"]
-.Useful resources
-
+[role="_additional-resources"]
+.Additional resources
 * https://docs.ceph.com/en/reef/cephfs/eviction[cephfs - eviction]
-
 * https://docs.ceph.com/en/reef/cephfs/standby/#configuring-mds-file-system-affinity[ceph mds - affinity]
 endif::[]
diff --git a/docs_user/modules/proc_migrating-object-storage-data-to-rhoso-nodes.adoc b/docs_user/modules/proc_migrating-object-storage-data-to-rhoso-nodes.adoc
@@ -144,7 +144,7 @@ swift-ring-tool remove 172.20.0.100
 swift-ring-tool rebalance
 swift-ring-tool push'
 ----
-
++
 [NOTE]
 Even if all replicas are on the new nodes and the `swift-dispersion-report` command reports 100% of the copies found, there might still be data on the old nodes. The replicators remove this data, but it might take more time.
 
diff --git a/docs_user/modules/proc_performing-a-fast-forward-upgrade-on-compute-services.adoc b/docs_user/modules/proc_performing-a-fast-forward-upgrade-on-compute-services.adoc
@@ -184,5 +184,5 @@ ${BASH_ALIASES[openstack]} server list -c Name -c Status -f value | grep -qF "te
   ${BASH_ALIASES[openstack]} server --os-compute-api-version 2.48 show --diagnostics test --fit-width -f json | jq -r '.state' | grep running || echo FAIL
 ----
 
-[NOTE]
+.Next steps
 After the data plane adoption, the Compute hosts continue to run Red Hat Enterprise Linux (RHEL) {rhel_prev_ver}. To take advantage of RHEL {rhel_curr_ver}, perform a minor update procedure after finishing the adoption procedure.
diff --git a/docs_user/modules/proc_preparing-block-storage-service-by-using-agnostic-config-file.adoc b/docs_user/modules/proc_preparing-block-storage-service-by-using-agnostic-config-file.adoc
@@ -17,9 +17,9 @@ contents of the whole file into a `Secret`.
 for each backend and just adding the respective `enabled_backends` option.
 . Add external files as mentioned in the last bullet of the tailor-made
 configuration explanation.
-
++
 Example of what the quick and dirty configuration patch would look like:
-
++
 [source,yaml]
 ----
    spec:
diff --git a/docs_user/modules/proc_retrieving-network-information-from-your-existing-deployment.adoc b/docs_user/modules/proc_retrieving-network-information-from-your-existing-deployment.adoc
@@ -15,6 +15,10 @@ deployment. After you retrieve your network configuration, you have the followin
   services, these addresses are excluded from the corresponding allocation
   pools.
 
+ifeval::["{build_variant}" == "ospdo"]
+For more information about director Operator network configurations, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_platform/17.1/html-single/deploying_an_overcloud_in_a_red_hat_openshift_container_platform_cluster_with_director_operator/index#assembly_creating-networks-with-director-operator[Creating networks with director Operator] in _Deploying an overcloud in a Red Hat OpenShift Container Platform cluster with director Operator_.
+endif::[]
+
 .Procedure
 
 . Find the network configuration in the `network_data.yaml` file. For example:
@@ -64,7 +68,3 @@ consumed and are not available for the new control plane services until the adop
 
 . Repeat this procedure for each isolated network and each host in the
 configuration.
-
-ifeval::["{build_variant}" == "ospdo"]
-For more information about director Operator network configurations, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_platform/17.1/html-single/deploying_an_overcloud_in_a_red_hat_openshift_container_platform_cluster_with_director_operator/index#assembly_creating-networks-with-director-operator[Creating networks with director Operator] in _Deploying an overcloud in a Red Hat OpenShift Container Platform cluster with director Operator_.
-endif::[]
diff --git a/docs_user/modules/proc_retrieving-topology-specific-service-configuration.adoc b/docs_user/modules/proc_retrieving-topology-specific-service-configuration.adoc
@@ -238,5 +238,6 @@ $ chmod 0600 ~/.source_cloud_exported_variables*
 +
 <1> If `neutron-sriov-nic-agent` agents are running in your {OpenStackShort} deployment, get the configuration to use for the data plane adoption.
 
-[NOTE]
+.Next steps
+
 This configuration and the exported values are required later, during the data plane adoption post-checks. After the {OpenStackShort} control plane services are shut down, if any of the exported values are lost, re-running the `export` command fails because the control plane services are no longer running on the source cloud, and the data cannot be retrieved. To avoid data loss, preserve the exported values in an environment file before shutting down the control plane services.
diff --git a/docs_user/modules/proc_rolling-back-the-control-plane-adoption.adoc b/docs_user/modules/proc_rolling-back-the-control-plane-adoption.adoc
@@ -172,6 +172,7 @@ $ oc delete --ignore-not-found=true --wait=false pod ovn-copy-data
 $ oc delete --ignore-not-found=true secret osp-secret
 ----
 
-[NOTE]
+.Next steps
+
 After you restore the {OpenStackShort} control plane services, their internal
 state might have changed. Before you retry the adoption procedure, verify that all the control plane resources are removed and that there are no leftovers which could affect the following adoption procedure attempt. You must not use previously created copies of the database contents in another adoption attempt. You must make a new copy of the latest state of the original source database contents. For more information about making new copies of the database, see xref:migrating-databases-to-the-control-plane_configuring-network[Migrating databases to the control plane].
diff --git a/docs_user/modules/proc_using-new-subnet-ranges.adoc b/docs_user/modules/proc_using-new-subnet-ranges.adoc
@@ -20,6 +20,10 @@ In the following procedure, you configure `NetworkAttachmentDefinition` custom r
 
 The values that are used in the following procedure are examples. Use values that are specific to your configuration.
 
+ifeval::["{build_variant}" == "ospdo"]
+For more information about director Operator network configurations, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_platform/17.1/html-single/deploying_an_overcloud_in_a_red_hat_openshift_container_platform_cluster_with_director_operator/index#assembly_creating-networks-with-director-operator[Creating networks with director Operator] in _Deploying an overcloud in a Red Hat OpenShift Container Platform cluster with director Operator_.
+endif::[]
+
 .Procedure
 
 
@@ -40,10 +44,6 @@ network_config:
 +
 Repeat this configuration for other networks that need to use different subnets for the new and existing parts of the deployment.
 
-ifeval::["{build_variant}" == "ospdo"]
-For more information about director Operator network configurations, see link:https://docs.redhat.com/en/documentation/red_hat_openstack_platform/17.1/html-single/deploying_an_overcloud_in_a_red_hat_openshift_container_platform_cluster_with_director_operator/index#assembly_creating-networks-with-director-operator[Creating networks with director Operator] in _Deploying an overcloud in a Red Hat OpenShift Container Platform cluster with director Operator_.
-endif::[]
-
 . Apply the new configuration to every {OpenStackShort} node:
 +
 ----
