REFERENCE.md

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::migration_opts_default
• peadm::node_manager_yaml_location
• peadm::oid
• 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::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
• 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
• 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
• 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::modify_certificate: Modify the certificate of one or more targets
• 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::update_compiler_extensions
• 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::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::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::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::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 get_targets() 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

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

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

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

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

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

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: '2021.7.9'

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: Enum['direct', 'bolthost']

Default value: 'bolthost'

permit_unsafe_versions

Data type: Boolean

Default value: false

token_lifetime

Data type: String

Default value: '1y'

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

targets

Data type: Peadm::SingleTargetSpec

This should be the primary puppetserver for the puppet cluster

restore_type

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

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

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: Enum[direct,bolthost]

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'