.fixtures.yml

@@ -13,7 +13,6 @@ fixtures:
     node_manager: 'https://github.com/WhatsARanjit/puppet-node_manager'
     apply_helpers: 'https://github.com/puppetlabs/puppetlabs-apply_helpers'
     bolt_shim: 'https://github.com/puppetlabs/puppetlabs-bolt_shim'
-    debug: 'https://github.com/nwops/puppet-debug'
     format: 'https://github.com/voxpupuli/puppet-format'
     container_inventory: 'https://gitlab.com/nwops/bolt-container_inventory'
   symlinks:

.github/workflows/test-add-compiler.yaml

@@ -15,7 +15,7 @@ on:
       version:
         description: 'PE version to install'
         required: true
-        default: '2021.7.6'
+        default: '2021.7.7'
       ssh-debugging:
         description: 'Boolean; whether or not to pause for ssh debugging'
         required: true

.github/workflows/test-add-replica.yaml

@@ -15,7 +15,7 @@ on:
       version:
         description: 'PE version to install'
         required: true
-        default: '2021.7.6'
+        default: '2021.7.7'
       ssh-debugging:
         description: 'Boolean; whether or not to pause for ssh debugging'
         required: true

.github/workflows/test-backup-restore.yaml

@@ -15,7 +15,7 @@ on:
       version:
         description: 'PE version to install'
         required: true
-        default: '2021.7.6'
+        default: '2021.7.7'
       ssh-debugging:
         description: 'Boolean; whether or not to pause for ssh debugging'
         required: true

.github/workflows/test-failover.yaml

@@ -15,7 +15,7 @@ on:
       version_to_upgrade:
         description: 'PE version to upgrade to'
         required: false
-        default: '2021.7.6'
+        default: '2021.7.7'
       ssh-debugging:
         description: 'Boolean; whether or not to pause for ssh debugging'
         required: true

.github/workflows/test-fips-install-matrix.yaml

@@ -43,8 +43,8 @@ jobs:
           - extra-large-with-dr
         version:
           - 2019.8.12
-          - 2021.7.6
-          - 2023.5.0
+          - 2021.7.7
+          - 2023.6.0
         image:
           - rhel-8
         fips:

.github/workflows/test-install-matrix.yaml

@@ -43,8 +43,8 @@ jobs:
           - extra-large-with-dr
         version:
           - 2019.8.12
-          - 2021.7.6
-          - 2023.5.0
+          - 2021.7.7
+          - 2023.6.0
         image:
           - centos-7
           - almalinux-cloud/almalinux-8

.github/workflows/test-install.yaml

@@ -15,7 +15,7 @@ on:
       version:
         description: 'PE version to install'
         required: true
-        default: '2021.7.6'
+        default: '2021.7.7'
       ssh-debugging:
         description: 'Boolean; whether or not to pause for ssh debugging'
         required: true

.github/workflows/test-upgrade-latest-dev.yaml

@@ -24,7 +24,7 @@ on:
         type: string
         required: true
         description: "The initial version of PE to install before upgrade"
-        default: "2021.7.6"
+        default: "2021.7.7"
       ssh-debugging:
         description: "Boolean; whether or not to pause for ssh debugging"
         required: true

.github/workflows/test-upgrade-latest-xlarge-dev-nightly.yaml

@@ -19,7 +19,7 @@ jobs:
         architecture:
           - "extra-large-with-dr"
         version:
-          - "2021.7.6"
+          - "2021.7.7"
         image:
           - "almalinux-cloud/almalinux-8"
 

.github/workflows/test-upgrade-matrix.yaml

@@ -44,7 +44,7 @@ jobs:
         version:
           - '2019.8.12'
         version_to_upgrade:
-          - '2021.7.6'
+          - '2021.7.7'
         image:
           - 'almalinux-cloud/almalinux-8'
         download_mode:

.github/workflows/test-upgrade.yaml

@@ -27,7 +27,7 @@ on:
       upgrade_version:
         description: 'PE version to upgrade to'
         required: true
