Merge pull request #425 from klgill/BetaDocs-ConsolidatingPrereqsandV…

…ariables consolidating sections and checking xrefs
openstack-k8s-operators · May 2, 2024 · 312bcab · 312bcab
2 parents 31f8fee + fb0462f
commit 312bcab
Show file tree

Hide file tree

Showing 26 changed files with 53 additions and 97 deletions.
diff --git a/docs_user/assemblies/assembly_adopting-the-data-plane.adoc b/docs_user/assemblies/assembly_adopting-the-data-plane.adoc
@@ -1,6 +1,6 @@
 [id="adopting-data-plane_{context}"]
 
-:context: adopting-data-plane
+:context: data-plane
 
 = Adopting the data plane
 

diff --git a/docs_user/assemblies/assembly_configuring-network-for-RHOSO-deployment.adoc b/docs_user/assemblies/assembly_configuring-network-for-RHOSO-deployment.adoc
@@ -40,7 +40,7 @@ Specifically,
   **existing** deployment or, depending on IP address availability in the
   existing allocation pools, **new** ranges will be defined to be used for the
   new control plane services. If so, **IP routing** will be configured between
-  the old and new ranges. For more information, see xref:planning-your-ipam-configuration_ipam-configuration[Planning your IPAM configuration].
+  the old and new ranges. For more information, see xref:planning-your-ipam-configuration_configuring-network[Planning your IPAM configuration].
 * VLAN tags will be reused from the existing deployment.
 
 include::../modules/proc_retrieving-network-information-from-your-existing-deployment.adoc[leveloffset=+1]

diff --git a/..._user/assemblies/assembly_preparing-the-block-storage-service-for-adoption.adoc b/..._user/assemblies/assembly_preparing-the-block-storage-service-for-adoption.adoc
@@ -4,9 +4,10 @@
 
 = Preparing the {block_storage} configurations for adoption
 
-As described in xref:planning-the-new-deployment_planning[Planning the new deployment], {block_storage_first_ref} is configured using
+The {block_storage_first_ref} is configured using
 configuration snippets instead of using configuration parameters
-defined by the installer.
+defined by the installer. For more information, see xref:planning-the-new-deployment_planning[Planning the new deployment].
+//kgilliga: Note to self: This xref does not work in the preview. Need to revisit.
 
 The recommended way to deploy {block_storage} volume backends has changed to remove old
 limitations, add flexibility, and improve operations.

diff --git a/docs_user/modules/con_bare-metal-provisioning-service-configurations.adoc b/docs_user/modules/con_bare-metal-provisioning-service-configurations.adoc
@@ -4,7 +4,8 @@
 
 = Bare Metal Provisioning service configurations
 
-The {bare_metal_first_ref} is configured by using configuration snippets. For more information about the configuration snippets, see xref:planning-the-new-deployment_planning[Planning the new deployment].
+The {bare_metal_first_ref} is configured by using configuration snippets. For more information about the configuration snippets, see xref:planning-the-new-deployment_planning[Planning the new deployment]. 
+//kgilliga: Note to self: This xref does not work in the preview. Need to revisit.
 
 {OpenStackPreviousInstaller} generally took care to not override the defaults of the {bare_metal}, however as with any system of descreet configuration management attempting to provide a cross-version compatability layer, some configuration was certainly defaulted in particular ways. For example, PXE Loader file names were often overridden at intermediate layers, and you will thus want to pay particular attention to the settings you choose to apply in your adopted deployment. The operator attempts to apply reasonable working default configuration, but if you override them with prior configuration, your experience may not be ideal or your new {bare_metal} will fail to operate. Similarly, additional configuration may be necessary, for example
 if your `ironic.conf` has additional hardware types enabled and in use.

diff --git a/docs_user/modules/con_block-storage-service-requirements.adoc b/docs_user/modules/con_block-storage-service-requirements.adoc
@@ -1,7 +1,5 @@
 [id="block-storage-requirements_{context}"]
 
