Bug 2187302

You don't put any values or parameters into those files. You simply include them as templates against the overcloud deployment, which are referenced in the example immediately following these bullet points.

Proposed text:


Validate that the following files are passed to RHOSP director "openstack overcloud deploy" command, as seen below,
to configure:
   - ceilometer-write-qdr.yaml - ensure that Ceilometer telemetry and events are sent to STF
   - qdr-edge-only.yaml - file to ensure that the message bus is enabled and connected to STF message bus routers
   - enable-stf.yaml - environment file to ensure defaults are configured correctly
   - stf-connectors.yaml - environment file to define the connection to STF

************************************************* copy box **********************************************************
openstack overcloud deploy
--templates /usr/share/openstack-tripleo-heat-templates \
  --environment-file /usr/share/openstack-tripleo-heat-templates/environments/metrics/ceilometer-write-qdr.yaml \
  --environment-file /usr/share/openstack-tripleo-heat-templates/environments/metrics/qdr-edge-only.yaml \
  --environment-file /home/stack/enable-stf.yaml \
  --environment-file /home/stack/stf-connectors.yaml
************************************************ copy box ***********************************************************

*Proposed text:*

3. Validate that the following files are passed to RHOSP director "openstack overcloud deploy" command, as seen below,
to configure:
   - ceilometer-write-qdr.yaml - ensure that Ceilometer telemetry and events are sent to STF
   - qdr-edge-only.yaml - file to ensure that the message bus is enabled and connected to STF message bus routers
   - enable-stf.yaml - environment file to ensure defaults are configured correctly
   - stf-connectors.yaml - environment file to define the connection to STF

4. Deploy the RHOSP overcloud:
************************************************* copy box **********************************************************
openstack overcloud deploy
--templates /usr/share/openstack-tripleo-heat-templates \
  --environment-file /usr/share/openstack-tripleo-heat-templates/environments/metrics/ceilometer-write-qdr.yaml \
  --environment-file /usr/share/openstack-tripleo-heat-templates/environments/metrics/qdr-edge-only.yaml \
  --environment-file /home/stack/enable-stf.yaml \
  --environment-file /home/stack/stf-connectors.yaml
************************************************ copy box ***********************************************************

Change

Add the following files to your RHOSP director deployment to configure data collection and AMQ Interconnect:

To

Add the following files to your RHOSP director deployment to enable data collection and AMQ Interconnect:

I think the problem I have with changing the syntax here to what you've proposed, is that it's unlikely someone would run this command exactly as is (outside of a development environment) because there will be other environment files and possibly other openstack CLI command arguments passed to a cloud deployment. That is why we have the other <parameter> sections in here.

Michael, maybe you can ask if this is the best style we should provide here, or if there is something a bit more clear we could do with this section?

Writers have boiler-plate text for the deployment step in our style guide:

In this case maybe we can add the deployment step as the final step in the 4.1.3 procedure, rather than having it as a separate procedure. It looks like the first two steps in the current 4.1.4 procedure are the same login steps from 4.1.3 so they might not be needed and step 3 in 4.1.3 could instead be presented as callouts from the deployment command, explaining what the file is for. For example:

=================
. Add your data collection and AMQ Interconnect environment files to the stack with your other environment files and deploy the overcloud:

(undercloud)$ openstack overcloud deploy --templates \
 -e [your environment files] \
 -e /usr/share/openstack-tripleo-heat-templates/environments/metrics/ceilometer-write-qdr.yaml \ <1>
 -e /usr/share/openstack-tripleo-heat-templates/environments/metrics/qdr-edge-only.yaml \ <2>
 -e /home/stack/enable-stf.yaml \ <3>
 -e /home/stack/stf-connectors.yaml <4>

<1> Include the `ceilometer-write-qdr.yaml` file to ensure that Ceilometer telemetry and events are sent to STF.
<2> Include the `qdr-edge-only.yaml` file to ensure that the message bus is enabled and connected to STF message bus routers.
<3> Include the `enable-stf.yaml` environment file to ensure that the defaults are configured correctly.
<4> Include the `stf-connectors.yaml` environment file to define the connection to STF.
================

https://docs.engineering.redhat.com/display/RHOSPDOC/Style+Guide+for+RHOSP#StyleGuideforRHOSP-Redeployment_steps

https://docs.engineering.redhat.com/display/RHOSPDOC/Style+Guide+for+RHOSP#StyleGuideforRHOSP-Command_prompt.

https://docs.engineering.redhat.com/display/RHOSPDOC/Style+Guide+for+RHOSP#StyleGuideforRHOSP-Undercloud_commands

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory (Release for Service Telemetry Framework 1.5.2), and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHEA-2023:3785