Adding support for legacy compilers (#448)

README.md

@@ -9,7 +9,7 @@ You can use PEADM to deploy and manage PE installations for standard, large, and
 #### Table of contents
 
 - [Puppet Enterprise Administration Module (PEADM)](#puppet-enterprise-pe-administration-adm-module)
-      - [Table of contents](#table-of-contents)
+  - [Table of contents](#table-of-contents)
   - [Support](#support)
   - [Overview](#overview)
     - [What PEADM affects](#what-peadm-affects)
@@ -24,14 +24,14 @@ You can use PEADM to deploy and manage PE installations for standard, large, and
 
 PEADM is a supported PE module. If you are a PE customer with the standard or premium support service, you can contact [Support](https://portal.perforce.com/s/topic/0TO4X000000DbNgWAK/puppet) or your Technical Account Manager for assistance.
 
-
 ## Overview
 
 This is the standard workflow for installing PEADM.
 
 1. [Install Bolt](https://www.puppet.com/docs/bolt/latest/bolt_installing) on a jump host.
 2. To create a Bolt project that includes the PEADM module, run:</br>`mkdir <YOUR_PROJECT> && cd <YOUR_PROJECT> && bolt project init <YOUR_PROJECT> --modules puppetlabs-peadm`
 3. In the Bolt project directory, update the `inventory.yaml` file with connection information for the servers you plan to use for hosting PE infrastructure. For example:
+
 ```yaml
 ---
 groups:
@@ -55,56 +55,55 @@ groups:
 
 ### What PEADM affects
 
-* The `peadm::install` plan adds a number of custom original identifier (OID) trusted facts to the certificates of deployed PE infrastructure nodes. These trusted facts are used by PEADM plans to identify nodes that host PE infrastructure components.
-* Depending on the scale of your architecture, up to four node groups may be created to configure `puppet_enterprise` class parameters for the following PE infrastructure components: 
-    * The primary server
-    * The primary server replica
-    * PostgreSQL nodes (database servers)
-    * Compilers (compiler hosts are designated as belonging to availability group A or B)
+- The `peadm::install` plan adds a number of custom original identifier (OID) trusted facts to the certificates of deployed PE infrastructure nodes. These trusted facts are used by PEADM plans to identify nodes that host PE infrastructure components.
+- Depending on the scale of your architecture, up to four node groups may be created to configure `puppet_enterprise` class parameters for the following PE infrastructure components:
+  - The primary server
+  - The primary server replica
+  - PostgreSQL nodes (database servers)
+  - Compilers (compiler hosts are designated as belonging to availability group A or B)
 
 ### What PEADM does not affect
 
-* PEADM does not impact regular PE operations. After using it to deploy a new PE installation or upgrade an existing one, PEADM is not required until you want to use it to upgrade PE or expand your installation.
-* Using PEADM to install PE or upgrade PE does not prevent you from using documented PE procedures such as setting up disaster recovery or performing a manual upgrade.
+- PEADM does not impact regular PE operations. After using it to deploy a new PE installation or upgrade an existing one, PEADM is not required until you want to use it to upgrade PE or expand your installation.
+- Using PEADM to install PE or upgrade PE does not prevent you from using documented PE procedures such as setting up disaster recovery or performing a manual upgrade.
 
 ### Requirements
 
-* PEADM is compatible with Puppet Enterprise 2019.8.1 or newer versions.
-* PEADM requires [Bolt](https://www.puppet.com/docs/bolt/latest/bolt_installing) version 3.17.0 or newer and works on operating systems supported by Bolt.  
-**Note:** You can use PEADM to install Puppet Enterprise (PE) onto any operating system platform that is supported by the specific PE version you want to install. To review operating system platforms supported by specific PE versions, refer to the PE documentation.
-* To successfully convert your current PE installation to a PEADM-managed installation, ensure that the PE setting for editing classifier configuration data is enabled. This setting is enabled by default on new PE installations, but it could be disabled if the relevant configuration was removed from your global hiera.yaml file. See the [PE docs](https://www.puppet.com/docs/pe/latest/config_console.html#enable_console_configuration_data) for more information.
+- PEADM is compatible with Puppet Enterprise 2019.8.1 or newer versions.
+- PEADM requires [Bolt](https://www.puppet.com/docs/bolt/latest/bolt_installing) version 3.17.0 or newer and works on operating systems supported by Bolt.  
+  **Note:** You can use PEADM to install Puppet Enterprise (PE) onto any operating system platform that is supported by the specific PE version you want to install. To review operating system platforms supported by specific PE versions, refer to the PE documentation.
+- To successfully convert your current PE installation to a PEADM-managed installation, ensure that the PE setting for editing classifier configuration data is enabled. This setting is enabled by default on new PE installations, but it could be disabled if the relevant configuration was removed from your global hiera.yaml file. See the [PE docs](https://www.puppet.com/docs/pe/latest/config_console.html#enable_console_configuration_data) for more information.
 
 ## Usage
 
 For instructions on using PEADM plans, see the following PEADM docs:
 
-* [Install](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/install.md)
-* [Upgrade](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/upgrade.md)
-* [Convert](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/convert.md)
-* [Status](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/status.md)
+- [Install](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/install.md)
+- [Upgrade](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/upgrade.md)
+- [Convert](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/convert.md)
+- [Status](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/status.md)
 
 ## Reference
 
 To understand which architecture is right for you, see the following information on the Puppet documentation site:
 
-* [PE architectures](https://puppet.com/docs/pe/latest/choosing_an_architecture.html)
-* [PE multi-region reference architectures](https://puppet.com/docs/patterns-and-tactics/latest/reference-architectures/pe-multi-region-reference-architectures.html)
-
+- [PE architectures](https://puppet.com/docs/pe/latest/choosing_an_architecture.html)
+- [PE multi-region reference architectures](https://puppet.com/docs/patterns-and-tactics/latest/reference-architectures/pe-multi-region-reference-architectures.html)
 
 To learn more about the PEADM module and its uses, see the following PEADM docs:
 
-* [Recovery procedures](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/recovery.md)
-* [Architectures](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/architectures.md)
-* [Expanding deployment](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/expanding.md)
-* [Classification](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/classification.md)
-* [Testing](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/pre_post_checks.md)
-* [Docker based examples](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/docker_examples.md)
-* [Release process](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/release_process.md)
+- [Recovery procedures](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/recovery.md)
+- [Architectures](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/architectures.md)
+- [Expanding deployment](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/expanding.md)
+- [Classification](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/classification.md)
+- [Testing](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/pre_post_checks.md)
+- [Docker based examples](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/docker_examples.md)
+- [Release process](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/release_process.md)
 
 ## Getting help
 
-* If you find a bug, you can [create a GitHub issue](https://github.com/puppetlabs/puppetlabs-peadm/issues).
-* For PE customers using PEADM and experiencing outages or other issues, [contact the Support team](https://portal.perforce.com/s/topic/0TO4X000000DbNgWAK/puppet).
+- If you find a bug, you can [create a GitHub issue](https://github.com/puppetlabs/puppetlabs-peadm/issues).
+- For PE customers using PEADM and experiencing outages or other issues, [contact the Support team](https://portal.perforce.com/s/topic/0TO4X000000DbNgWAK/puppet).
 
 ## License
 

REFERENCE.md

@@ -10,6 +10,7 @@
 
 * `peadm::setup::convert_node_manager`: Used during the peadm::convert plan
 * `peadm::setup::convert_pre20197`: Defines configuration needed for converting PE 2018
+* `peadm::setup::legacy_compiler_group`
 * `peadm::setup::node_manager`: Configures PEAdm's required node groups
 * `peadm::setup::node_manager_yaml`: Set up the node_manager.yaml file in the temporary Bolt confdir
 
@@ -55,6 +56,7 @@
 * [`backup_classification`](#backup_classification): A task to call the classification api and write to file
 * [`cert_data`](#cert_data): Return certificate data related to the Puppet agent
 * [`cert_valid_status`](#cert_valid_status): Check primary for valid state of a certificate
+* [`classify_compilers`](#classify_compilers): Classify compilers as legacy or non-legacy
 * [`code_manager`](#code_manager): Perform various code manager actions
 * [`code_sync_status`](#code_sync_status): A task to confirm code is in sync accross the cluster for clusters with code manager configured
 * [`divert_code_manager`](#divert_code_manager): Divert the code manager live-dir setting
@@ -107,6 +109,7 @@ Supported use cases:
 
 #### Private Plans
 
+* `peadm::convert_compiler_to_legacy`
 * `peadm::misc::divert_code_manager`: This plan exists to account for a scenario where a PE XL
 * `peadm::modify_cert_extensions`
 * `peadm::subplans::component_install`: Install a new PEADM component
@@ -116,6 +119,7 @@ Supported use cases:
 * `peadm::subplans::modify_certificate`
 * `peadm::subplans::prepare_agent`
 * `peadm::uninstall`: Single-entry-point plan for uninstalling Puppet Enterprise
+* `peadm::update_compiler_extensions`
 * `peadm::util::code_sync_status`
 * `peadm::util::copy_file`
 * `peadm::util::db_disable_pglogical`
@@ -134,7 +138,7 @@ Type: Puppet Language
 
 Assert that the architecture given is a supported one
 
-#### `peadm::assert_supported_architecture(TargetSpec $primary_host, Variant[TargetSpec, Undef] $replica_host = undef, Variant[TargetSpec, Undef] $primary_postgresql_host = undef, Variant[TargetSpec, Undef] $replica_postgresql_host = undef, Variant[TargetSpec, Undef] $compiler_hosts = undef)`
+#### `peadm::assert_supported_architecture(TargetSpec $primary_host, Variant[TargetSpec, Undef] $replica_host = undef, Variant[TargetSpec, Undef] $primary_postgresql_host = undef, Variant[TargetSpec, Undef] $replica_postgresql_host = undef, Variant[TargetSpec, Undef] $compiler_hosts = undef, Variant[TargetSpec, Undef] $legacy_compilers = undef)`
 
 The peadm::assert_supported_architecture function.
 
@@ -170,6 +174,12 @@ Data type: `Variant[TargetSpec, Undef]`
 
 
 
+##### `legacy_compilers`
+
+Data type: `Variant[TargetSpec, Undef]`
+
+
+
 ### <a name="peadm--assert_supported_bolt_version"></a>`peadm::assert_supported_bolt_version`
 
 Type: Puppet Language
@@ -1054,6 +1064,20 @@ Data type: `String`
 
 The certifcate name to check validation of
 
+### <a name="classify_compilers"></a>`classify_compilers`
+
+Classify compilers as legacy or non-legacy
+
+**Supports noop?** false
+
+#### Parameters
+
+##### `compiler_hosts`
+
+Data type: `Array[String]`
+
+List of FQDNs of compilers
+
 ### <a name="code_manager"></a>`code_manager`
 
 Perform various code manager actions
@@ -1791,6 +1815,7 @@ The following parameters are available in the `peadm::convert` plan:
 * [`primary_host`](#-peadm--convert--primary_host)
 * [`replica_host`](#-peadm--convert--replica_host)
 * [`compiler_hosts`](#-peadm--convert--compiler_hosts)
+* [`legacy_compilers`](#-peadm--convert--legacy_compilers)
 * [`primary_postgresql_host`](#-peadm--convert--primary_postgresql_host)
 * [`replica_postgresql_host`](#-peadm--convert--replica_postgresql_host)
 * [`compiler_pool_address`](#-peadm--convert--compiler_pool_address)
@@ -1819,6 +1844,14 @@ Data type: `Optional[TargetSpec]`
 
 
 
+Default value: `undef`
+
+##### <a name="-peadm--convert--legacy_compilers"></a>`legacy_compilers`
+
+Data type: `Optional[TargetSpec]`
+
+
+
 Default value: `undef`
 
 ##### <a name="-peadm--convert--primary_postgresql_host"></a>`primary_postgresql_host`
@@ -1904,6 +1937,7 @@ The following parameters are available in the `peadm::install` plan:
 * [`primary_host`](#-peadm--install--primary_host)
 * [`replica_host`](#-peadm--install--replica_host)
 * [`compiler_hosts`](#-peadm--install--compiler_hosts)
+* [`legacy_compilers`](#-peadm--install--legacy_compilers)
 * [`primary_postgresql_host`](#-peadm--install--primary_postgresql_host)
 * [`replica_postgresql_host`](#-peadm--install--replica_postgresql_host)
 * [`console_password`](#-peadm--install--console_password)
@@ -2020,6 +2054,14 @@ Data type: `Optional[TargetSpec]`
 
 
 
+Default value: `undef`
+
+##### <a name="-peadm--install--legacy_compilers"></a>`legacy_compilers`
+
+Data type: `Optional[TargetSpec]`
+
+
+
 Default value: `undef`
 
 ##### <a name="-peadm--install--primary_postgresql_host"></a>`primary_postgresql_host`

documentation/convert.md

@@ -1,6 +1,6 @@
-# Convert infrastructure for use with the peadm module
+# Convert infrastructure for use with the PEADM module
 
-The peadm::convert plan can be used to adopt manually deployed infrastructure for use with peadm, or to adopt infrastructure deployed with an older version of peadm.
+The peadm::convert plan can be used to adopt manually deployed infrastructure for use with PEADM or to adopt infrastructure deployed with an older version of peadm.
 
 ## Convert an Existing Deployment
 
@@ -14,19 +14,36 @@ Prepare to run the plan against all servers in the PE infrastructure, using a pa
     "pe-xl-compiler-0.lab1.puppet.vm",
     "pe-xl-compiler-1.lab1.puppet.vm"
   ],
-
-  "compiler_pool_address": "puppet.lab1.puppet.vm",
+  "legacy_compilers": [
+    "pe-xl-legacy-compiler-0.lab1.puppet.vm",
+    "pe-xl-legacy-compiler-1.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`.
+The `begin_at_step` parameter can be used to facilitate re-running this plan after a failed attempt, skipping past any steps that were already completed successfully on the first try and picking up again at the step specified. The step name to resume 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 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/convert_compiler_to_legacy.md

@@ -0,0 +1,9 @@
+# Convert compilers to legacy
+
+### Puppet Enterprise installed with puppetlabs-peadm version 3.25 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 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
+```