feat(documentation): add instructions for converting compilers to legacy

This commit introduces a new section in the `convert.md` documentation. It provides instructions on how to convert compilers to legacy compilers for Puppet Enterprise installations using puppetlabs-peadm version 3.21 or later, as well as for versions prior to 3.21. The new section includes specific commands to run and references to other relevant documentation.

documentation/convert.md

@@ -15,18 +15,32 @@ Prepare to run the plan against all servers in the PE infrastructure, using a pa
     "pe-xl-compiler-1.lab1.puppet.vm"
   ],
 
-  "compiler_pool_address": "puppet.lab1.puppet.vm",
+  "compiler_pool_address": "puppet.lab1.puppet.vm"
 }
 ```
 
-See the [install](install.md#reference-architectures) documentation for a list of supported architectures. Note that for convert, *all infrastructure being converted must already be functional*; you cannot use convert to add new systems to the infrastructure, nor can you use it to change your architecture.
+See the [install](install.md#reference-architectures) documentation for a list of supported architectures. Note that for convert, _all infrastructure being converted must already be functional_; you cannot use convert to add new systems to the infrastructure, nor can you use it to change your architecture.
 
 ```
-bolt plan run peadm::convert --params @params.json 
+bolt plan run peadm::convert --params @params.json
 ```
 
 ## Retry or resume plan
 
 This plan is broken down into steps. Normally, the plan runs through all the steps from start to finish. The name of each step is displayed during the plan run, as the step begins.
 
 The `begin_at_step` parameter can be used to facilitate re-running this plan after a failed attempt, skipping past any steps that already completed successfully on the first try and picking up again at the step specified. The step name to resume at can be read from the previous run logs. A full list of available values for this parameter can be viewed by running `bolt plan show peadm::convert`.
+
+## Convert compilers to legacy
+
+### Puppet Enterprise installed with puppetlabs-peadm version 3.21 or later
+
+To convert compilers to legacy compilers use the `peadm::convert_compiler_to_legacy` plan. This plan will create the needed Node group and Classifier rules to make the compilers legacy. Also will add certificate extensions to those nodes.
+
+```shell
+bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com
+```
+
+### Puppet Enterprise installed with puppetlabs-peadm version prior to 3.21
+
+Follow Steps 1 to 3 in the [Upgrade Puppet Enterprise with legacy compilers](upgrade_with_legacy_compilers.md) documentation.

documentation/upgrade_with_legacy_compilers.md

@@ -0,0 +1,45 @@
+# Upgrade Puppet Enterprise with legacy compilers
+
+## What is a legacy compiler and a current compiler
+
+As a legacy compiler we refer to a compiler that doesn't have PuppetDB. And a current Compiler is a compiler that has PuppetDB. By default, latest versions of Puppet enterprise comes with compilers that have PuppetDB.If your primary server and compilers are connected with high-latency links or congested network segments, you might experience better PuppetDB performance with legacy compilers.
+
+## Who is this documentation for
+
+For those users that have installed Puppet Enterprise with puppetlabs-peadm prior version 3.21 and manually converted their existing complilers (all of the or at least 1) to legacy compilers.
+
+## Who is this documentation not for
+
+For those users that have installed Puppet Enterprise with PEADM with 3.21 version or later, there is no need to follow this documentation. The install process will automatically have created the necessary configurations for you and you can use the `peadm::convert_compiler_to_legacy` plan if you need a legacy compiler. example:
+
+```shell
+bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com
+```
+
+## How to upgrade Puppet Enterprise with legacy compilers
+
+### 1. Revert changes to the legacy compilers nodes
+
+Usually users pin the nodes in the Pe Master Node Group and then manually removing PuppetDB from compilers nodes. To revert this changes go to your Puppet Enterprise console and unpin the compilers nodes from the Group.
+
+### 2. Update certificate extensions for NON legacy compilers
+
+If you have NON legacy compilers in your infrastructure, you have to add a certificate extension to them that recognizes them as NON legacy compilers. To do this, execute the following plan:
+
+```shell
+bolt plan run peadm::update_compiler_extensions primary_host=primary.example.com compilers_hosts=compiler1.example.com,compiler2.example.com
+```
+
+### 3. Use the convert legacy compiler plan
+
+Now that we have unpinned the compilers nodes from the PE Master node group, execute the following plan to convert your needed compilers to legacy compilers:
+
+```shell
+bolt plan run peadm::convert_compiler_to_legacy legacy_hosts=compiler1.example.com,compiler2.example.com primary_host=primary.example.com
+```
+
+The above will create the needed Node group and Classifier rules to make the compilers legacy. Also will add certificate extensions to those nodes.
+
+### 4. Upgrade Puppet Enterprise
+
+After you have completed the above steps, you can proceed with the upgrade of Puppet Enterprise as usual using the puppetlabs-peadm module. There is no need to do the above ever again.