Puppet Enterprise Administration Module (PEADM)

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.

You can use PEADM to deploy and manage PE installations for standard, large, and extra-large architectures.

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.

Table of contents

• Puppet Enterprise Administration Module (PEADM)
  • Table of contents
  • Support
  • Overview
    • What PEADM affects
    • What PEADM does not affect
    • Requirements
  • Usage
  • Reference
  • Getting help
  • License

Support

PEADM is a supported PE module. If you are a PE customer with the standard or premium support service, you can contact Support or your Technical Account Manager for assistance.

Overview

This is the standard workflow for installing PEADM.

1. Install Bolt on a jump host.
2. To create a Bolt project that includes the PEADM module, run: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:

---
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

• PEADM is compatible with Puppet Enterprise 2019.8.1 or newer versions.
• PEADM requires Bolt 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 for more information.

Usage

For instructions on using PEADM plans, see the following PEADM docs:

• Install
• Upgrade
• Convert
• Status

Reference

To understand which architecture is right for you, see the following information on the Puppet documentation site:

• PE architectures
• PE multi-region reference architectures

To learn more about the PEADM module and its uses, see the following PEADM docs:

• Recovery procedures
• Architectures
• Expanding deployment
• Classification
• Testing
• Docker based examples
• Release process

Getting help

• If you find a bug, you can create a GitHub issue.
• For PE customers using PEADM and experiencing outages or other issues, contact the Support team.

License

This codebase is licensed under Apache 2.0. However, the open source dependencies included in this codebase might be subject to other software licenses such as AGPL, GPL2.0, and MIT.

Reference

Table of Contents

Classes

Private Classes

• 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

Functions

• peadm::assert_supported_architecture: Assert that the architecture given is a supported one
• peadm::assert_supported_bolt_version: Assert that the Bolt executable running PEAdm is a supported version
• peadm::assert_supported_pe_version: Assert that the PE version given is supported by PEAdm
• peadm::bolt_version
• peadm::certname: Return the certname of the given target-like input
• peadm::check_version_and_known_hosts: Checks PE verison and warns about setting r10k_known_hosts
• peadm::convert_hash: converts two arrays into hash
• peadm::convert_status: Transforms a value in a human readable status with or without colors
• peadm::determine_status: Produces a summarized hash of the given status data
• peadm::fail_on_transport: Fails if any nodes have the chosen transport. Useful for excluding PCP when it's not appopriate
• peadm::file_content_upload
• peadm::file_or_content
• peadm::flatten_compact
• peadm::generate_pe_conf: Generate a pe.conf file in JSON format
• peadm::get_pe_conf
• peadm::get_targets: Accept undef or a SingleTargetSpec, and return an Array[Target, 1, 0]. This differs from get_target() in that: - It returns an Array[Target
• peadm::log_plan_parameters
• peadm::migration_opts_default
• peadm::module_version
• peadm::node_manager_yaml_location
• peadm::oid
• peadm::pe_db_names
• peadm::plan_step
• peadm::recovery_opts_all
• peadm::recovery_opts_default
• peadm::update_pe_conf: Update the pe.conf file on a target with the provided hash
• peadm::wait_until_service_ready: A convenience function to help remember port numbers for services and handle running the wait_until_service_ready task

Data types

• Peadm::ConvertSteps: type for the different steps where the peadm::convert plan can be started
• Peadm::Download_mode: download the installer to the bolt node and upload to targets, or let the targets download it directly
• Peadm::Known_hosts
• Peadm::Ldap_config
• Peadm::Pe_version
• Peadm::Pem
• Peadm::Recovery_opts
• Peadm::SingleTargetSpec: A SingleTargetSpec represents any String, Target or single-element array of one or the other that can be passed to get_targets() to return an
• Peadm::UpgradeSteps: type for the different steps where the peadm::upgrade plan can be started

Tasks

• agent_install: Install the Puppet agent from a master
• backup_classification: A task to call the classification api and write to file
• cert_data: Return certificate data related to the Puppet agent
• cert_valid_status: Check primary for valid state of a certificate
• check_pe_master_rules: Checks if the PE Master group rules have already been updated to support 'pe_compiler_legacy' as a pp_auth_role
• classify_compilers: Classify compilers as legacy or non-legacy
• code_manager: Perform various code manager actions
• code_manager_enabled: Run on a PE primary node to check if Code Manager is enabled.
• code_sync_status: A task to confirm code is in sync accross the cluster for clusters with code manager configured
• divert_code_manager: Divert the code manager live-dir setting
• download: Download a file using curl
• enable_replica: Execute the enable replica puppet command
• filesize: Return the size of a file in bytes
• get_group_rules: Run on a PE primary node to return the rules currently applied to the PE Infrastructure Agent group
• get_peadm_config: Run on a PE primary node to return the currently configured PEAdm parameters
• get_psql_version: Run on a PE PSQL node to return the major version of the PSQL server currently installed
• infrastatus: Runs puppet infra status and returns the output
• mkdir_p_file: Create a file with the specified content at the specified location
• mv: Wrapper task for mv command
• node_group_unpin: Unpins nodes from a specified PE node group
• os_identification: Return the operating system runnin gon the target as a string
• pe_install: Install Puppet Enterprise from a tarball
• pe_ldap_config: Set the ldap config in the PE console
• pe_uninstall: Uninstall Puppet Enterprise
• precheck: Return pre-check information about a system
• provision_replica: Execute the replica provision puppet command
• puppet_infra_upgrade: Execute the puppet infra upgrade command
• puppet_runonce: Run the Puppet agent one time
• rbac_token: Get and save an rbac token for the root user, admin rbac user
• read_file: Read the contents of a file
• reinstall_pe: Reinstall PE, only to be used to restore PE
• restore_classification: A short description of this task
• sign_csr: Submit a certificate signing request
• ssl_clean: Clean an agent's certificate
• submit_csr: Submit a certificate signing request
• transform_classification_groups: Transform the user groups from a source backup to a list of groups on the target server
• update_pe_master_rules: Updates the PE Master group rules to support 'pe_compiler_legacy' as a pp_auth_role
• validate_rbac_token: Check an RBAC token stored in a file is valid
• wait_until_service_ready: Return when the orchestrator service is healthy, or timeout after 15 seconds

Plans

Public Plans

• peadm::add_compiler: Proxy plan for peadm::add_compilers.
• peadm::add_compilers: Add new compilers to a PE architecture or replace an existing with new configuration.
• peadm::add_database
• peadm::add_replica: Add or replace a replica host. Supported use cases: 1: Adding a replica to an existing primary. 2: The existing replica is broken, we have a fresh new VM we want to provision the replica to.
• peadm::backup: Backup puppet primary configuration
• peadm::backup_ca
• peadm::convert: Convert an existing PE cluster to a PEAdm-managed cluster
• peadm::install: Install a new PE cluster
• peadm::migrate: Migrate a PE installation to new host(s)
• peadm::modify_certificate: Modify the certificate of one or more targets
• peadm::replace_failed_postgresql: Replaces a failed PostgreSQL host
• peadm::restore: Restore puppet primary configuration
• peadm::restore_ca
• peadm::status: Return status information from one or more PE clusters in a table format
• peadm::upgrade: Upgrade a PEAdm-managed cluster
• peadm::util::init_db_server

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
• peadm::subplans::configure: Configure first-time classification and DR setup
• peadm::subplans::db_populate: Destructively (re)populates a new or existing database with the contents or a known good source
• peadm::subplans::install: Perform initial installation of Puppet Enterprise Extra Large
• peadm::subplans::modify_certificate
• peadm::subplans::prepare_agent
• peadm::uninstall: Single-entry-point plan for uninstalling Puppet Enterprise
• peadm::util::code_sync_status
• peadm::util::copy_file
• peadm::util::db_disable_pglogical
• peadm::util::db_purge
• peadm::util::insert_csr_extension_requests
• peadm::util::retrieve_and_upload
• peadm::util::sanitize_pg_pe_conf
• peadm::util::update_classification: Configure classification
• peadm::util::update_db_setting: Make updates to PuppetDB database settings

Functions

peadm::assert_supported_architecture

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, Variant[TargetSpec, Undef] $legacy_compilers = undef)

The peadm::assert_supported_architecture function.

Returns: Hash

primary_host

Data type: TargetSpec

replica_host

Data type: Variant[TargetSpec, Undef]

primary_postgresql_host

Data type: Variant[TargetSpec, Undef]

replica_postgresql_host

Data type: Variant[TargetSpec, Undef]

compiler_hosts

Data type: Variant[TargetSpec, Undef]

legacy_compilers

Data type: Variant[TargetSpec, Undef]

peadm::assert_supported_bolt_version

Type: Puppet Language