-//xref at the end of this module needs to be updated.
-
 = Block Storage service requirements
 
 The Block Storage service (cinder) has both local storage used by the service and OpenStack user requirements.
@@ -23,5 +21,5 @@ RBD, iSCSI, FC, NFS, NVMe-oF, etc.
 Once you know all the transport protocols that you are using, you can make
 sure that you are taking them into consideration when placing the Block Storage services (as mentioned above in the Node Roles section) and the right storage transport related binaries are running on the OpenShift nodes.
 
-Detailed information about the specifics for each storage transport protocol can be found in the xref:adopting-the-block-storage-service_{context}[Adopting the Block Storage service].
+Detailed information about the specifics for each storage transport protocol can be found in the xref:adopting-the-block-storage-service_adopt-control-plane[Adopting the Block Storage service].
 
diff --git a/docs_user/modules/con_changes-to-cephFS-via-NFS.adoc b/docs_user/modules/con_changes-to-cephFS-via-NFS.adoc
@@ -19,4 +19,4 @@ will correspond to the new clustered Ceph NFS service in contrast to other
 non-preferred export paths that continue to be displayed until the old
 isolated, standalone NFS service is decommissioned.
 
-See xref:creating-a-ceph-nfs-cluster_migrating-databases[Creating a Ceph NFS cluster] for instructions on setting up a clustered NFS service.
+See xref:creating-a-ceph-nfs-cluster_migrating-databases[Creating a NFS Ganesha cluster] for instructions on setting up a clustered NFS service.
diff --git a/docs_user/modules/con_openshift-preparation-for-block-storage-adoption.adoc b/docs_user/modules/con_openshift-preparation-for-block-storage-adoption.adoc
@@ -1,8 +1,11 @@
 [id="openshift-preparation-for-block-storage-adoption_{context}"]
 
+//kgilliga: There are some external links that need to be revisited.
+
 = {OpenShift} preparation for {block_storage} adoption
 
 As explained in xref:planning-the-new-deployment_planning[Planning the new deployment], before deploying {rhos_prev_long} {OpenStackShort} in {OpenShift}, you must ensure that the networks are ready, that you have decided the node selection, and also make sure any necessary changes to the {OpenShiftShort} nodes have been made. For {block_storage_first_ref} volume and backup services all these 3 must be carefully considered.
+//kgilliga: Note to self: xref for planning the new deployment does not work in preview. need to revisit.
 
 Node Selection::
 You might need, or want, to restrict the {OpenShiftShort} nodes where {block_storage} volume and

diff --git a/docs_user/modules/proc_adopting-autoscaling.adoc b/docs_user/modules/proc_adopting-autoscaling.adoc
@@ -59,7 +59,7 @@ pushd os-diff
 ./os-diff cdiff --service aodh -c /tmp/collect_tripleo_configs/aodh/etc/aodh/aodh.conf -o aodh_patch.yaml
 ----
 +
-For more information, see xref:pulling-the-openstack-configuration_{context}[Reviewing the {rhos_prev_long} control plane configuration].
+For more information, see xref:reviewing-the-openstack-control-plane-configuration_{context}[Reviewing the {rhos_prev_long} control plane configuration].
 
 . Patch the `OpenStackControlPlane` CR to deploy Aodh services:
 +

diff --git a/docs_user/modules/proc_adopting-compute-services-to-the-data-plane.adoc b/docs_user/modules/proc_adopting-compute-services-to-the-data-plane.adoc
@@ -1,13 +1,11 @@
 [id="adopting-compute-services-to-the-data-plane_{context}"]
 
-//check xrefs.
-
 = Adopting Compute services to the {rhos_acro} data plane
 
 .Prerequisites
 
 * Remaining source cloud xref:stopping-infrastructure-management-and-compute-services_{context}[Stopping infrastructure management and Compute services] on Compute hosts.
