Updating add compiler docs to show optional params

documentation/add_compiler.md

@@ -1,33 +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
 
-Prepare to run the plan using a params.json file such as this one:
+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
 {
-  "avail_group_letter": "A",
   "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",
+  "primary_host":  "pe-xl-core-0.lab1.puppet.vm"
 }
 ```
 
-See the [install](install.md#reference-architectures) documentation for a list of supported architectures.
-
-
-## Running the add_compiler plan
+## 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 is be installed. The compiler agent's certificate is be regenerated to include required data with `peadm::subplans::component_install`. Puppet agent will run on the following components
+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 be 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 been seen used 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 each 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`       | This will by default 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, the value of this parameters by default be 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.
 
-    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.
 
-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>