Fix issues reported by asciidoctor-dita-vale (Managing Configurations Puppet) (#4189)

aneta-petrova · maximiliankolb · web-flow · commit 38e49e7d97b4 · 2025-08-27T21:09:32.000+02:00
* Convert xrefs

* Drop discrete headings

* Resolve errors in additional resources

Some are not relevant and can be dropped, others need to be updated.

* Resolve errors around free floating paras

Procedures can't contain free paragraphs.

* Move alternative Puppet install note to intro

---------

Co-authored-by: Maximilian Kolb &lt;mail@maximilian-kolb.de&gt;
diff --git a/guides/common/modules/con_how-puppet-integrates-with-project.adoc b/guides/common/modules/con_how-puppet-integrates-with-project.adoc
@@ -19,24 +19,10 @@ The Puppet agent evaluates the system state on the host.
 If the Puppet agent finds differences, known as _drifts_, between the _desired state_ defined in the _catalog_ and the actual state, it enforces correction of the state of the host.
 The Puppet agent then reports correction results back to the Puppet server, which reports them to {Project}.
 
-.Puppet modules
-The _desired state_ of a host is defined in a _catalog_.
-The _catalog_ is compiled from Puppet manifests of one or more Puppet modules assigned to the host.
-A Puppet module is a collection of classes, manifests, resources, files, and templates.
-The Puppet modules work as components of host configuration definitions.
-
-.Smart Class parameters
-You can override parameters of a Puppet module by using Smart Class parameters if the module supports the use of parameters.
-You can define the parameters in your {Project} as _key-value_ pairs, which behave similar to host parameters or Ansible variables.
-
-.Puppet environments
-You can also create multiple Puppet environments to control versions of configuration definitions or to manage variants of the definitions, and to test the definitions before you deploy them on production.
-
-.High-level integration steps
 Puppet integration with {Project} involves the following high-level steps:
 
 ifdef::katello,orcharhino,satellite[]
-. xref:Enabling_Puppet_Integration_{context}[Enable Puppet integration].
+. xref:common/modules/proc_enabling-puppet.adoc#Enabling_Puppet_Integration_{context}[Enable Puppet integration].
 endif::[]
 ifdef::katello,satellite,orcharhino[]
 . Import Puppet agent packages into {Project}.
@@ -49,13 +35,17 @@ by syncing repositories in custom products
 endif::[]
 and by using {ContentManagementDocURL}Managing_Activation_Keys_content-management[activation keys] and {ContentManagementDocURL}Managing_Content_Views_content-management[content views].
 endif::[]
-. Install Puppet agent on hosts during xref:Installing_and_Configuring_Puppet_Agent_during_Host_Provisioning_{context}[provisioning], xref:installing-and-configuring-puppet-agent-during-host-registration_{context}[registration], xref:Installing_and_Configuring_Puppet_Agent_Manually_{context}[manually], or by remote job execution.
+. Install Puppet agent on hosts during xref:common/modules/proc_installing-and-configuring-puppet-agent-manually.adoc#Installing_and_Configuring_Puppet_Agent_during_Host_Provisioning_{context}[provisioning], xref:common/modules/proc_installing-and-configuring-puppet-agent-during-host-registration.adoc#installing-and-configuring-puppet-agent-during-host-registration_{context}[registration], xref:common/modules/proc_installing-and-configuring-puppet-agent-manually.adoc#Installing_and_Configuring_Puppet_Agent_Manually_{context}[manually], or by remote job execution.
 
-.Additional resources
-ifdef::katello,satellite,orcharhino[]
-* {ContentManagementDocURL}[{ContentManagementDocTitle}]
-endif::[]
-* {ManagingHostsDocURL}registering-hosts-and-setting-up-host-integration_managing-hosts[Registering hosts and setting up host integration] in _{ManagingHostsDocTitle}_
-* {ManagingHostsDocURL}Configuring_and_Setting_Up_Remote_Jobs_managing-hosts[Configuring and setting up remote jobs] in _{ManagingHostsDocTitle}_
+Puppet modules::
+The _desired state_ of a host is defined in a _catalog_.
+The _catalog_ is compiled from Puppet manifests of one or more Puppet modules assigned to the host.
+A Puppet module is a collection of classes, manifests, resources, files, and templates.
+The Puppet modules work as components of host configuration definitions.
 
-The following procedures outline how to use a Puppet module to install, configure, and manage the _ntp_ service to provide examples.
+Smart Class parameters::
+You can override parameters of a Puppet module by using Smart Class parameters if the module supports the use of parameters.
+You can define the parameters in your {Project} as _key-value_ pairs, which behave similar to host parameters or Ansible variables.
+
+Puppet environments::
+You can also create multiple Puppet environments to control versions of configuration definitions or to manage variants of the definitions, and to test the definitions before you deploy them on production.
diff --git a/guides/common/modules/con_introducing-configuration-management-by-using-puppet.adoc b/guides/common/modules/con_introducing-configuration-management-by-using-puppet.adoc
@@ -11,4 +11,4 @@ At the same time, it decreases your configuration effort as Puppet makes it easy
 
 .Additional resources
 * https://puppet.com/docs/puppet/[Open Source Puppet documentation]
-* https://forge.puppet.com/[Puppet Forge] -- a repository of pre-built Puppet modules
+* https://forge.puppet.com/[Puppet Forge]
diff --git a/guides/common/modules/proc_assigning-a-puppet-class-to-an-individual-host.adoc b/guides/common/modules/proc_assigning-a-puppet-class-to-an-individual-host.adoc
@@ -67,5 +67,5 @@ server 1.de.pool.ntp.org
 server 2.de.pool.ntp.org
 server 3.de.pool.ntp.org
 ----
-
++
 You now have a working ntp module which you can add to a host or group of hosts to roll out your ntp configuration automatically.
diff --git a/guides/common/modules/proc_creating-a-custom-puppet-environment.adoc b/guides/common/modules/proc_creating-a-custom-puppet-environment.adoc
@@ -12,5 +12,3 @@ You can create a Puppet environment within your {Project}.
 . Optional: Set a location context.
 . Optional: Set an organization context.
 . Click *Submit* to create the Puppet environment.
-
-Note that before you run an import of Puppet modules into {Project}, the environment must already exist as the folder `/etc/puppetlabs/code/environments/_example_environment_` on the Puppet server and contain installed Puppet modules.
diff --git a/guides/common/modules/proc_importing-puppet-classes-and-environments.adoc b/guides/common/modules/proc_importing-puppet-classes-and-environments.adoc
@@ -7,6 +7,7 @@ Import Puppet classes and environments from the installed Puppet modules to {Pro
 
 .Prerequisites
 * Ensure to select *Any Organization* and *Any Location* as context, otherwise the import might fail.
+* Before you run an import of Puppet modules into {Project}, the environment must already exist as the folder `/etc/puppetlabs/code/environments/_example_environment_` on the Puppet server and contain installed Puppet modules.
 
 .Procedure
 . In the {ProjectWebUI}, navigate to *Configure* > *Puppet ENC* > *Classes* or *Configure* > *Puppet ENC* > *Environments*.
diff --git a/guides/common/modules/proc_installing-a-puppet-module.adoc b/guides/common/modules/proc_installing-a-puppet-module.adoc
@@ -7,6 +7,12 @@ You can install a pre-built Puppet module from the Puppet Forge.
 The Puppet Forge is a repository that provides Puppet modules contributed by the community.
 Puppet modules flagged as _supported_ are officially supported and tested by Puppet Inc.
 
+[NOTE]
+====
+An alternative way to install a Puppet module is to copy a folder containing the Puppet module to the module path as mentioned below.
+Ensure to resolve its dependencies manually.
+====
+
 This example shows how to add the _ntp module_ to hosts.
 
 .Procedure
@@ -33,6 +39,3 @@ Notice: Installing -- do not interrupt ...
 |-| puppetlabs-ntp (v8.3.0)
   |-- puppetlabs-stdlib (v4.25.1) [/etc/puppetlabs/code/environments/production/modules]
 ----
-
-An alternative way to install a Puppet module is to copy a folder containing the Puppet module to the module path as mentioned above.
-Ensure to resolve its dependencies manually.
diff --git a/guides/common/modules/proc_installing-and-configuring-puppet-agent-during-host-provisioning.adoc b/guides/common/modules/proc_installing-and-configuring-puppet-agent-during-host-provisioning.adoc
@@ -8,7 +8,7 @@ A configured Puppet agent is required on the host for Puppet integration with yo
 
 .Prerequisites
 * Puppet must be enabled in your {Project}.
-For more information, see xref:Enabling_Puppet_Integration_{context}[].
+For more information, see xref:common/modules/proc_enabling-puppet.adoc#Enabling_Puppet_Integration_{context}[].
 ifdef::satellite[]
 include::snip_prerequisite-project-client-repository-ak.adoc[]
 * You have an activation key.
diff --git a/guides/common/modules/proc_installing-and-configuring-puppet-agent-during-host-registration.adoc b/guides/common/modules/proc_installing-and-configuring-puppet-agent-during-host-registration.adoc
@@ -12,7 +12,7 @@ endif::[]
 .Prerequisites
 * Puppet must be enabled in your {Project}.
 ifdef::managing-configurations-puppet[]
-For more information, see xref:Enabling_Puppet_Integration_{context}[].
+For more information, see xref:common/modules/proc_enabling-puppet.adoc#Enabling_Puppet_Integration_{context}[].
 endif::[]
 ifndef::managing-configurations-puppet[]
 For more information, see {ManagingConfigurationsPuppetDocURL}Enabling_Puppet_Integration_managing-configurations-puppet[Enabling Puppet Integration with {Project}] in _{ManagingConfigurationsPuppetDocTitle}_.
@@ -71,7 +71,7 @@ ifndef::katello,orcharhino,satellite[]
 . Navigate to *Hosts* > *Register Host* and register your host.
 endif::[]
 ifeval::[{context} == "managing-hosts"]
-For more information, see xref:Registering_Hosts_by_Using_Global_Registration_{context}[].
+For more information, see xref:common/modules/proc_registering-hosts-by-using-global-registration.adoc#Registering_Hosts_by_Using_Global_Registration_{context}[].
 endif::[]
 ifeval::[{context} != "managing-hosts"]
 For more information, see {ManagingHostsDocURL}Registering_Hosts_by_Using_Global_Registration_managing-hosts[Registering hosts by using global registration] in _{ManagingHostsDocTitle}_.
diff --git a/guides/common/modules/proc_installing-and-configuring-puppet-agent-manually.adoc b/guides/common/modules/proc_installing-and-configuring-puppet-agent-manually.adoc
@@ -12,7 +12,7 @@ endif::[]
 .Prerequisites
 * Puppet must be enabled in your {Project}.
 ifdef::managing-configurations-puppet[]
-For more information, see xref:Enabling_Puppet_Integration_{context}[].
+For more information, see xref:common/modules/proc_enabling-puppet.adoc#Enabling_Puppet_Integration_{context}[].
 endif::[]
 ifndef::managing-configurations-puppet[]
 For more information, see {ManagingConfigurationsPuppetDocURL}Enabling_Puppet_Integration_managing-configurations-puppet[Enabling Puppet Integration with {Project}] in _{ManagingConfigurationsPuppetDocTitle}_.
diff --git a/guides/common/modules/proc_running-puppet-once-using-ssh.adoc b/guides/common/modules/proc_running-puppet-once-using-ssh.adoc
@@ -6,9 +6,9 @@
 Assign the proper job template to the _Run Puppet Once_ feature to run Puppet on hosts.
 
 .Procedure
-. In the {ProjectWebUI}, navigate to *Administer* > *Remote Execution Features*.
-. Select the `puppet_run_host` remote execution feature.
-. Assign the `Run Puppet Once {endash} SSH Default` job template.
-
-Run Puppet on hosts by running a job and selecting category `Puppet` and template `Run Puppet Once - SSH Default`.
+. Edit remote execution settings on {Project}:
+.. In the {ProjectWebUI}, navigate to *Administer* > *Remote Execution Features*.
+.. Select the `puppet_run_host` remote execution feature.
+.. Assign the `Run Puppet Once {endash} SSH Default` job template.
+. To run Puppet on hosts, execute a remote job and select category `Puppet` and template `Run Puppet Once - SSH Default`.
 Alternatively, click *Run Puppet Once* in the *Schedule Remote Job* drop down menu on the host details page.
diff --git a/guides/common/modules/proc_setting-the-global-out-of-sync-interval.adoc b/guides/common/modules/proc_setting-the-global-out-of-sync-interval.adoc
@@ -8,4 +8,4 @@
 . On the *General* tab, edit *Out of sync interval*.
 Set a duration, in minutes, after which hosts are considered to be out of sync.
 +
-You can also override this interval on xref:overriding-out-of-sync-interval-for-a-host-group_{context}[host groups] or xref:overriding-out-of-sync-interval-for-an-individual-host_{context}[individual hosts] by adding the `outofsync_interval` parameter.
+You can also override this interval on xref:common/modules/proc_overriding-out-of-sync-interval-for-a-host-group.adoc#overriding-out-of-sync-interval-for-a-host-group_{context}[host groups] or xref:common/modules/proc_overriding-out-of-sync-interval-for-an-individual-host.adoc#overriding-out-of-sync-interval-for-an-individual-host_{context}[individual hosts] by adding the `outofsync_interval` parameter.
diff --git a/guides/common/modules/ref_performing-configuration-management.adoc b/guides/common/modules/ref_performing-configuration-management.adoc
@@ -18,4 +18,4 @@ For more information, see {AdministeringDocURL}Monitoring_Resources_admin[Monito
 For more information, see {AdministeringDocURL}Configuring_Email_Notification_Preferences_admin[Configuring Email Notification Preferences] in _{AdministeringDocTitle}_.
 
 After assigning Puppet classes or config groups, {Project} runs configuration management automatically in the configured intervals to enforce Puppet configuration on your hosts, or you can initiate it manually on demand with the *Run Puppet Once* feature.
-For more information, see xref:running-puppet-once-using-ssh_{context}[].
+For more information, see xref:common/modules/proc_running-puppet-once-using-ssh.adoc#running-puppet-once-using-ssh_{context}[].