-        default: '2021.7.6'
+        default: '2021.7.7'
       ssh-debugging:
         description: 'Boolean; whether or not to pause for ssh debugging'
         required: true

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org).
 
+## [v3.17.0](https://github.com/puppetlabs/puppetlabs-peadm/tree/v3.17.0) - 2024-02-07
+
+[Full Changelog](https://github.com/puppetlabs/puppetlabs-peadm/compare/v3.16.1...v3.17.0)
+
+### Other
+
+- add environment parameter to puppet_runonce task [#402](https://github.com/puppetlabs/puppetlabs-peadm/pull/402) ([vchepkov](https://github.com/vchepkov))
+
 ## [v3.16.1](https://github.com/puppetlabs/puppetlabs-peadm/tree/v3.16.1) - 2023-11-23
 
 [Full Changelog](https://github.com/puppetlabs/puppetlabs-peadm/compare/v3.16.0...v3.16.1)

README.md

@@ -1,61 +1,82 @@
-# Puppet Enterprise (pe) Administration (adm) Module
+# Puppet Enterprise Administration Module (PEADM)
 
-This Puppet module contains Bolt plans used to deploy and manage Puppet Enterprise infrastructure. Plans are provided to automate common lifecycle activities in order to increase velocity and reduce the possibility of human error incurred by manually performing these activities.
+The Puppet Enterprise Administration Module (PEADM) contains a set of Bolt plans designed for deploying and managing Puppet Enterprise (PE) infrastructure. These plans automate key PE lifecycle activities to accelerate deployment and reduce the risk of human error.
 
-The peadm module is able to deploy and manage Puppet Enterprise 2019.7 and higher for Standard, Large, and Extra Large architectures.
+You can use PEADM to deploy and manage PE installations for standard, large, and extra-large architectures.
 
-#### Table of Contents
+**Important**: PEADM is compatible with PE 2019.8.1 and later versions. If your PE version is older than 2019.8.1 and you want to use PEADM, you must upgrade PE before converting your installation to a PEADM-managed installation.
 
-- [Puppet Enterprise (pe) Administration (adm) Module](#puppet-enterprise-pe-administration-adm-module)
-      - [Table of Contents](#table-of-contents)
-  - [Expectations and support](#expectations-and-support)
+#### Table of contents
+
+- [Puppet Enterprise Administration Module (PEADM)](#puppet-enterprise-pe-administration-adm-module)
+      - [Table of contents](#table-of-contents)
+  - [Support](#support)
   - [Overview](#overview)
-    - [What peadm affects](#what-peadm-affects)
-    - [What peadm does not affect](#what-peadm-does-not-affect)
+    - [What PEADM affects](#what-peadm-affects)
+    - [What PEADM does not affect](#what-peadm-does-not-affect)
     - [Requirements](#requirements)
   - [Usage](#usage)
   - [Reference](#reference)
-  - [Getting Help](#getting-help)
+  - [Getting help](#getting-help)
   - [License](#license)
 
-## Expectations and support
-
-While the peadm module was initially built by the Puppet Solutions Architecture team to streamline particularly large and complex Puppet Enterprise deployments, but has matured to a point where we believe that users with a reasonable understanding of Puppet Enterprise architecture can use it on their own.
+## Support
 
-As a Puppet Enterprise customer this tool is **supported** through Puppet Enterprise's standard and premium [support.puppet.com](https://support.puppet.com) service, and if you have questions or need assistance, you are welcome to reach out to your Support team for help, or to talk to your Sales or Technical Account Manager contacts to arrange a chat with one of us on the Solutions Architect team.
-
-We also love contributions! We're more than happy to also chat about any ideas you may have for improving this module, or offer guidance on ways you could get involved.
+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
 
-The normal usage pattern for peadm is as follows.
-
-1. Users set up a Bolt host from which they can run peadm plans. The Bolt host can be any machine that has ssh access to all of the PE nodes.
-2. Users run the `peadm::install` plan to bootstrap a new PE cluster. Depending on the architecture chosen, peadm may create some node groups in the classifier to set parameters on the built-in `puppet_enterprise` module, tuning it for large or extra large architectures.
-3. Users use and operate their PE cluster as normal. The peadm module is not used again until the next upgrade.
-4. When it is time to upgrade, users run the `peadm::upgrade` plan from their Bolt host to accelerate and aid in the upgrade process.
-
-### What peadm affects
-
-* The `peadm::install` plan adds a number of custom OID trusted facts to the certificates of PE infrastructure nodes as it deploys them. These trusted facts are later used by the plans to quickly and correctly identify nodes in particular roles.
-* Up to four node groups may be created to help configure `puppet_enterprise` class parameters for PE infrastructure roles. The most notable configuration is the designation of compilers as being either "A" or "B" nodes for availability.
-
-### What peadm does not affect
-
-* The peadm module is not required to exist or be present outside of the point(s) in time it is used to create a new PE cluster, or upgrade an existing cluster. No new Puppet classes or other persistent content not provided out-of-box by PE itself is applied to PE infrastructure nodes by the peadm module.
-* Having used the peadm module to install or to upgrade a PE cluster is not known to affect or curtail the ability to use any normal, documented PE procedures, e.g. failover to a replica, or manual upgrade of a cluster.
+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:
+  - name: puppet-enterprise-nodes
+    config:
+      transport: ssh
+      ssh:
+        host-key-check: false
+        user: centos
+        run-as: root
+    targets:
+      - pe-xl-core-0.lab1.puppet.vm
+      - pe-xl-core-1.lab1.puppet.vm
+      - pe-xl-core-2.lab1.puppet.vm
+      - pe-xl-core-3.lab1.puppet.vm
+      - name: pe-xl-compiler-0.lab1.puppet.vm
+        uri: 10.234.6.45
+      - name: pe-xl-compiler-1.lab1.puppet.vm
+        uri: 10.234.14.131
+```
+
+### 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)
+
+### 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.
 
 ### Requirements
 
-* Puppet Enterprise 2019.8.1 or newer (tested with PE 2021.7)
-* Bolt 3.17.0 or newer (tested with Bolt 3.21.0)
-* EL 7, EL 8, Ubuntu 18.04, or Ubuntu 20.04
-* Classifier Data enabled. This PE feature is enabled by default on new installs, but can be disabled by users if they remove the relevant configuration from their global hiera.yaml file. See the [PE docs](https://puppet.com/docs/pe/latest/config_console.html#task-5039) for more information.
+* PEADM is compatible with Puppet Enterprise 2019.8.1 or newer versions.
+* To use PEADM, you must first [install Bolt](https://www.puppet.com/docs/bolt/latest/bolt_installing) version 3.17.0 or newer.
+* PEADM supports PE installations on the following operating systems: EL 7, EL 8, Ubuntu 18.04, or Ubuntu 20.04.
+* 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
 
-Follow the links below to usage instructions for each peadm plan.
+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)
@@ -64,26 +85,26 @@ Follow the links below to usage instructions for each peadm plan.
 
 ## Reference
 
-Information from the Puppet documentation site that will help you understand which architecture is right for you.
+To understand which architecture is right for you, see the following information on the Puppet documentation site:
 
-* [PE Architecture Documentation](https://puppet.com/docs/pe/latest/choosing_an_architecture.html)
-* [PE Multi-region reference architecture](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)
 
 
-Documentation pertaining to additional uses of peadm.
+To learn more about the PEADM module and its uses, see the following PEADM docs:
 
-* [DR Component Recovery](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/recovery.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)
+* [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)
+* [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
+## Getting help
 
-* If you find bugs with this module, please make use of [issues](https://github.com/puppetlabs/puppetlabs-peadm/issues) in the project on GitHub
-* If you are a Puppet Enterprise (PE) customer that uses peadm to manage a deployment of PE and are currently having an outage or need assistance troubleshooting another issue, e.g. upgrades, contact the [Support Team](https://support.puppet.com)
+* 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

@@ -324,7 +324,7 @@ converts two arrays into hash
 
 #### Examples
 
-##### 
+##### Using function
 
 ```puppet
 peadm::convert_hash(['type', 'status'], [['xl', 'running'], ['large', 'failed']])
@@ -341,7 +341,7 @@ Returns: `Array`
 
 ##### Examples
 
-###### 
+###### Using function
 
 ```puppet
 peadm::convert_hash(['type', 'status'], [['xl', 'running'], ['large', 'failed']])
@@ -465,7 +465,7 @@ Type: Puppet Language
 
 #### Examples
 
-##### 
+##### Using function
 
 ```puppet
 peadm::determine_status($data, true)
@@ -519,7 +519,7 @@ Returns: `Hash` A simplified hash of of status data for the given stack
 
 ##### Examples
 
-###### 
+###### Using function
 
 ```puppet
 peadm::determine_status($data, true)
@@ -1340,12 +1340,24 @@ Run the Puppet agent one time
 
 #### Parameters
 
+##### `environment`
+
+Data type: `Optional[String]`
+
+If set, run Puppet in specified code environment
+
 ##### `noop`
 
 Data type: `Optional[Boolean]`
 
 If true, run Puppet in no-op mode
 
+##### `in_progress_timeout`
+
+Data type: `Integer[1]`
+
+How many seconds to wait for a puppet run, that is already in progress
+
 ### <a name="rbac_token"></a>`rbac_token`
 
 Get and save an rbac token for the root user, admin rbac user
@@ -1826,7 +1838,7 @@ Data type: `Peadm::Pe_version`
 
 
 
-Default value: `'2021.7.6'`
+Default value: `'2021.7.7'`
 
 ##### <a name="-peadm--install--dns_alt_names"></a>`dns_alt_names`
 
@@ -2030,7 +2042,7 @@ Return status information from one or more PE clusters in a table format
 
 #### Examples
 
-##### 
+##### Using plan
 
 ```puppet
 peadm::status($targets, 'table', true, true)

documentation/install.md

@@ -114,7 +114,7 @@ Example params.json Bolt parameters file (shown: Standard):
   "primary_host": "pe-xl-core-0.lab1.puppet.vm",
   "console_password": "puppetlabs",
   "dns_alt_names": [ "puppet", "puppet.lab1.puppet.vm" ],
-  "version": "2021.7.6"
+  "version": "2021.7.7"
 }
 ```
 

documentation/upgrade.md

@@ -8,11 +8,11 @@ The `peadm::upgrade` plan requires as input the version of PE to upgrade to, and
 
 Please note that when upgrading from before 2023.4 to 2023.4 or above and you are using code manager, it is nessesary to provide known hosts for r10k. r10k_known_hosts is an optional parameter and is only required one time when upgrading to 2023.4 or beyond. But if you currently use the SSH protocol to allow r10k to access your remote Git repository, your Code manager or r10k code management tool cannot function until you define the r10k_known_hosts parameter. Subsequent upgrades will already have this and it won't be required again. Please refer to the Puppet Enterprise 2023.4 Upgrade cautions for more details.
 
-The following is an example parameters file for upgrading an Extra Large architecture deployment of PE 2023.2.0 to PE 2023.5.0.
+The following is an example parameters file for upgrading an Extra Large architecture deployment of PE 2023.2.0 to PE 2023.6.0.
 
 ```json
 {
-  "version": "2023.5.0",
+  "version": "2023.6.0",
   "primary_host": "pe-master-09a40c-0.us-west1-a.c.reidmv-peadm.internal",
   "primary_postgresql_host": "pe-psql-09a40c-0.us-west1-a.c.reidmv-peadm.internal",
   "replica_host": "pe-master-09a40c-1.us-west1-b.c.reidmv-peadm.internal",

functions/assert_supported_pe_version.pp

@@ -6,7 +6,7 @@ function peadm::assert_supported_pe_version (
   Boolean $permit_unsafe_versions = false,
 ) >> Struct[{ 'supported' => Boolean }] {
   $oldest = '2019.7'
-  $newest = '2023.5'
+  $newest = '2023.6'
   $supported = ($version =~ SemVerRange(">= ${oldest} <= ${newest}"))
 
   if $permit_unsafe_versions {