-* Ceph backend for Nova/Libvirt is configured xref:configuring-a-ceph-backend_{context}[Configuring a Ceph backend].
+* Ceph backend for Nova/Libvirt is configured xref:configuring-a-ceph-backend_migrating-databases[Configuring a Ceph backend].
 * Make sure the IPAM is configured
 
 ----

diff --git a/docs_user/modules/proc_adopting-key-manager-service.adoc b/docs_user/modules/proc_adopting-key-manager-service.adoc
@@ -17,10 +17,6 @@ Additional backends are available, such as PKCS11 and DogTag, however they are n
 * Previous Adoption steps completed. Notably, MariaDB, RabbitMQ and Keystone.
 should be already adopted.
 
-.Variables
-
-No shell variables are necessary currently.
-
 .Procedure
 
 . Add the kek secret. In this case we are updating and using `osp-secret`,

diff --git a/docs_user/modules/proc_adopting-telemetry-services.adoc b/docs_user/modules/proc_adopting-telemetry-services.adoc
@@ -59,7 +59,7 @@ pushd os-diff
 ./os-diff cdiff --service ceilometer -c /tmp/collect_tripleo_configs/ceilometer/etc/ceilometer/ceilometer.conf -o ceilometer_patch.yaml
 ----
 +
-For more information, see xref:pulling-the-openstack-configuration_{context}[Reviewing the {rhos_prev_long} control plane configuration].
+For more information, see xref:reviewing-the-openstack-control-plane-configuration_{context}[Reviewing the {rhos_prev_long} control plane configuration].
 
 . Patch the `OpenStackControlPlane` CR to deploy Ceilometer services:
 +

diff --git a/docs_user/modules/proc_adopting-the-compute-service.adoc b/docs_user/modules/proc_adopting-the-compute-service.adoc
@@ -1,6 +1,6 @@
 [id="adopting-the-compute-service_{context}"]
 
-//Check xref contexts.
+//kgilliga: Note to self: "Adopting the data plane" xrefs do not work. Need to revisit.
 
 = Adopting the {compute_service}
 
@@ -21,15 +21,12 @@ must already be imported into the control plane MariaDB;
  ** the xref:adopting-the-image-service_{context}[Adopting the Image service] needs to be imported;
  ** the xref:migrating-ovn-data_migrating-databases[Migrating OVN data] need to be imported;
  ** the xref:adopting-the-networking-service_{context}[Adopting the Networking service] needs to be imported;
- ** the xref:adopting-the-bare-metal-provisioning-service_{context}[Adopting the Openstack Baremetal service] needs to be imported;
+ ** the xref:adopting-the-bare-metal-provisioning-service_{context}[Adopting the Openstack Baremetal service] needs to be imported; 
+//kgilliga:Need to revist this xref. Might rewrite this section anyway.
  ** Required services specific topology
-xref:pulling-the-openstack-configuration_{context}[Pulling the OpenStack configuration].
-//kgilliga: this xref should specifically point to the Get services topology specific configuration module when it's ready.
+xref:proc_retrieving-services-topology-specific-configuration_{context}[Retrieving services from a topology specific-configuration].
  ** {rhos_prev_long} services have been stopped. For more information, see xref:stopping-openstack-services_migrating-databases[Stopping {rhos_prev_long} services].
-
-.Variables
-
-Define the shell variables and aliases used in the steps below. The values are just illustrative, use values that are correct for your environment:
+* Define the following shell variables. The values that are used are examples. Replace these example values with values that are correct for your environment:
 ----
 alias openstack="oc exec -t openstackclient -- openstack"
 ----
@@ -135,7 +132,7 @@ oc wait --for condition=Ready --timeout=300s Nova/nova
 ----
 +
 The local Conductor services will be started for each cell, while the superconductor runs in `cell0`.
-Note that `disable_compute_service_check_for_ffu` is mandatory for all imported Nova services, until the external data plane is imported, and until Nova Compute services fast-forward upgraded. For more information, see xref:adopting-dataplane_{context}[Data Plane Adoption].
+Note that `disable_compute_service_check_for_ffu` is mandatory for all imported Nova services, until the external data plane is imported, and until Nova Compute services fast-forward upgraded. For more information, see xref:adopting-data-plane_data-plane[Adopting the data plane].
 
 .Verification 
 
