(PE-37235) Verify and update documentation on add_compiler (#429)

* PE-37235 Verify and update documentation on add_compiler if needed and its experimental status

* @cathal41
PE-37235 Verify and update documentation on add_compiler - wording updates

* Update plans/add_compiler.pp

Co-authored-by: Dimitri Tischenko <[email protected]>

* Update documentation/add_compiler.md

Co-authored-by: Dimitri Tischenko <[email protected]>

* Update documentation/add_compiler.md

Co-authored-by: Dimitri Tischenko <[email protected]>

* Update documentation/add_compiler.md

Co-authored-by: Dimitri Tischenko <[email protected]>

* Update documentation/add_compiler.md

Co-authored-by: Dimitri Tischenko <[email protected]>

* Update documentation/add_compiler.md

Co-authored-by: Dimitri Tischenko <[email protected]>

* Updating add compiler docs to show optional params

* Updating docs with text corrections

---------

Co-authored-by: Dimitri Tischenko <[email protected]>
Co-authored-by: Neil Anderson <[email protected]>

Author: 3 people

documentation/add_compiler.md

@@ -0,0 +1,64 @@
+# Add Compiler
+
+- [Add Compiler](#Add-Compiler)
+  - [Introduction](#Introduction)
+  - [Add a compiler to an existing PE cluster](#Add-a-compiler-to-an-existing-PE-cluster)
+  - [Running the `add_compiler` plan](#running-the-add_compiler-plan)
+  - [Optional Parameters](#optional-parameters)
+
+
+## Introduction
+
+The `peadm::add_compiler` plan can be used to add a new compiler to a PE cluster or replace an existing one with new configuration.
+
+
+## Add a compiler to an existing PE cluster
+
+As seen in the example below, this is the minimal parameters required to add a compiler to an existing PE cluster. These can be passed as command line variables to the plan, or in this case added to a params.json file. 
+
+```json
+{
+  "compiler_host": "pe-xl-compiler-0.lab1.puppet.vm",
+  "primary_host":  "pe-xl-core-0.lab1.puppet.vm"
+}
+```
+
+## Running the `add_compiler` plan
+```
+bolt plan run peadm::add_compiler --params @params.json 
+```
+
+This command will retrieve the current PEADM configuration to determine the setup rules needed for a compiler's secondary PuppetDB instances. The plan will configure the primary with appropriate rules for allowing access from the new compiler. On the primary, the `puppet` service is stopped and the `pe-postgresql` service is reloaded. If required, a puppet agent will be installed on the new compiler host. The compiler agent's certificate is regenerated to include data required by the  `peadm::subplans::component_install` plan. A subsequent Puppet agent run will happen on the following components.
+* _\<compiler-host\>_
+* _\<primary_postgresql_host\>_
+* _\<replica host\>_
+* _\<primary_postgresql_host\>_
+
+ The `puppet` service is then restarted.
+
+
+## Optional Parameters
+
+As well as `compiler_host` and `primary_host`, the `add_compiler` plan has a number of optional parameters. These can be viewed in the following params example.
+
+```json
+{
+  "avail_group_letter": "B",
+  "compiler_host": "pe-xl-compiler-0.lab1.puppet.vm",
+  "dns_alt_names": [ "puppet", "puppet.lab1.puppet.vm" ],
+  "primary_host":  "pe-xl-core-0.lab1.puppet.vm",
+  "primary_postgresql_host": "pe-psql-6251cd-0.us-west1-a.c.slice-cody.internal"
+}
+```
+
+Please note, the optional parameters and values of the plan are as follows.
+
+<!-- table -->
+| Parameter                | Default value | Description                                      |
+|--------------------------|---------------|--------------------------------------------------|
+| `avail_group_letter`     | `A`           | By default, each compiler will be added to the primary group A.        |
+| `dns_alt_names`          | `undef`       |                                                  |
+| `primary_postgresql_host`| `undef`       | By default, this will pre-populate to the required value depending if your architecture contains HA and or external databases.                                    |
+
+For more information around adding compilers to your infrastructure [Expanding Your Deployment](expanding.md#adding-compilers-with-peadmadd_compiler)
+

documentation/expanding.md

@@ -101,21 +101,21 @@ The Standard deployment architecture is the only deployment architecture of the
 
 ### Adding Compilers to Standard and Large without disaster recovery
 
-The command invocation is identical when adding Compilers to a Standard or Large deployment architecture if disaster recovery (DR) is not enabled and a Replica Puppet server has not been provisioned. Take note of the values for `avail_group_letter` and `primary_postgresql_host`, in this **no DR**  scenario, the value of these parameters will always be set to **A** and the FQDN of the Primary Puppet server.
+The command invocation is identical when adding Compilers to a Standard or Large deployment architecture if disaster recovery (DR) is not enabled and a replica Puppet server has not been provisioned. Take note that `avail_group_letter` is not required in this **no DR**  scenario. By default, the value of this parameter is set to **A**.
 
-    bolt plan run peadm::add_compiler primary_host=<primary-server-fqdn> compiler_host=<new-compiler-fqdn> avail_group_letter=A primary_postgresql_host=<primary-server-fqdn>
+    bolt plan run peadm::add_compiler primary_host=<primary-server-fqdn> compiler_host=<new-compiler-fqdn>
 
 ### Adding Compilers to Extra Large without disaster recovery
 
-When adding a Compiler to a deployment which has adopted the Extra Large deployment architecture in a **no DR** scenario, the only difference is that the `primary_postgresql_host` changes to be the value of the Primary PE-PostgreSQL server as opposed to the Primary Puppet server.
+When adding a compiler to a deployment which has adopted the Extra Large deployment architecture in a **no DR** scenario, the only difference is that the `primary_postgresql_host` changes to the value of the primary PE-PostgreSQL server as opposed to the Primary Puppet server.
 
-    bolt plan run peadm::add_compiler primary_host=<primary-server-fqdn> compiler_host=<new-compiler-fqdn> avail_group_letter=A primary_postgresql_host=<primary-postgresql-server-fqdn>
+    bolt plan run peadm::add_compiler primary_host=<primary-server-fqdn> compiler_host=<new-compiler-fqdn>
 
 ### Adding Compilers to Standard and Large when disaster recovery has been enabled
 
-As was described in the section documenting [peadm::add_replica](#enable-disaster-recovery-and-add-a-replica-with-peadmadd_replica), when disaster recovery (DR) is enabled and a Replica provisioned, PEADM creates a second availability group, **B**. You must take this second availability group into consideration when adding new compilers and ensure you are assigning appropriate values for the group the Compiler is targeted for. It is a good idea to keep these two availability groups populated with an equal quantity of Compilers. Besides the value of `avail_group_letter` being dependent on which group the new Compiler is targeted towards, the value of `primary_postgresql_host` will also vary.
+As was described in the section documenting [peadm::add_replica](#enable-disaster-recovery-and-add-a-replica-with-peadmadd_replica), when disaster recovery (DR) is enabled and a Replica provisioned, PEADM creates a second availability group, **B**. You must take this second availability group into consideration when adding new compilers and ensure you are assigning appropriate values for the group the compiler is targeted for. It is a good idea to keep these two availability groups populated with an equal quantity of compilers. Besides the value of `avail_group_letter` being dependent on which group the new compiler is targeted towards, the value of `primary_postgresql_host` will also vary.
 
-The name of the `primary_postgresql_host` parameter can be confusing, it is **NOT** always equal to the Primary Puppet server or Primary PE-PostgreSQL server, it can also be equal to the Replica Puppet server or Replica PE-PostgreSQL server. It should be set to the server which is a member of the Compiler's target availability group. The easiest way to determine this value is to first run the `peadm::get_peadm_config` task and source the value from its output. In the **Example** section the value to use when targeting the **B** group is `pe-server-59ab63-1.us-west1-b.c.slice-cody.internal`. You'll find the value at `role-letter.server.B`.
+The name of the `primary_postgresql_host` parameter can be confusing, it is **NOT** always equal to the Primary Puppet server or Primary PE-PostgreSQL server, it can also be equal to the replica Puppet server or replica PE-PostgreSQL server. It should be set to the server which is a member of the compiler's target availability group. In most cases this will be handled behind the scenes and not be required to be worked out by the user. The easiest way to determine this value is to first run the `peadm::get_peadm_config` task and source the value from its output. In the **Example** section the value to use when targeting the **B** group is `pe-server-59ab63-1.us-west1-b.c.slice-cody.internal`. You'll find the value at `role-letter.server.B`.
 
     bolt plan run peadm::get_peadm_config --targets <primary-server-fqdn> 
     bolt plan run peadm::add_compiler primary_host=<primary-server-fqdn> compiler_host=<new-compiler-fqdn> avail_group_letter=<new-compiler-target-group> primary_postgresql_host=<target-group-server-fqdn>
@@ -161,7 +161,7 @@ The name of the `primary_postgresql_host` parameter can be confusing, it is **NO
     Successful on 1 target: pe-server-59ab63-0.us-west1-a.c.slice-cody.internal
     Ran on 1 target in 2.46 sec
 
-### Adding compilers to Extra Large when disaster recovery has been enabled
+### Adding Compilers to Extra Large when disaster recovery has been enabled
 
 Adding a Compiler to a deployment which has adopted the Extra Large deployment architecture with disaster recovery (DR) enabled is similar to Standard and Large but the value of `primary_postgresql_host` will no longer correspond to the Primary or Replica Puppet server since PuppetDB databases are now hosted externally. In the **Example** section, the value to use when targeting the **A** group is `pe-psql-65e03f-0.us-west1-a.c.slice-cody.internal`. You'll find the value at `role-letter.postgresql.A`.
 

plans/add_compiler.pp

@@ -103,16 +103,16 @@
     path        => '/etc/puppetlabs/puppet/hiera.yaml'
   )
 
-  # On <compiler-host>, run the puppet agent
+  # On <compiler-host>, run puppet agent
   run_task('peadm::puppet_runonce', $compiler_target)
 
-  # On <primary_postgresql_host> run the puppet agent
+  # On <primary_postgresql_host>, run puppet agent
   run_task('peadm::puppet_runonce', $primary_postgresql_target)
 
-  # On replica puppetdb run the puppet agent
+  # On <replica_puppetdb_target>, run puppet agent
   run_task('peadm::puppet_runonce', $replica_puppetdb_target)
 
-  # On <primary_postgresql_host> start puppet.service
+  # On <primary_postgresql_host>, start puppet.service
   run_command('systemctl start puppet.service', peadm::flatten_compact([
         $primary_postgresql_target,
         $replica_puppetdb_target,