Checks if the current Bolt version matches the SemVerRange defined in $supported_bolt_version Fails the calling plan if false, does nothing if true. Accepts a parameter for the $supported_bolt_version for unit testing purposes

peadm::assert_supported_bolt_version()

Checks if the current Bolt version matches the SemVerRange defined in $supported_bolt_version Fails the calling plan if false, does nothing if true. Accepts a parameter for the $supported_bolt_version for unit testing purposes

Returns: Struct[{ 'supported' => Boolean }]

peadm::assert_supported_pe_version

Type: Puppet Language

Assert that the PE version given is supported by PEAdm

peadm::assert_supported_pe_version(String $version, Boolean $permit_unsafe_versions = false)

The peadm::assert_supported_pe_version function.

Returns: Struct[{ 'supported' => Boolean }] true if the version is supported, raise error otherwise

the

Data type: String

version number to check

version

Data type: String

permit_unsafe_versions

Data type: Boolean

peadm::bolt_version

Type: Ruby 4.x API

The peadm::bolt_version function.

peadm::bolt_version()

The peadm::bolt_version function.

Returns: Any

peadm::certname

Type: Puppet Language

This function accepts a variety of data types which could represent single targets, and returns the certname corresponding to the input.

For Target objects, or arrays of a single Target object, a "certname" var can be set, which determines that target's certname. Otherwise, the target's name is its certname. For strings, the certname is equal to the string. Undef input returns undef.

`peadm::certname(Variant[Target,

String,
Undef,
Array[Target,1,1],
Array[String,1,1],
Array[Undef,1,1],

Array[Any,0,0]] $target)`

This function accepts a variety of data types which could represent single targets, and returns the certname corresponding to the input.

For Target objects, or arrays of a single Target object, a "certname" var can be set, which determines that target's certname. Otherwise, the target's name is its certname. For strings, the certname is equal to the string. Undef input returns undef.

Returns: Variant[String, Undef]

target

Data type:

Variant[Target,
    String,
    Undef,
    Array[Target,1,1],
    Array[String,1,1],
    Array[Undef,1,1],
  Array[Any,0,0]]

peadm::check_version_and_known_hosts

Type: Puppet Language

Checks if the current PE version is less than 2023.3.0 and the target version is greater than or equal to 2023.3.0 If both conditions are true and the r10k_known_hosts parameter is not defined, a warning message is displayed.

peadm::check_version_and_known_hosts(String $current_version, String $target_version, Optional[Peadm::Known_hosts] $r10k_known_hosts = undef)

Checks if the current PE version is less than 2023.3.0 and the target version is greater than or equal to 2023.3.0 If both conditions are true and the r10k_known_hosts parameter is not defined, a warning message is displayed.

Returns: Any

$current_version

Data type: String

The current PE version

$target_version

Data type: String

The target PE version

$r10k_known_hosts

Data type: Optional[Peadm::Known_hosts]

The r10k_known_hosts parameter

current_version

Data type: String

target_version

Data type: String

r10k_known_hosts

Data type: Optional[Peadm::Known_hosts]

peadm::convert_hash

Type: Puppet Language

converts two arrays into hash

Examples

Using function

peadm::convert_hash(['type', 'status'], [['xl', 'running'], ['large', 'failed']])
[
  { type => xl, status => running}, { type => large, status => failed }
]

peadm::convert_hash(Array $keys, Array[Array] $values)

The peadm::convert_hash function.

Returns: Array

Examples

Using function

peadm::convert_hash(['type', 'status'], [['xl', 'running'], ['large', 'failed']])
[
  { type => xl, status => running}, { type => large, status => failed }
]

keys

Data type: Array

an array of key names to be merged into the hash

values

Data type: Array[Array]

data to be merged into an array with the keys

peadm::convert_status

Type: Puppet Language

Transforms a value in a human readable status with or without colors

Examples

With colors

peadm::convert_status(true) = "\e[32moperational\e[0m"

Without colors

peadm::convert_status(true, 0, false) = "operational"

Using integers where 1 of 2 services has failed

peadm::convert_status(1, 2, false) = "degraded"

Using integers where 2 of 2 services has failed

peadm::convert_status(2, 2, false) = "failed"

Using integers where 0 of 2 services has failed

peadm::convert_status(0, 2, false) = "operational"

peadm::convert_status(Variant[String,Boolean, Integer] $status, Optional[Integer] $total = 0, Optional[Boolean] $use_colors = true)

The peadm::convert_status function.

Returns: String A status as a string with or without color

Examples

With colors

peadm::convert_status(true) = "\e[32moperational\e[0m"

Without colors

peadm::convert_status(true, 0, false) = "operational"

Using integers where 1 of 2 services has failed

peadm::convert_status(1, 2, false) = "degraded"

Using integers where 2 of 2 services has failed

peadm::convert_status(2, 2, false) = "failed"

Using integers where 0 of 2 services has failed

peadm::convert_status(0, 2, false) = "operational"

status

Data type: Variant[String,Boolean, Integer]

A value of true, false, degraded, or an Integer that represents number of non operationally services If using an integer, you must also supply the total amount of services

total

Data type: Optional[Integer]

the total number of services, used only when the status is an integer

use_colors

Data type: Optional[Boolean]

Adds colors to the status, defaults to true

peadm::determine_status

Type: Puppet Language

}

Examples

Using function

peadm::determine_status($data, true)
{
 "failed" => {
           "activity/pe-std-replica.puppet.vm" => false,
         "classifier/pe-std-replica.puppet.vm" => false,
   "file-sync-client/pe-std-replica.puppet.vm" => false,
             "master/pe-std-replica.puppet.vm" => false,
           "puppetdb/pe-std-replica.puppet.vm" => false,
               "rbac/pe-std-replica.puppet.vm" => false
 },
 "passed" => {
            "activity-service/pe-std.puppet.vm" => true,
              "broker-service/pe-std.puppet.vm" => true,
          "classifier-service/pe-std.puppet.vm" => true,
        "code-manager-service/pe-std.puppet.vm" => true,
    "file-sync-client-service/pe-std.puppet.vm" => true,
   "file-sync-storage-service/pe-std.puppet.vm" => true,
        "orchestrator-service/pe-std.puppet.vm" => true,
                   "pe-master/pe-std.puppet.vm" => true,
             "puppetdb-status/pe-std.puppet.vm" => true,
                "rbac-service/pe-std.puppet.vm" => true
 },
  "state" => {
            "activity-service/pe-std.puppet.vm" => true,
            "activity/pe-std-replica.puppet.vm" => false,
              "broker-service/pe-std.puppet.vm" => true,
          "classifier-service/pe-std.puppet.vm" => true,
          "classifier/pe-std-replica.puppet.vm" => false,
        "code-manager-service/pe-std.puppet.vm" => true,
    "file-sync-client-service/pe-std.puppet.vm" => true,
    "file-sync-client/pe-std-replica.puppet.vm" => false,
   "file-sync-storage-service/pe-std.puppet.vm" => true,
              "master/pe-std-replica.puppet.vm" => false,
        "orchestrator-service/pe-std.puppet.vm" => true,
                   "pe-master/pe-std.puppet.vm" => true,
             "puppetdb-status/pe-std.puppet.vm" => true,
            "puppetdb/pe-std-replica.puppet.vm" => false,
                "rbac-service/pe-std.puppet.vm" => true,
                "rbac/pe-std-replica.puppet.vm" => false
 },
 "status" => "\e[33mdegraded\e[0m"

peadm::determine_status(Array $status_data, Boolean $use_colors = true)

}

Returns: Hash A simplified hash of of status data for the given stack

Examples

Using function