@@ -147,7 +144,7 @@ $ openstack endpoint list | grep nova
 $ openstack server list
 ----
 
-Compare the following outputs with the topology specific configuration in xref:pulling-the-openstack-configuration_{context}[Pulling the OpenStack configuration].
+Compare the following outputs with the topology specific configuration in xref:proc_retrieving-services-topology-specific-configuration_{context}[Retrieving services from a topology specific-configuration].
 
 * Query the superconductor for cell1 existance and compare it to pre-adoption values:
 +
@@ -164,4 +161,4 @@ The expected changes to happen:
  ** RabbitMQ transport URL no longer uses `guest`.
 
 [NOTE]
-At this point, the {compute_service} control plane services have yet taken control over existing {compute_service} compute workloads. That would become possible to verify only after the data plane adoption is completed. For more information, see xref:adopting-dataplane_{context}[Data Plane Adoption].
+At this point, the {compute_service} control plane services do not control the existing {compute_service} Compute workloads. The control plane manages the data plane only after the data adoption process is successfully completed. For more information, see xref:adopting-data-plane_data-plane[Adopting the data plane].
diff --git a/docs_user/modules/proc_adopting-the-identity-service.adoc b/docs_user/modules/proc_adopting-the-identity-service.adoc
@@ -25,10 +25,6 @@ type: Opaque
 EOF
 ----
 
-.Variables
-
-No shell variables are necessary currently.
-
 .Procedure
 
 . Patch `OpenStackControlPlane` to deploy {identity_service}:

diff --git a/docs_user/modules/proc_adopting-the-object-storage-service.adoc b/docs_user/modules/proc_adopting-the-object-storage-service.adoc
@@ -10,10 +10,9 @@ This section only applies if you are using OpenStack Swift as {object_storage_fi
 * The {object_storage} storage backend services must still be running.
 * Storage network has been properly configured on the {OpenShift} cluster.
 
-.Variables
-
-No new environmental variables need to be defined, though you use the
-`CONTROLLER1_SSH` alias that was defined in a previous step.
+//No new environmental variables need to be defined, though you use the
+//`CONTROLLER1_SSH` alias that was defined in a previous step.
+//kgilliga: I commented this part out because I need to understand why "`CONTROLLER1_SSH` alias that was defined in a previous step" is significant for customers to know downstream.
 
 .Procedure
 

diff --git a/docs_user/modules/proc_adopting-the-openstack-dashboard.adoc b/docs_user/modules/proc_adopting-the-openstack-dashboard.adoc
@@ -7,10 +7,6 @@
 * Previous Adoption steps completed. Notably, Memcached and
 {identity_service_first_ref} should be already adopted.
 
-.Variables
-
-No shell variables are necessary currently.
-
 .Procedure
 
 * Patch `OpenStackControlPlane` to deploy the {dashboard}:

diff --git a/docs_user/modules/proc_adopting-the-placement-service.adoc b/docs_user/modules/proc_adopting-the-placement-service.adoc
@@ -13,10 +13,6 @@ must already be imported into the control plane MariaDB.
  ** the Memcached operator needs to be deployed (nothing to import for it from
 the source environment).
 
-.Variables
-
-No shell variables are necessary currently.
-
 .Procedure
 
 * Patch `OpenStackControlPlane` to deploy the Placement service:

diff --git a/docs_user/modules/proc_configuring-a-ceph-backend.adoc b/docs_user/modules/proc_configuring-a-ceph-backend.adoc
@@ -33,11 +33,7 @@ ceph auth caps client.openstack \
 .Prerequisites
 
 * The `OpenStackControlPlane` custom resource (CR) must already exist.
-
-.Variables
-
-Define the shell variables used in the steps below. The values are
-just illustrative, use values that are correct for your environment:
+* Define the following shell variables. The values that are used are examples. Replace these example values with values that are correct for your environment: 
 
 [subs=+quotes]
 ----

diff --git a/docs_user/modules/proc_deploying-backend-services.adoc b/docs_user/modules/proc_deploying-backend-services.adoc
@@ -35,9 +35,6 @@ ifeval::["{build}" != "downstream"]
 For developer/CI environments driven by install_yamls, make sure
 you've run `make crc_storage`.
 endif::[]
-
-.Variables
-
 * Set the desired admin password for the control plane deployment. This can
 be the original deployment's admin password or something else.
 +
@@ -50,7 +47,6 @@ To use the existing {OpenStackShort} deployment password:
 ----
 ADMIN_PASSWORD=$(cat ~/tripleo-standalone-passwords.yaml | grep ' AdminPassword:' | awk -F ': ' '{ print $2; }')
 ----
-
 * Set service password variables to match the original deployment.
 Database passwords can differ in the control plane environment, but
 synchronizing the service account passwords is a required step.

diff --git a/docs_user/modules/proc_deploying-the-bare-metal-provisioning-service.adoc b/docs_user/modules/proc_deploying-the-bare-metal-provisioning-service.adoc
@@ -27,11 +27,8 @@ It is critical that this configuration file comes from one of the controllers an
 //kgilliga: What is meant by "overcloud Ironic deployment? Can this be changed to the "RHOSP Bare Metal Provisioning service deployment"?
 
 * If adopting the Ironic Inspector service you need the value of the `IronicInspectorSubnets` {OpenStackPreviousInstaller} parameter. Use the same values to populate the `dhcpRanges` parameter in the target environment.
-
-.Variables
-
-Define the shell variables and aliases used in the steps below. The values are just illustrative, use values that are correct for your environment:
-
+* Define the following shell variables. The values that are used are examples. Replace these example values with values that are correct for your environment:
++
 ----
 alias openstack="oc exec -t openstackclient -- openstack"
 ----

diff --git a/docs_user/modules/proc_deploying-the-block-storage-services.adoc b/docs_user/modules/proc_deploying-the-block-storage-services.adoc
@@ -18,11 +18,10 @@ stopped and the service databases must already be imported into the control plan
 ----
 $CONTROLLER1_SSH cat /var/lib/config-data/puppet-generated/cinder/etc/cinder/cinder.conf > cinder.conf
 ----
-
-.Variables
-
-No new environmental variables need to be defined, though you use the
-`CONTROLLER1_SSH` that was defined in a previous step for the pre-checks.
+//No new environmental variables need to be defined, though you use the
+//`CONTROLLER1_SSH` that was defined in a previous step for the pre-checks.
+//kgilliga: I commented this out for now because I'm not sure why "use the
+//`CONTROLLER1_SSH` that was defined in a previous step for the pre-checks" is relevant.
 
 .Procedure
 

diff --git a/docs_user/modules/proc_migrating-databases-to-mariadb-instances.adoc b/docs_user/modules/proc_migrating-databases-to-mariadb-instances.adoc
@@ -23,12 +23,8 @@ here this time).
 //kgilliga: this xref should specifically point to the Get services topology specific configuration module when it's ready.
  ** {OpenStackShort} services have been stopped. For more information, see xref:stopping-openstack-services_{context}[Stopping {rhos_prev_long} services].
  ** There must be network routability between the original MariaDB and the MariaDB for the control plane.
-
-.Variables
-
-Define the shell variables used in the steps below. The values are
-just illustrative, use values that are correct for your environment:
-
+* Define the following shell variables. The values that are used are examples. Replace these example values with values that are correct for your environment:
++
 ----
 PODIFIED_MARIADB_IP=$(oc get svc --selector "mariadb/name=openstack" -ojsonpath='{.items[0].spec.clusterIP}')
 PODIFIED_CELL1_MARIADB_IP=$(oc get svc --selector "mariadb/name=openstack-cell1" -ojsonpath='{.items[0].spec.clusterIP}')