peadm::determine_status($data, true)
{
 "failed" => {
           "activity/pe-std-replica.puppet.vm" => false,
         "classifier/pe-std-replica.puppet.vm" => false,
   "file-sync-client/pe-std-replica.puppet.vm" => false,
             "master/pe-std-replica.puppet.vm" => false,
           "puppetdb/pe-std-replica.puppet.vm" => false,
               "rbac/pe-std-replica.puppet.vm" => false
 },
 "passed" => {
            "activity-service/pe-std.puppet.vm" => true,
              "broker-service/pe-std.puppet.vm" => true,
          "classifier-service/pe-std.puppet.vm" => true,
        "code-manager-service/pe-std.puppet.vm" => true,
    "file-sync-client-service/pe-std.puppet.vm" => true,
   "file-sync-storage-service/pe-std.puppet.vm" => true,
        "orchestrator-service/pe-std.puppet.vm" => true,
                   "pe-master/pe-std.puppet.vm" => true,
             "puppetdb-status/pe-std.puppet.vm" => true,
                "rbac-service/pe-std.puppet.vm" => true
 },
  "state" => {
            "activity-service/pe-std.puppet.vm" => true,
            "activity/pe-std-replica.puppet.vm" => false,
              "broker-service/pe-std.puppet.vm" => true,
          "classifier-service/pe-std.puppet.vm" => true,
          "classifier/pe-std-replica.puppet.vm" => false,
        "code-manager-service/pe-std.puppet.vm" => true,
    "file-sync-client-service/pe-std.puppet.vm" => true,
    "file-sync-client/pe-std-replica.puppet.vm" => false,
   "file-sync-storage-service/pe-std.puppet.vm" => true,
              "master/pe-std-replica.puppet.vm" => false,
        "orchestrator-service/pe-std.puppet.vm" => true,
                   "pe-master/pe-std.puppet.vm" => true,
             "puppetdb-status/pe-std.puppet.vm" => true,
            "puppetdb/pe-std-replica.puppet.vm" => false,
                "rbac-service/pe-std.puppet.vm" => true,
                "rbac/pe-std-replica.puppet.vm" => false
 },
 "status" => "\e[33mdegraded\e[0m"

status_data

Data type: Array

Raw json data as returned by puppet infra status --format=json

use_colors

Data type: Boolean

Adds colors to the status, defaults to true

peadm::fail_on_transport

Type: Puppet Language

Fails if any nodes have the chosen transport.

Useful for excluding PCP when it's not appopriate

peadm::fail_on_transport(TargetSpec $nodes, String $transport, String $message = 'This is not supported.')

Fails if any nodes have the chosen transport.

Useful for excluding PCP when it's not appopriate

Returns: Any

nodes

Data type: TargetSpec

transport

Data type: String

message

Data type: String

peadm::file_content_upload

Type: Ruby 4.x API

The peadm::file_content_upload function.

peadm::file_content_upload(String[1] $content, String[1] $destination, TargetOrTargets *$targets)

The peadm::file_content_upload function.

Returns: Any

content

Data type: String[1]

destination

Data type: String[1]

*targets

Data type: TargetOrTargets

peadm::file_or_content

Type: Puppet Language

The peadm::file_or_content function.

peadm::file_or_content(String $param_name, Variant[String, Undef] $file, Variant[String, Undef] $content)

The peadm::file_or_content function.

Returns: Any

param_name

Data type: String

file

Data type: Variant[String, Undef]

content

Data type: Variant[String, Undef]

peadm::flatten_compact

Type: Puppet Language

The peadm::flatten_compact function.

peadm::flatten_compact(Array $input)

The peadm::flatten_compact function.

Returns: Any

input

Data type: Array

peadm::generate_pe_conf

Type: Puppet Language

Generate a pe.conf file in JSON format

peadm::generate_pe_conf(Hash $settings)

The peadm::generate_pe_conf function.

Returns: String

settings

Data type: Hash

A hash of settings to set in the config file. Any keys that are set to undef will not be included in the config file.

peadm::get_pe_conf

Type: Puppet Language

The peadm::get_pe_conf function.

peadm::get_pe_conf(Target $target)

The peadm::get_pe_conf function.

Returns: Any

target

Data type: Target

peadm::get_targets

Type: Puppet Language

Accept undef or a SingleTargetSpec, and return an Array[Target, 1, 0]. This differs from get_target() in that:

• It returns an Array[Target, 1, 0], rather than a Target
• It will accept undef and return [ ].

peadm::get_targets(Variant[TargetSpec, Undef] $spec, Optional[Integer[1,1]] $count = undef)

Accept undef or a SingleTargetSpec, and return an Array[Target, 1, 0]. This differs from get_target() in that:

• It returns an Array[Target, 1, 0], rather than a Target
• It will accept undef and return [ ].

Returns: Any

spec

Data type: Variant[TargetSpec, Undef]

count

Data type: Optional[Integer[1,1]]

peadm::log_plan_parameters

Type: Puppet Language

The peadm::log_plan_parameters function.

peadm::log_plan_parameters(Hash $params)

The peadm::log_plan_parameters function.

Returns: Any

params

Data type: Hash

peadm::migration_opts_default

Type: Puppet Language

The peadm::migration_opts_default function.

peadm::migration_opts_default()

The peadm::migration_opts_default function.

Returns: Any

peadm::module_version

Type: Ruby 4.x API

The peadm::module_version function.

peadm::module_version()

The peadm::module_version function.

Returns: Any

peadm::node_manager_yaml_location

Type: Ruby 4.x API

The peadm::node_manager_yaml_location function.

peadm::node_manager_yaml_location()

The peadm::node_manager_yaml_location function.

Returns: Any

peadm::oid

Type: Puppet Language

The peadm::oid function.

peadm::oid(String $short_name)

The peadm::oid function.

Returns: Any

short_name

Data type: String

peadm::pe_db_names

Type: Puppet Language

The peadm::pe_db_names function.

peadm::pe_db_names(String $pe_ver)

The peadm::pe_db_names function.

Returns: Array

pe_ver

Data type: String

peadm::plan_step

Type: Ruby 4.x API

The peadm::plan_step function.

peadm::plan_step(String $step_name, Callable &$block)

The peadm::plan_step function.

Returns: Any

step_name

Data type: String

&block

Data type: Callable

peadm::recovery_opts_all

Type: Puppet Language

The peadm::recovery_opts_all function.

peadm::recovery_opts_all()

The peadm::recovery_opts_all function.

Returns: Any

peadm::recovery_opts_default

Type: Puppet Language

The peadm::recovery_opts_default function.

peadm::recovery_opts_default()

The peadm::recovery_opts_default function.

Returns: Any

peadm::update_pe_conf

Type: Puppet Language

Update the pe.conf file on a target with the provided hash

peadm::update_pe_conf(Target $target, Hash $updated_pe_conf_hash)

The peadm::update_pe_conf function.

Returns: Any

target

Data type: Target

The target to update the pe.conf file on

updated_pe_conf_hash

Data type: Hash

The hash to update the pe.conf file with

peadm::wait_until_service_ready

Type: Puppet Language

A convenience function to help remember port numbers for services and handle running the wait_until_service_ready task

peadm::wait_until_service_ready(String $service, TargetSpec $target)

A convenience function to help remember port numbers for services and handle running the wait_until_service_ready task

Returns: Any

service

Data type: String

target

Data type: TargetSpec

Data types

Peadm::ConvertSteps

type for the different steps where the peadm::convert plan can be started

Alias of Enum['modify-primary-certs', 'modify-infra-certs', 'convert-node-groups', 'finalize']

Peadm::Download_mode

download the installer to the bolt node and upload to targets, or let the targets download it directly

Alias of Enum['direct', 'bolthost']

Peadm::Known_hosts

The Peadm::Known_hosts data type.

Alias of

Array[Struct[
    'title'        => Optional[String[1]],
    'ensure'       => Optional[Enum['present','absent']],
    'name'         => String[1],
    'type'         => String[1],
    'key'          => String[1],
    'host_aliases' => Optional[Variant[String[1],Array[String[1]]]],
  ]]

Peadm::Ldap_config

The Peadm::Ldap_config data type.

Alias of

Struct[{
    base_dn                             => String,
    connect_timeout                     => Integer,
    disable_ldap_matching_rule_in_chain => Boolean,
    display_name                        => String,
    group_lookup_attr                   => String,
    group_member_attr                   => String,
    group_name_attr                     => String,
    group_object_class                  => String,
    Optional[group_rdn]                 => Optional[String],
    Optional[help_link]                 => Optional[String],
    hostname                            => String,
    Optional[login]                     => Optional[String],
    Optional[password]                  => Optional[String],
    port                                => Integer,
    search_nested_groups                => Boolean,
    ssl                                 => Boolean,
    ssl_hostname_validation             => Boolean,
    ssl_wildcard_validation             => Boolean,
    start_tls                           => Boolean,
    user_display_name_attr              => String,
    user_email_attr                     => String,
    user_lookup_attr                    => String,
    Optional[user_rdn]                  => Optional[String],
}]

Peadm::Pe_version

The Peadm::Pe_version data type.

Alias of Pattern[/^\d+\.\d+\.\d+(-.+)?$/]

Peadm::Pem

The Peadm::Pem data type.

Alias of Pattern[/^-----BEGIN/]

Peadm::Recovery_opts

The Peadm::Recovery_opts data type.

Alias of

Struct[{
    'activity'     => Optional[Boolean],
    'ca'           => Optional[Boolean],
    'classifier'   => Optional[Boolean],
    'code'         => Optional[Boolean],
    'config'       => Optional[Boolean],
    'orchestrator' => Optional[Boolean],
    'puppetdb'     => Optional[Boolean],
    'rbac'         => Optional[Boolean],
}]

Peadm::SingleTargetSpec

A SingleTargetSpec represents any String, Target or single-element array of one or the other that can be passed to gettargets() to return an Array[Target, 1, 1]. This is a constrained type variant of Boltlib::TargetSpec for use when a _single target is valid, but multiple targets are not.

Alias of Variant[Pattern[/\A[^[:space:],]+\z/], Target, Array[Peadm::SingleTargetSpec, 1, 1]]

Peadm::UpgradeSteps

type for the different steps where the peadm::upgrade plan can be started

Alias of Enum['upgrade-primary', 'upgrade-node-groups', 'upgrade-primary-compilers', 'upgrade-replica', 'upgrade-replica-compilers', 'finalize']

Tasks

agent_install

Install the Puppet agent from a master

Supports noop? false

Parameters

server

Data type: String

The resolvable name of the Puppet server to install from

install_flags

Data type: Array[String]

Positional arguments to pass to the shell installer

backup_classification

A task to call the classification api and write to file

Supports noop? false

Parameters

directory

Data type: String

The directory to write the classification output to. Directory must exist

cert_data

Return certificate data related to the Puppet agent

Supports noop? false

cert_valid_status

Check primary for valid state of a certificate

Supports noop? false

Parameters

certname

Data type: String

The certifcate name to check validation of

check_pe_master_rules

Checks if the PE Master group rules have already been updated to support 'pe_compiler_legacy' as a pp_auth_role

Supports noop? false

classify_compilers

Classify compilers as legacy or non-legacy

Supports noop? false

Parameters

compiler_hosts

Data type: Array[String]

List of FQDNs of compilers

code_manager

Perform various code manager actions

Supports noop? false

Parameters

action

Data type: String

What code manager action to perform. For example: 'deploy production'; 'flush-environment-cache'; 'file-sync commit'

code_manager_enabled

Run on a PE primary node to check if Code Manager is enabled.

Supports noop? false

code_sync_status

A task to confirm code is in sync accross the cluster for clusters with code manager configured

Supports noop? false

Parameters

environments

Data type: Array

A list of environments to check, pass a single value of all for all

divert_code_manager

Divert the code manager live-dir setting

Supports noop? false

download

Download a file using curl

Supports noop? false

Parameters

source

Data type: String

Where to download the file from

path

Data type: String

Where to save the downloaded file

verify_download

Data type: Boolean

Whether to check the integrity of the downloaded file

key_server

Data type: String

The GPG keyserver to retrieve GPG keys from

enable_replica

Execute the enable replica puppet command

Supports noop? false

Parameters

replica

Data type: String

The name of the replica to enable

token_file

Data type: Optional[String]

The name of the token file to use for auth

filesize

Return the size of a file in bytes

Supports noop? false

Parameters

path

Data type: String

Path to the file to return the size of

get_group_rules

Run on a PE primary node to return the rules currently applied to the PE Infrastructure Agent group

Supports noop? false

get_peadm_config

Run on a PE primary node to return the currently configured PEAdm parameters

Supports noop? false

get_psql_version

Run on a PE PSQL node to return the major version of the PSQL server currently installed

Supports noop? false

infrastatus

Runs puppet infra status and returns the output

Supports noop? false

Parameters

format

Data type: Enum[json,text]

The type of output to return

mkdir_p_file

Create a file with the specified content at the specified location

Supports noop? false

Parameters

path

Data type: String

The fully qualified path of the file to create

content

Data type: String

The content to create the file with

owner

Data type: Optional[String]

The file owner

group

Data type: Optional[String]

The file group

mode

Data type: Optional[String]

The file mode

chown_r

Data type: Optional[String]

If supplied, recursively chown starting at this path

mv

Wrapper task for mv command

Supports noop? false

Parameters

source

Data type: String

Current path of file

target

Data type: String

New path of file

node_group_unpin

Unpins nodes from a specified PE node group

Supports noop? false

Parameters

node_certnames

Data type: Array[String]

The certnames of the nodes to unpin

group_name

Data type: String

The name of the node group to unpin the nodes from

os_identification

Return the operating system runnin gon the target as a string

Supports noop? false

pe_install

Install Puppet Enterprise from a tarball

Supports noop? false

Parameters

tarball

Data type: String

The path to the Puppet Enterprise tarball

peconf

Data type: Optional[String]

The path to the pe.conf file

install_extra_large

Data type: Optional[Boolean]

If true, optimize task for known manual issues with extra-large installs. Do not use for upgrades

puppet_service_ensure

Data type: Optional[Enum['stopped']]

If 'stopped', ensure the Puppet agent is not running when install completes

pe_ldap_config

Set the ldap config in the PE console

Supports noop? false

Parameters

ldap_config

Data type: Peadm::Ldap_config

The hash of options for ldap.

pe_main

Data type: String

The PE Main server

pe_version

Data type: String

The PE version

pe_uninstall

Uninstall Puppet Enterprise

Supports noop? false

precheck

Return pre-check information about a system

Supports noop? false

provision_replica

Execute the replica provision puppet command

Supports noop? false

Parameters

replica

Data type: String

The name of the replica to provision

token_file

Data type: Optional[String]

The name of the token-file for auth

legacy

Data type: Boolean

Set to true if provisioning a replica for PE 2019.5 or older. Defaults to false

puppet_infra_upgrade

Execute the puppet infra upgrade command

Supports noop? false

Parameters

type

Data type: Enum[compiler,replica]

Which kind of infra node to upgrade

targets

Data type: Array[String]

The certnames of the targets to upgrade

token_file

Data type: Optional[String]

The path to the token file to use

wait_until_connected_timeout

Data type: Integer

How many seconds to wait for targets to be connected to the orchestrator

puppet_runonce

Run the Puppet agent one time

Supports noop? false

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

rbac_token

Get and save an rbac token for the root user, admin rbac user

Supports noop? false

Parameters

password

Data type: String

The password for the admin user

token_lifetime

Data type: String

The duration for which a token will be valid. Format [smhdy]

read_file

Read the contents of a file

Supports noop? false

Parameters

path

Data type: String

Path to the file to read

reinstall_pe

Reinstall PE, only to be used to restore PE

Supports noop? false

Parameters

version

Data type: String[1]

The PE version to install

arch

Data type: String[1]

The PE installation platform

uninstall

Data type: Boolean

Whether we want to uninstall PE before installing

restore_classification

A short description of this task

Supports noop? false

Parameters

classification_file

Data type: String

The full path to a backed up or transformed classification file

sign_csr

Submit a certificate signing request

Supports noop? false

Parameters

certnames

Data type: Array[String]

A list of certnames to sign

ssl_clean

Clean an agent's certificate

Supports noop? false

Parameters

certname

Data type: String

The certname to clean

submit_csr

Submit a certificate signing request

Supports noop? false

Parameters

dns_alt_names

Data type: Optional[Array[String]]

DNS Alternative Names to request for the certificate

transform_classification_groups

Transform the user groups from a source backup to a list of groups on the target server

Supports noop? false

Parameters

source_directory

Data type: String

Location of Source node group yaml file

working_directory

Data type: String

Location of target node group yaml file and where to create the transformed file

update_pe_master_rules

Updates the PE Master group rules to support 'pe_compiler_legacy' as a pp_auth_role

Supports noop? false

validate_rbac_token

Check an RBAC token stored in a file is valid

Supports noop? false

Parameters

token_file

Data type: Optional[String]

The path to the token file to use

wait_until_service_ready

Return when the orchestrator service is healthy, or timeout after 15 seconds

Supports noop? false

Parameters

service

Data type: Enum[all, ca, pe-master, orchestrator-service]

What service to check. For example: all, pe-master, orchestrator-service

port

Data type: Enum['8140', '8143']

Which port to query the status API on

Plans

peadm::add_compiler

Proxy plan for peadm::add_compilers.

Parameters

The following parameters are available in the peadm::add_compiler plan:

• avail_group_letter
• compiler_host
• dns_alt_names
• primary_host
• primary_postgresql_host

avail_group_letter

Data type: Enum['A', 'B']

_ Either A or B; whichever of the two letter designations the compiler are being assigned to

Default value: 'A'

compiler_host

Data type: Peadm::SingleTargetSpec

_ The hostname and certname of the new compiler

dns_alt_names

Data type: Optional[String[1]]

_ A comma-separated list of DNS alt names for the compiler.

Default value: undef

primary_host

Data type: Peadm::SingleTargetSpec

_ The hostname and certname of the primary Puppet server

primary_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

_ The hostname and certname of the PE-PostgreSQL server with availability group $avail_group_letter

Default value: undef

peadm::add_compilers

Add new compilers to a PE architecture or replace an existing with new configuration.

Parameters

The following parameters are available in the peadm::add_compilers plan:

• avail_group_letter
• compiler_hosts
• dns_alt_names
• primary_host
• primary_postgresql_host

avail_group_letter

Data type: Enum['A', 'B']

_ Either A or B; whichever of the two letter designations the compilers are being assigned to

Default value: 'A'

compiler_hosts

Data type: TargetSpec

_ The hostnames and certnames of the new compilers

dns_alt_names

Data type: Optional[Array[String[1]]]

_ An array of strings, where each string is a comma-separated list of DNS alt names for the compilers. Order matters; if a compiler doesn't need dns_alt_names, use "undef" as string.

Default value: undef

primary_host

Data type: Peadm::SingleTargetSpec

_ The hostname and certname of the primary Puppet server

primary_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

_ The hostname and certname of the PE-PostgreSQL server with availability group $avail_group_letter

Default value: undef

peadm::add_database

The peadm::add_database class.

Parameters

The following parameters are available in the peadm::add_database plan:

• targets
• primary_host
• mode
• begin_at_step
• is_migration

targets

Data type: Peadm::SingleTargetSpec

primary_host

Data type: Peadm::SingleTargetSpec

mode

Data type: Optional[Enum['init', 'pair']]

Default value: undef

begin_at_step

Data type:

Optional[Enum[
      'init-db-node',
      'replicate-db',
      'update-classification',
      'update-db-settings',
      'cleanup-db',
  'finalize']]

Default value: undef

is_migration

Data type: Optional[Boolean]

Default value: false

peadm::add_replica

Add or replace a replica host. Supported use cases: 1: Adding a replica to an existing primary. 2: The existing replica is broken, we have a fresh new VM we want to provision the replica to.

Parameters

The following parameters are available in the peadm::add_replica plan:

• primary_host
• replica_host
• replica_postgresql_host
• token_file

primary_host

Data type: Peadm::SingleTargetSpec

• The hostname and certname of the primary Puppet server

replica_host

Data type: Peadm::SingleTargetSpec

• The hostname and certname of the replica VM

replica_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

• The hostname and certname of the host with the replica PE-PosgreSQL database. Can be a separate host in an XL architecture, or undef in Standard or Large.

Default value: undef

token_file

Data type: Optional[String]

• (optional) the token file in a different location than the default.

Default value: undef

peadm::backup

Backup puppet primary configuration

Examples

bolt plan run peadm::backup -t primary1.example.com

Parameters

The following parameters are available in the peadm::backup plan:

• targets
• backup_type
• backup
• output_directory

targets

Data type: Peadm::SingleTargetSpec

This should be the primary puppetserver for the puppet cluster

backup_type

Data type: Enum['recovery', 'custom', 'migration']

Currently, the recovery and custom backup types are supported

Default value: 'recovery'

backup

Data type: Peadm::Recovery_opts

A hash of custom backup options, see the peadm::recovery_opts_default() function for the default values

Default value: {}

output_directory

Data type: String

The directory to place the backup in

Default value: '/tmp'

peadm::backup_ca

The peadm::backup_ca class.

Parameters

The following parameters are available in the peadm::backup_ca plan:

• target
• output_directory

target

Data type: Peadm::SingleTargetSpec

output_directory

Data type: Optional[String]

Default value: '/tmp'

peadm::convert

This plan sets required certificate extensions on PE nodes, and configures the required PE node groups to make an existing cluster compatible with management using PEAdm.

Parameters

The following parameters are available in the peadm::convert plan:

• begin_at_step
• primary_host
• replica_host
• compiler_hosts
• legacy_compilers
• primary_postgresql_host
• replica_postgresql_host
• compiler_pool_address
• internal_compiler_a_pool_address
• internal_compiler_b_pool_address
• dns_alt_names

begin_at_step

Data type: Optional[Peadm::ConvertSteps]

The step where the plan should start. If not set, it will start at the beginning

Default value: undef

primary_host

Data type: Peadm::SingleTargetSpec

replica_host

Data type: Optional[Peadm::SingleTargetSpec]

Default value: undef

compiler_hosts

Data type: Optional[TargetSpec]

Default value: undef

legacy_compilers

Data type: Optional[TargetSpec]

Default value: undef

primary_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

Default value: undef

replica_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

Default value: undef

compiler_pool_address

Data type: String

Default value: $primary_host

internal_compiler_a_pool_address

Data type: Optional[String]

Default value: undef

internal_compiler_b_pool_address

Data type: Optional[String]

Default value: undef

dns_alt_names

Data type: Array[String]

Default value: []

peadm::install

Install a new PE cluster

Parameters

The following parameters are available in the peadm::install plan:

• compiler_pool_address
• internal_compiler_a_pool_address
• internal_compiler_b_pool_address
• pe_installer_source
• ldap_config
• final_agent_state
• stagingdir
• uploaddir
• primary_host
• replica_host
• compiler_hosts
• legacy_compilers
• primary_postgresql_host
• replica_postgresql_host
• console_password
• version
• dns_alt_names
• pe_conf_data
• code_manager_auto_configure
• r10k_remote
• r10k_private_key_file
• r10k_private_key_content
• r10k_known_hosts
• deploy_environment
• license_key_file
• license_key_content
• download_mode
• permit_unsafe_versions
• token_lifetime

compiler_pool_address

Data type: Optional[String]

The service address used by agents to connect to compilers, or the Puppet service. Typically this is a load balancer.

Default value: undef

internal_compiler_a_pool_address

Data type: Optional[String]

A load balancer address directing traffic to any of the "A" pool compilers. This is used for DR configuration in large and extra large architectures.

Default value: undef

internal_compiler_b_pool_address

Data type: Optional[String]

A load balancer address directing traffic to any of the "B" pool compilers. This is used for DR configuration in large and extra large architectures.

Default value: undef

pe_installer_source

Data type: Optional[Stdlib::HTTPSUrl]

The URL to download the Puppet Enterprise installer media from. If not specified, PEAdm will attempt to download PE installation media from its standard public source. When specified, PEAdm will download directly from the URL given.

Default value: undef

ldap_config

Data type: Optional[Peadm::Ldap_config]

If specified, configures PE RBAC DS with the supplied configuration hash. The parameter should be set to a valid set of connection settings as documented for the PE RBAC /ds endpoint. See: https://puppet.com/docs/pe/latest/rbac_api_v1_directory.html#put_ds-request_format

Default value: undef

final_agent_state

Data type: Enum['running', 'stopped']

Configures the state the puppet agent should be in on infrastructure nodes after PE is configured successfully.

Default value: 'running'

stagingdir

Data type: Optional[String]

Directory on the Bolt host where the installer tarball will be cached if download_mode is 'bolthost' (default)

Default value: undef

uploaddir

Data type: Optional[String]

Directory the installer tarball will be uploaded to or expected to be in for offline usage.

Default value: undef

primary_host

Data type: Peadm::SingleTargetSpec

replica_host

Data type: Optional[Peadm::SingleTargetSpec]

Default value: undef

compiler_hosts

Data type: Optional[TargetSpec]

Default value: undef

legacy_compilers

Data type: Optional[TargetSpec]

Default value: undef

primary_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

Default value: undef

replica_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

Default value: undef

console_password

Data type: String

version

Data type: Peadm::Pe_version

Default value: '2023.8.4'

dns_alt_names

Data type: Optional[Array[String]]

Default value: undef

pe_conf_data

Data type: Optional[Hash]

Default value: {}

code_manager_auto_configure

Data type: Optional[Boolean]

Default value: undef

r10k_remote

Data type: Optional[String]

Default value: undef

r10k_private_key_file

Data type: Optional[String]

Default value: undef

r10k_private_key_content

Data type: Optional[Peadm::Pem]

Default value: undef

r10k_known_hosts

Data type: Optional[Peadm::Known_hosts]

Default value: undef

deploy_environment

Data type: Optional[String]

Default value: undef

license_key_file

Data type: Optional[String]

Default value: undef

license_key_content

Data type: Optional[String]

Default value: undef

download_mode

Data type: Peadm::Download_mode

Default value: 'bolthost'

permit_unsafe_versions

Data type: Boolean

Default value: false

token_lifetime

Data type: String

Default value: '1y'

peadm::migrate

Migrate a PE installation to new host(s)

Parameters

The following parameters are available in the peadm::migrate plan:

• old_primary_host
• new_primary_host
• upgrade_version
• replica_host
• primary_postgresql_host
• replica_postgresql_host

old_primary_host

Data type: Peadm::SingleTargetSpec

The existing PE primary server that will be migrated from

new_primary_host

Data type: Peadm::SingleTargetSpec

The new server that will become the PE primary server

upgrade_version

Data type: Optional[String]

Optional version to upgrade to after migration is complete

Default value: undef

replica_host

Data type: Optional[Peadm::SingleTargetSpec]

Optional new replica server to be added to the cluster

Default value: undef

primary_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

Optional new primary PostgreSQL server to be added to the cluster

Default value: undef

replica_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

Optional new replica PostgreSQL server to be added to the cluster

Default value: undef

peadm::modify_certificate

Certificates can be modified by adding extensions, removing extensions, or setting DNS alternative names.

Parameters

The following parameters are available in the peadm::modify_certificate plan:

• targets
• primary_host
• add_extensions
• remove_extensions
• dns_alt_names
• force_regenerate

targets

Data type: TargetSpec

primary_host

Data type: Peadm::SingleTargetSpec

add_extensions

Data type: Hash

Default value: {}

remove_extensions

Data type: Array

Default value: []

dns_alt_names

Data type: Optional[Array]

Default value: undef

force_regenerate

Data type: Boolean

Default value: false

peadm::replace_failed_postgresql

Replaces a failed PostgreSQL host

Parameters

The following parameters are available in the peadm::replace_failed_postgresql plan:

• primary_host
• replica_host
• working_postgresql_host
• failed_postgresql_host
• replacement_postgresql_host

primary_host

Data type: Peadm::SingleTargetSpec

• The hostname and certname of the primary Puppet server

replica_host

Data type: Peadm::SingleTargetSpec

• The hostname and certname of the replica VM

working_postgresql_host

Data type: Peadm::SingleTargetSpec

• The hostname and certname of the still-working PE-PostgreSQL server

failed_postgresql_host

Data type: Peadm::SingleTargetSpec

• The hostname and certname of the failed PE-PostgreSQL server

replacement_postgresql_host

Data type: Peadm::SingleTargetSpec

• The hostname and certname of the server being brought in to replace the failed PE-PostgreSQL server

peadm::restore

Restore puppet primary configuration

Examples

bolt plan run peadm::restore -t primary1.example.com input_file=/tmp/peadm-backup.tar.gz

Parameters

The following parameters are available in the peadm::restore plan:

• targets
• restore_type
• restore
• input_file
• console_password

targets

Data type: Peadm::SingleTargetSpec

This should be the primary puppetserver for the puppet cluster

restore_type

Data type: Enum['recovery', 'recovery-db', 'custom', 'migration']

Choose from recovery, recovery-db and custom

Default value: 'recovery'

restore

Data type: Peadm::Recovery_opts

A hash of custom backup options, see the peadm::recovery_opts_default() function for the default values

Default value: {}

input_file

Data type: Pattern[/.*\.tar\.gz$/]

The file containing the backup to restore from

console_password

Data type: Optional[String]

Default value: undef

peadm::restore_ca

The peadm::restore_ca class.

Parameters

The following parameters are available in the peadm::restore_ca plan:

• target
• file_path
• recovery_directory

target

Data type: Peadm::SingleTargetSpec

file_path

Data type: String

recovery_directory

Data type: Optional[String]

Default value: '/tmp/peadm_recovery'

peadm::status

Return status information from one or more PE clusters in a table format

Examples

Using plan

peadm::status($targets, 'table', true, true)

Parameters

The following parameters are available in the peadm::status plan:

• targets
• format
• summarize
• verbose
• colors

targets

Data type: TargetSpec

These are a list of the primary puppetservers from one or multiple puppet stacks

format

Data type: Enum[json,table]

The output format to dump to stdout (json or table)

Default value: 'table'

summarize

Data type: Boolean

Controls the type of json output to render, defaults to true

Default value: true

verbose

Data type: Boolean

Toggles the output to show all the operationally services, can be loads more data

Default value: false

colors

Data type: Boolean

Toggles the usage of colors, you may want to disable if the format is json

Default value: $format ? { 'json' => false, default => true

peadm::upgrade

Upgrade a PEAdm-managed cluster

Parameters

The following parameters are available in the peadm::upgrade plan:

• compiler_pool_address
• internal_compiler_a_pool_address
• internal_compiler_b_pool_address
• pe_installer_source
• final_agent_state
• r10k_known_hosts
• stagingdir
• uploaddir
• begin_at_step
• primary_host
• replica_host
• compiler_hosts
• primary_postgresql_host
• replica_postgresql_host
• version
• token_file
• download_mode
• permit_unsafe_versions

compiler_pool_address

Data type: Optional[String]

The service address used by agents to connect to compilers, or the Puppet service. Typically this is a load balancer.

Default value: undef

internal_compiler_a_pool_address

Data type: Optional[String]

A load balancer address directing traffic to any of the "A" pool compilers. This is used for DR configuration in large and extra large architectures.

Default value: undef

internal_compiler_b_pool_address

Data type: Optional[String]

A load balancer address directing traffic to any of the "B" pool compilers. This is used for DR configuration in large and extra large architectures.

Default value: undef

pe_installer_source

Data type: Optional[Stdlib::HTTPSUrl]

The URL to download the Puppet Enterprise installer media from. If not specified, PEAdm will attempt to download PE installation media from its standard public source. When specified, PEAdm will download directly from the URL given.

Default value: undef

final_agent_state

Data type: Enum['running', 'stopped']

Configures the state the puppet agent should be in on infrastructure nodes after PE is upgraded successfully.

Default value: 'running'

r10k_known_hosts

Data type: Optional[Peadm::Known_hosts]

Puppet Enterprise 2023.3+ requires host key verification for the r10k_remote host when using ssh. you must provide \$r10k_known_hosts information in the form of an array of hashes with 'name', 'type' and 'key' information for hostname, key-type and public key.

Default value: undef

stagingdir

Data type: String

Directory on the Bolt host where the installer tarball will be cached if download_mode is 'bolthost' (default)

Default value: '/tmp'

uploaddir

Data type: String

Directory the installer tarball will be uploaded to or expected to be in for offline usage.

Default value: '/tmp'

begin_at_step

Data type: Optional[Peadm::UpgradeSteps]

The step where the plan should start. If not set, it will start at the beginning

Default value: undef

primary_host

Data type: Peadm::SingleTargetSpec

replica_host

Data type: Optional[Peadm::SingleTargetSpec]

Default value: undef

compiler_hosts

Data type: Optional[TargetSpec]

Default value: undef

primary_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

Default value: undef

replica_postgresql_host

Data type: Optional[Peadm::SingleTargetSpec]

Default value: undef

version

Data type: Optional[Peadm::Pe_version]

Default value: undef

token_file

Data type: Optional[String]

Default value: undef

download_mode

Data type: Peadm::Download_mode

Default value: 'bolthost'

permit_unsafe_versions

Data type: Boolean

Default value: false

peadm::util::init_db_server

The peadm::util::init_db_server class.

Parameters

The following parameters are available in the peadm::util::init_db_server plan:

• db_host
• install_pe
• pe_version
• pe_platform

db_host

Data type: String[1]

install_pe

Data type: Boolean

Default value: false

pe_version

Data type: String[1]

Default value: '2023.5.0'

pe_platform

Data type: String[1]

Default value: 'el-8-x86_64'

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v3.30.0 - 2025-06-27

Full Changelog

Added

• (PE-41546) add support for PE 2023.8.4 and 2025.4.0 #600 (davidmalloncares)

Other

• (PE-40391) Adding repo docs for migrate plan #589 (davidmalloncares)

v3.29.0 - 2025-05-14

Full Changelog

Added

• (RE-16872) add support for PE 2025.3.0 and 2023.8.3 #595 (davidmalloncares)
• (PE-41176) make migrate plan public #592 (davidmalloncares)

Fixed

• (PE-41341) Allow primary postgres host to be the failure #594 (davidmalloncares)

v3.28.0 - 2025-03-28

Full Changelog

Added

• (RE-16847) add support for PE 2025.2.0 #570 (davidmalloncares)

Other

• (PE-39577) Optimise legacy compiler support #536 (petergmurphy)
• (PE-39397) Adding LDAP endpoint for 2023.8 #515 (ragingra)

v3.27.0 - 2025-03-07

Full Changelog

Added

• (PE-40784) Add support for PE 2023.8.2 and 2025.1.0 #560 (davidmalloncares)
• (PE-40163) automate recovery of failed postgres server #537 (davidmalloncares)

Fixed

• (PE-40239) Adding check for missing legacy flag #547 (davidmalloncares)

Other

• (PE-40691) document automated steps for failed postgres and adding compilers #554 (davidmalloncares)

v3.26.1 - 2025-01-23

Full Changelog

Added

• (PE-40187) Add support for PE 2023.8.1 #538 (davidmalloncares)

v3.26.0 - 2024-12-16

Full Changelog

Added

• (PE-39891) Add support for PE 2025 #533 (jhbuchanan45)
• Add support for bolt 4.x #529 (bastelfreak)
• (PE-39352) Add version to get peadm config #527 (jpartlow)

Fixed

• puppet_runonce: redirect stderr to stdout #523 (bastelfreak)
• Check for curl failure #521 (seanmil)

Other

• (PE-38076) Remove unused bolt_shim and apply_helpers modules #518 (jhbuchanan45)

v3.25.1 - 2024-10-24

Full Changelog

Added

• (PE-39411) Add descriptive error during infrastructure upgrade when rbac token is invalid #514 (jhbuchanan45)
• (PE-39412) PEADM should be able to add multiple compilers at once without requiring service restarts on Primary #512 (CoMfUcIoS)
• PE-38801 Task added to fetch rules for PE Infrastructure Agent group and warn user that they will be replaced #510 (AaronShannon)

Fixed

• fix: echo environment variable containing special char #516 (LordKa0S)
• (PE-39429) Only restart puppetdb on non-legacy compilers #511 (jhbuchanan45)

v3.25.0 - 2024-09-30

Full Changelog

Added

• Adding support for legacy compilers (#448) #495 (CoMfUcIoS)

v3.24.0 - 2024-09-20

Full Changelog

Added

• (PE-39118) Adding code manager check to add_replica #501 (ragingra)

v3.23.0 - 2024-09-12

Full Changelog

Added

• (PE-37233-35) Official support of Add compiler plan #485 (CoMfUcIoS)
• (PE-38815-18) Official support of Add replica plan #484 (CoMfUcIoS)

Other

• PE-39228 add_replica smoke test #497 (AaronShannon)
• (PE-38817) Text fixes for add_replica docs #496 (ragingra)
• (PE-39224) Adding random console password for forked pr workflow #491 (ragingra)

v3.22.0 - 2024-09-03

Full Changelog

Fixed

• (#469) Assign correct environment to node groups #479 (bastelfreak)
• pe_installer_source: Use Stdlib::HTTPSUrl datatype #466 (bastelfreak)

Other

• (PE-38769) Task/Plan to identify conflicting classifications on legacy compilers and warn the user #483 (CoMfUcIoS)
• PE-38815 add_replica plan updated, test matrix added #480 (AaronShannon)
• (PE-38818) Removing experimental and private from add_replica #478 (ragingra)
• (PE-38771) Convert plan accepts legacy compilers key in params.json #476 (CoMfUcIoS)
• (PE-38770) Install Plan accepts legacy_compilers key #474 (CoMfUcIoS)
• (PE-38814) add_compiler - Making primary_postgresql_host and avail_group_letter optional #468 (ragingra)
• PE-38768 classify compilers task added #467 (AaronShannon)
• (PE-38767) Adding legacy compilers to get_peadm_config #456 (ragingra)
• PE-38772 Node groups added for legacy compilers #455 (AaronShannon)
• Adding support for legacy compilers #448 (ragingra)
• (PE-37235) Verify and update documentation on add_compiler #429 (cathal41)

v3.21.0 - 2024-07-15

Full Changelog

Added

• PE-38219 - Support air gapped installation while using a Windows as Jump host #438 (cathal41)

v3.20.0 - 2024-07-01

Full Changelog

Added

• Add backup/restore plans #339 (timidri)

Other

• [ITHELP-87329] Update test-backup-restore.yaml #447 (binford2k)
• [ITHELP-87329] Update test-backup-restore.yaml #446 (binford2k)
• (PE-37233) Adding add_compiler to test matrix #434 (ragingra)
• Update backup_restore.md #432 (J-Hunniford)

v3.19.0 - 2024-05-08

Full Changelog

v3.18.1 - 2024-04-17

Full Changelog

v3.18.0 - 2024-04-04

Full Changelog

v3.17.0 - 2024-02-07

Full Changelog

Other

• add environment parameter to puppet_runonce task #402 (vchepkov)

v3.16.1 - 2023-11-23

Full Changelog

Other

• (PE-37192) Updating default install version to 2021.7.6 #406 (ragingra)
• (MAINT) Update release_process.md #405 (Jo-Lillie)

v3.16.0 - 2023-11-08

Full Changelog

Added

• (PE-35906) Adding plans for backing up and restoring CA #400 (ragingra)

Fixed

• peadm::install: Depend code-manager setup on r10k remote presence, not r10k ssh key #401 (bastelfreak)

v3.15.1 - 2023-10-10

Full Changelog

Added

• (#351) code_manager: Switch default to undef #352 (bastelfreak)

Fixed

• Fix for plan peadm::add_compiler over pcp transport #356 (jortencio)

v3.15.0 - 2023-10-06

Full Changelog

Added

• support configurable installer target upload path #376 (h0tw1r3)

v3.14.0 - 2023-09-15

Full Changelog

Added

• (PE-36789) R10k Known hosts upgrade path #382 (ragingra)
• (PE-36580) Add r10k_known_hosts to install plan #380 (jpartlow)

v3.13.1 - 2023-06-27

Full Changelog

v3.13.0 - 2023-06-26

Full Changelog

Added

• Adding /etc/puppetlabs/enterprise/conf.d/pe.conf #346 (16c7x)
• Allow code manager auto configure to be passed as param #341 (elainemccloskey)

v3.12.0 - 2023-02-17

Full Changelog

Added

• Remove experimental backup/restore plans #337 (timidri)

Fixed

• Fix group letter assignments during upgrade #336 (timidri)

v3.11.1 - 2023-02-10

Full Changelog

Added

• add parameter for setting final state of infrastructure agents after upgrade #330 (vchepkov)

Fixed

• fix variable notation #331 (vchepkov)

v3.11.0 - 2023-02-01

Full Changelog

Added

• Fail with guidance if peadm::util::retrieve_and_upload is used on PE XL with the PCP transport #317 (Sharpie)

v3.10.0 - 2023-02-01

Full Changelog

Added

• Adding windows node capability #307 (davidsandilands)
• Parameter for setting final state of agents #305 (ody)

Fixed

• Fix XL failures in finalize step of peadm::convert #315 (Sharpie)
• Sync FIPS detection with the PE installer #310 (Sharpie)

v3.9.0 - 2022-09-23

Full Changelog

Fixed

• Ensure fips commands exists before using it #289 (ody)
• Fix-ups in copy_file plan usage #282 (ody)
• Re-use sync_global_hiera plan #281 (ody)
• Support the installation of PE on FIPS enabled RHEL #280 (ody)
• Fetch installed PSQL version #275 (ody)

Other

• allow to customize admin's token lifetime #285 (vchepkov)

v3.8.0 - 2022-06-21

Full Changelog

Added

• Fix classification when adding some components #258 (ody)
• Add task and update configure plan to allow for ldap configuration on… #253 (bwilcox)

Fixed

• Restart compiler services #271 (ody)
• Set additional rules on replica when adding compiler #270 (ody)
• Updates documentation #269 (ody)

v3.7.0 - 2022-05-11

Full Changelog

Added

• Add optional pe_installer_source parameter #261 (reidmv)
• Support PE 2021.6 and 2019.8.11 #260 (reidmv)
• Add experimental restore plan #250 (reidmv)

v3.6.0 - 2022-05-04

Full Changelog

Added

• Add experimental backup plan #235 (davidsandilands)

Fixed

• Add read map so puppetdb can start on new compiler #252 (ody)
• Fix and document recovery procedure for PSQL #243 (ody)

v3.5.0 - 2022-04-13

Full Changelog

Added

• Add support for SLES 12 #245 (MartyEwings)
• Add peadm::add_database plan #241 (ody)
• Add experimental peadm::util::code_sync_status plan #221 (reidmv)

Fixed

• Fix json escaping in bash_task_helper #246 (reidmv)
• Fix load balancer bug in peadm::get_peadm_config task #244 (reidmv)

v3.4.0 - 2022-03-08

Full Changelog

Added

• Allow compilers and replicas to merge csr_attributes. #238 (bwilcox)
• Add support for PE 2021.5 #237 (reidmv)
• Improve handling of unsuitable LANG settings #236 (reidmv)
• Add peadm::backup plan #226 (davidsandilands)

Fixed

• Make versions match SemVer pattern #232 (reidmv)

v3.3.0 - 2022-01-05

Full Changelog

Added

• Support PE 2021.4 #229 (reidmv)
• Add development and testing option to permit installing unsupported PE versions #204 (jarretlavallee)

Fixed

• Fail agent_install if agent is already installed #223 (reidmv)
• Catch mv errors when downloading #220 (reidmv)
• Determine validation key from asc signature file #219 (reidmv)
• Improve reliability of downloading PE tarball #215 (mcka1n)

v3.2.0 - 2021-09-20

Full Changelog

Added

• Add auto-generated REFERENCE.md documentation #211 (reidmv)
• Make PEAdm a Puppet supported module #199 (ody)

Fixed

• Update documentation to reference supported PE version #213 (reidmv)
• Fix output of peadm::status when used with multiple clusters #209 (reidmv)

v3.1.0 - 2021-09-10

Full Changelog

Added

• Support PE 2021.3 #203 (reidmv)
• Add PE download signature checking #201 (timidri)
• Add task to report on code synchronization status #196 (davidsandilands)
• Add an experimental peadm::uninstall plan #195 (mcka1n)
• Remove hardcoded default memory configuration #194 (reidmv)
• Highlight user-facing plans by hiding internal plans from bolt plan show output #189 (reidmv)
• Add get_peadm_config task #187 (reidmv)
• Replace plan peadm::modify_cert_extensions with peadm::modify_certificate #181 (reidmv)

Fixed

• Fix upgrade without replica #198 (reidmv)
• Fix upgrade bug for token files with newlines #193 (reidmv)
• Move load_balancer class to examples #183 (reidmv)
• Fix GitHub README.md problem #182 (reidmv)

v3.0.1 - 2021-06-30

Full Changelog

Fixed

• Add missing parenthesis to add_compiler plan #177 (timidri)
• Use absolute links so they render properly on the Forge #175 (binford2k)

v3.0.0 - 2021-06-29

Full Changelog

Changed

• Global rename of primary/replica and postgresql parameters #161 (timidri)
• Language and terminology updates #153 (davidsandilands)

Added

• Update workflow PE defaults to latest LTS #170 (reidmv)
• Add add_replica plan #166 (timidri)
• Support latest PE release #157 (ody)
• Add add_compiler plan #154 (timidri)

Fixed

• Resolving linting issues #165 (davidsandilands)
• Fix installer exit handling #152 (reidmv)

Other

• Release 2.5.0 #149 (reidmv)

2.5.0 - 2021-03-23

Full Changelog

Other

• PE 2021.0 support #146 (reidmv)
• Added modules to bolt-project. Removed Puppetfile #145 (bryanjbelanger)
• Ensure locales are set to en_US.UTF-8 for install #144 (kreeuwijk)
• fix documented parameters for peadm::install plan #143 (vchepkov)
• Adds testing for validate_version #142 (logicminds)
• Add bolt_version function and use it in plans #141 (timidri)
• Infra upgrade improvement #139 (reidmv)
• Use node_manager's new purge_behavior parameter #134 (reidmv)

2.4.5 - 2020-12-23

Full Changelog

Other

• Fix a problem with Peadm::SingleTargetSpec #138 (reidmv)
• Make puppet_runonce exit non-zero on resrc failure #137 (reidmv)
• Fix bug in convert plan version validation #136 (reidmv)

2.4.4 - 2020-11-19

Full Changelog

2.4.3 - 2020-11-13

Full Changelog

Other

• GH-130 Fix overwrite of user config data #132 (reidmv)

2.4.2 - 2020-11-02

Full Changelog

Other

• GH-130 Fix overwrite of user config data #132 (reidmv)

2.4.1 - 2020-09-26

Full Changelog

Other

• Fix upgrade peconf #129 (reidmv)

2.4.0 - 2020-09-23

Full Changelog

Other

• Don't re-issue certs if they have required exts #128 (reidmv)
• Add support clause and instructions to README #127 (reidmv)

2.3.0 - 2020-09-22

Full Changelog

Other

• Plan steps #126 (reidmv)
• Bug fixes to convert #125 (reidmv)

2.2.1 - 2020-09-17

Full Changelog

2.2.0 - 2020-09-17

Full Changelog

Other

• Eliminate convert configure_node_groups param #124 (reidmv)
• Add informational messages to upgrade plan #123 (reidmv)
• Wait until nodes connected before infra upgrade #122 (reidmv)
• Add compilerpool{a,b}_address parameters #121 (reidmv)
• Set ha_enabled_replicas to an empty array for compilers #120 (reidmv)
• Add service module #115 (logicminds)

2.1.1 - 2020-08-13

Full Changelog

Other

• Docker inventory refactor #114 (logicminds)
• Remove support team responsibilities in README #113 (nigelkersten)
• Fix #110 - peadm::status plan fails with new bolt version #111 (logicminds)

0.4.3 - 2020-07-08

Full Changelog

Other

• #106 fix permissions on the key files #108 (vchepkov)

2.1.0 - 2020-07-07

Full Changelog

Other

• Update validate_version.pp #104 (bryanjbelanger)
• use platform-python on RHEL8 #102 (vchepkov)
• Upgrade from 2018 #101 (reidmv)
• (maint) Update Puppet VS Code Extension ID #100 (jpogran)

2.0.0 - 2020-05-29

Full Changelog

1.2.0 - 2020-05-29

Full Changelog

Other

• Backport docker examples for 2018 #99 (logicminds)
• Docker updates #98 (logicminds)
• Add direct download option for PE installers #97 (Sharpie)
• Re-implement ad6ae240 without behavior change #96 (reidmv)
• Revert "made print() call Py3 compliant, added checks for Py execs" #95 (ody)

1.1.0 - 2020-05-14

Full Changelog

Other

• made print() call Py3 compliant, added checks for Py execs #94 (rajeshr264)
• Improve error handling of peadm::download task #92 (Sharpie)
• Add explicit help instructions to README #91 (trlinkin)
• Adds some basic tests for functions #90 (logicminds)
• Adds ability to audit bolt files #89 (logicminds)
• (feat) Add stack status task and plan #88 (logicminds)
• Provide mv wrapper task #86 (reidmv)

1.0.1 - 2020-04-02

Full Changelog

Other

• Pin master to PE Database group #85 (reidmv)
• Reduce several check tasks down to one #84 (reidmv)
• Fix incorrect task name in install plan #83 (logicminds)
• Add docker support for experimentation #81 (logicminds)
• Add wait function during install #80 (logicminds)
• Add check status tasks #79 (logicminds)
• Make cert tasks more idempotent #78 (logicminds)
• Use custom OIDs for peadm role and avil. group #76 (reidmv)

1.0.0 - 2020-03-27

Full Changelog

Other

• Rework upgrade sequence to support Standard arch #77 (reidmv)
• Fail peadm::pe_install task when installer fails #75 (reidmv)
• Set certnames to target names #72 (reidmv)
• updated the agent_install.sh file sed statement for installation flag… #70 (chrislorro)
• Update function to accept either string or undef data type. #66 (bwilcox)
• Node manager switch #64 (bwilcox)
• Eliminate default private key parameter value #62 (reidmv)
• Manage license file #61 (abrader)
• Node manager fix #60 (bwilcox)
• basework for https://github.com/puppetlabs/puppetlabs-peadm/issues/50 #52 (abuxton)

0.5.2 - 2020-01-30

Full Changelog

0.4.2 - 2020-01-30

Full Changelog

0.5.1 - 2020-01-29

Full Changelog

0.4.1 - 2020-01-29

Full Changelog

0.5.0 - 2020-01-27

Full Changelog

Other

• Modernize Upgrade Plan #56 (reidmv)
• Add support for Ubuntu platform #54 (reidmv)
• configure classifier data in global hiera.yaml #44 (tkishel)
• Make CSR submission version-aware #43 (reidmv)
• Re-add use of raw OIDs to csr_attribute.yaml files #38 (reidmv)
• Rename subdirectory "unit" to "action" #37 (reidmv)
• Partially revert #35 #36 (reidmv)
• Update parameter for puppetdb_database_host #35 (npwalker)
• Deploy combined with GCP, macOS, Terraform #34 (ody)
• Remove use of pp_role #33 (reidmv)
• Added "if" to not run CA sign on empty certname #32 (spidersddd)
• Rename module to puppetlabs-peadm #31 (reidmv)
• Use node group apply #28 (reidmv)

0.4.0 - 2019-11-12

Full Changelog

Other

• Changed for more reliable hostname resolution #27 (dylanratcliffe)
• V4 #26 (reidmv)
• Added ability fo fully bootstrap Code manager #25 (dylanratcliffe)
• Removed local:// dependency for upgrades #24 (dylanratcliffe)
• SLV-366 Make external database host optional #23 (johnduarte)
• (SLV-365) Update the install, configure, and upgrade plans in the pe_xl module to make ha optional #21 (billclaytor)

0.2.3 - 2019-07-12

Full Changelog

Other

• Stop managing environments #18 (reidmv)

0.2.2 - 2019-02-15

Full Changelog

0.2.1 - 2019-02-07

Full Changelog

0.2.0 - 2019-02-06

Full Changelog

Other

• add variable to mark a node as the replica (required for other modules to only configure webhooks on the current primary) #16 (uphillian)
• name translation not working to the bash script #14 (spidersddd)
• Adding tokenfile option #13 (spidersddd)

0.1.0 - 2018-09-27

Full Changelog