@@ -65,6 +61,7 @@ SOURCE_DB_ROOT_PASSWORD=$(cat ~/tripleo-standalone-passwords.yaml | grep ' Mysql
 mkdir ~/adoption-db
 cd ~/adoption-db
 ----
++
 [source,yaml]
 ----
 oc apply -f - <<EOF
@@ -113,7 +110,7 @@ EOF
 ----
 
 * Wait for the pod to come up
-
++
 ----
 oc wait --for condition=Ready pod/mariadb-copy-data --timeout=30s
 ----

diff --git a/docs_user/modules/proc_migrating-ovn-data.adoc b/docs_user/modules/proc_migrating-ovn-data.adoc
@@ -18,12 +18,8 @@ defined. Specifically, `openstack/internalapi` network is defined.
  ** There must be network routability between:
   *** The adoption host and the original OVN.
   *** The adoption host and the control plane OVN.
-
-.Variables
-
-Define the shell variables used in the steps below. The values are
-just illustrative, use values that are correct for your environment:
-
+* Define the following shell variables. The values that are used are examples. Replace these example values with values that are correct for your environment:
++
 ----
 STORAGE_CLASS_NAME=crc-csi-hostpath-provisioner
 ifeval::["{build}" != "downstream"]
@@ -34,9 +30,9 @@ OVSDB_IMAGE=registry.redhat.io/rhosp-dev-preview/openstack-ovn-base-rhel9:18.0
 endif::[]
 SOURCE_OVSDB_IP=172.17.1.49
 ----
-
-The real value of the `SOURCE_OVSDB_IP` can be get from the puppet generated configs:
-
++
+You can get the value to set `SOURCE_OVSDB_IP` by querying the puppet-generated configurations:
++
 ----
 grep -rI 'ovn_[ns]b_conn' /var/lib/config-data/puppet-generated/
 ----

diff --git a/docs_user/modules/proc_migrating-tls-everywhere.adoc b/docs_user/modules/proc_migrating-tls-everywhere.adoc
@@ -26,7 +26,7 @@ This procedure will also need to be modified if the signing keys are stored in a
 * Your {OpenStackShort} deployment is using TLS-e.
 * Make sure the previous Adoption steps (if any) have been performed successfully.
 * Make sure the backend services on the new deployment are not started yet.
-* Define the shell variables used in the following steps. The values are illustrative and refer to a single node standalone {OpenStackPreviousInstaller} deployment. Use values that are correct for your environment:
+* Define the following shell variables. The values that are used are examples and refer to a single node standalone {OpenStackPreviousInstaller} deployment. Replace these example values with values that are correct for your environment:
 +
 ifeval::["{build}" != "downstream"]
 ----

diff --git a/docs_user/modules/proc_retrieving-services-topology-specific-configuration.adoc b/docs_user/modules/proc_retrieving-services-topology-specific-configuration.adoc
@@ -6,8 +6,7 @@
 
 .Prerequisites
 
-* Define the shell variables used in the steps below. The values are
-just illustrative, use values that are correct for your environment:
+* Define the following shell variables. The values that are used are examples. Replace these example values with values that are correct for your environment:
 +
 ----
 CONTROLLER_SSH="ssh -F ~/director_standalone/vagrant_ssh_config vagrant@standalone"

diff --git a/..._user/modules/proc_stopping-infrastructure-management-and-compute-services.adoc b/..._user/modules/proc_stopping-infrastructure-management-and-compute-services.adoc
@@ -10,7 +10,7 @@ Templates).
 
 .Prerequisites
 
-* Define the following shell variables. The values are illustrative and refer to a single node standalone {OpenStackPreviousInstaller} deployment. Use values that are correct for your environment: 
+* Define the following shell variables. The values that are used are examples and refer to a single node standalone {OpenStackPreviousInstaller} deployment. Replace these example values with values that are correct for your environment:
 +
 [subs=+quotes]
 ----