Installing PE
To install Puppet Enterprise (PE), you must first set up a standard installation. From there, you can scale up to the large or extra-large installation as your infrastructure grows, or customize your configuration as needed.
- The primary server: The central hub of activity. It is where Puppet code is compiled to create agent catalogs and where SSL certificates are verified and signed.
- The console: The graphical web user interface. It has configuration and reporting tools.
- PuppetDB: The data store for data generated throughout your Puppet infrastructure.
sudo
.To install a FIPS-enabled PE primary server, install the
appropriate FIPS-enabled PE tarball (such as puppet-enterprise-2023.1.0-redhatfips-7-x86_64.tar
) on a third-party Supported operating
system with FIPS mode enabled. The node must be configured
with sufficient available entropy for the installation process to
succeed.
Verify the installation package
These steps are only required if your organization requires you to verify authenticity before installing packages. These steps explain how to use GnuPG (GPG) to verify the PE installation tarball.
yum install gnupg
gpg --verify
command returns something similar
to:gpg: Signature made <DATE_AND_TIME>
gpg: using RSA key <KEY_ID>
gpg: Good signature from "Puppet, Inc. Release Key (Puppet, Inc. Release Key) <release@puppet.com>"
If you receive a warning that a valid key path couldn't be found, this means you don't have a trusted path to one of the signatures on the release key.
If you receive a warning that the key is not certified with a trusted signature, this means you haven't told GPG to trust the imported key. Refer to the GPG documentation for more information.
Install PE
The Puppet Enterprise (PE) installer uses default settings to install PE infrastructure components on a single node. After installing, you can scale or customize your installation as needed.
Review the Hardware requirements for standard installations to make sure your system capacity can handle the standard PE installation.
Log in as root on your target primary server. If you're installing on a system that
doesn't allow root login, you must use sudo su -
to
complete these steps.
Configuration parameters and the pe.conf
file
A pe.conf
file is a HOCON formatted file that declares parameters and
values used to install, upgrade, or configure Puppet Enterprise (PE). A
default pe.conf
file is available in the conf.d
directory in
the installer tarball.
pe.conf
file when installing PE by running: ./puppet-enterprise-installer -c
<PATH_TO_pe.conf>
pe.conf
file,
along with examples of each type:Type | Parameter-value format example |
---|---|
FQDN |
"puppet_enterprise::puppet_master_host":
"primary.example.com"
|
String |
"console_admin_password": "mypassword"
|
Array |
[ "puppet", "puppetlb-01.example.com" ]
|
Boolean |
"puppet_enterprise::profile::orchestrator::run_service":
true
Restriction: The only valid Boolean values are
true and false . These are not
case sensitive, and these are the only values that don't use quotation
marks. Don't use Yes (y) , No (n) , 1 ,
or 0 for Booleans. |
JSON hash |
"puppet_enterprise::profile::orchestrator::java_args": {"Xmx":
"256m", "Xms": "256m"}
|
Integer |
"puppet_enterprise::profile::console::rbac_session_timeout":
"60"
|
"
) around parameter values.Installation parameters
These parameters must be present in the pe.conf
file
to install Puppet Enterprise (PE).
puppet_enterprise::puppet_master_host
- Specify the FQDN of the node hosting your PE
primary server, such as
primary.example.com
.
Database configuration parameters
These parameters and values are supplied for Puppet Enterprise (PE) databases.
puppet_enterprise::activity_database_name
- The activity database name.
puppet_enterprise::activity_database_read_user
- An activity database user that can perform only read functions.
puppet_enterprise::activity_database_write_user
- An activity database user that can perform read and write functions.
puppet_enterprise::activity_database_super_user
- The activity database superuser.
puppet_enterprise::activity_service_migration_db_user
- An activity service database user used for migrations.
puppet_enterprise::activity_service_regular_db_user
- An activity service database user used for normal operations.
puppet_enterprise::classifier_database_name
- The classifier database name.
puppet_enterprise::classifier_database_read_user
- A classifier database user that can perform only read functions.
puppet_enterprise::classifier_database_write_user
- A classifier database user that can perform read and write functions.
puppet_enterprise::classifier_database_super_user
- The classifier database superuser.
-
puppet_enterprise::classifier_service_migration_db_user
- A classifier service user used for migrations.
-
puppet_enterprise::classifier_service_regular_db_user
- A classifier service user used for normal operations.
puppet_enterprise::orchestrator_database_name
- The orchestrator database name.
puppet_enterprise::orchestrator_database_read_user
- An orchestrator database user that can perform only read functions.
puppet_enterprise::orchestrator_database_write_user
- An orchestrator database user that can perform read and write functions.
puppet_enterprise::orchestrator_database_super_user
- The orchestrator database superuser.
puppet_enterprise::orchestrator_service_migration_db_user
- An orchestrator service user used for migrations.
puppet_enterprise::orchestrator_service_regular_db_user
- An orchestrator service user used for normal operations.
puppet_enterprise::puppetdb_database_name
- The PuppetDB database name.
puppet_enterprise::puppetdb_database_user
- The PuppetDB database user.
puppet_enterprise::rbac_database_name
- The role-based access control (RBAC) database name.
puppet_enterprise::rbac_database_read_user
- An RBAC database user that can perform only read functions.
puppet_enterprise::rbac_database_write_user
- An RBAC database user that can perform read and write functions.
puppet_enterprise::rbac_database_super_user
- The RBAC database superuser.
puppet_enterprise::rbac_service_migration_db_user
- An RBAC service user used for migrations.
puppet_enterprise::rbac_service_regular_db_user
- An RBAC service user used for normal operations.
External PostgreSQL parameters
These parameters are required to install an external PostgreSQL instance. If necessary, you can add password parameters to standard installations.
puppet_enterprise::database_host
- The agent certname of the node hosting the database component.
-
puppet_enterprise::database_port
- The port that the database is running on.
puppet_enterprise::database_ssl
- A Boolean indicating whether SSL authentication is used.
puppet_enterprise::database_cert_auth
- A Boolean indicating whether certificate authentication is used.
puppet_enterprise::puppetdb_database_password
- Specify a password, as a string, for the PuppetDB database user.
puppet_enterprise::classifier_database_password
- Specify a password, as a string, for the classifier database user.
puppet_enterprise::classifier_service_regular_db_user
- A database user the classifier service can use for normal operations.
puppet_enterprise::classifier_service_migration_db_user
- A database user the classifier service can use for migrations.
puppet_enterprise::activity_database_password
- Specify a password, as a string, for the activity database user.
puppet_enterprise::activity_service_regular_db_user
- A database user the activity service can use for normal operations.
puppet_enterprise::activity_service_migration_db_user
- A database user the activity service can use for migrations.
puppet_enterprise::rbac_database_password
- Specify a password, as a string, for the RBAC database user.
puppet_enterprise::rbac_service_regular_db_user
- A database user the RBAC service can use for normal operations.
puppet_enterprise::rbac_service_migration_db_user
- A database user the RBAC service can use for migrations.
puppet_enterprise::orchestrator_database_password
- Specify a password, as a string, for the orchestrator database user.
puppet_enterprise::orchestrator_service_regular_db_user
- A database user the orchestrator service can use for normal operations.
puppet_enterprise::orchestrator_service_migration_db_user
- A database user the orchestrator service can use for migrations.
Primary server parameters
Use these parameters to configure and tune the primary server.
pe_install::puppet_master_dnsaltnames
- An array of strings representing DNS altnames to add to the primary server's SSL certificate.
pe_install::install::classification::pe_node_group_environment
- A string indicating the environment that infrastructure nodes are running in.
puppet_enterprise::ip_version
- Accepts either
4
or6
to specify a preference for IPv4 or IPv6, but this does not restrict the non-preferred option. puppet_enterprise::ipv6_only
- You can set this to
true
to force NGINX to listen only on IPv6. puppet_enterprise::master::recover_configuration::pe_environment
- A string indicating the environment that infrastructure nodes are running in.
puppet_enterprise::profile::certificate_authority
- An array of additional certificates to be allowed access to the
/certificate_statusAPI
endpoint. This list is added to the base certificate list. puppet_enterprise::profile::master::check_for_updates
- A Boolean indicating whether to check for updates when the
pe-puppetserver
service restarts. puppet_enterprise::profile::master::code_manager_auto_configure
- Set to
true
to automatically configure the Code Manager service; otherwise, set it tofalse
. puppet_enterprise::profile::master::r10k_remote
- A string representing the Git URL to be
passed to the
r10k.yaml
file, for example:git@your.git.server.com:puppet/control.git
puppet_enterprise::profile::master::r10k_private_key
- A string representing the local file path on the primary server where the
SSH private key can be found and used by r10k, for example:
/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519
Console and console-services
parameters
In the PE Console node group, these parameters customize the
behavior of the console and the console-services
service.
You can modify parameters that begin with
puppet_enterprise::profile
in the PE console.
puppet_enterprise::profile::console::classifier_synchronization_period
- An integer representing, in seconds, the classifier synchronization period. This controls how long the node classifier can take to retrieve classes from the primary server.
puppet_enterprise::profile::console::ldap_sync_period_seconds
- An integer specifying, in seconds, the interval at which LDAP user details and group membership associations are synchronized.
puppet_enterprise::profile::console::rbac_failed_attempts_lockout
- An integer specifying how many failed login attempts are allowed on an account before the account is revoked.
puppet_enterprise::profile::console::rbac_password_reset_expiration
- An integer representing the number of hours that password reset tokens are valid.
puppet_enterprise::profile::console::rbac_session_timeout
- An integer representing, in minutes, how long a user's session can last.
puppet_enterprise::profile::console::session_maximum_lifetime
- An string representing how long a console session can last.
puppet_enterprise::profile::console::rbac_token_auth_lifetime
- A string representing the default authentication lifetime for a token.
puppet_enterprise::profile::console::rbac_token_maximum_lifetime
- A string representing the maximum allowable lifetime for all tokens.
puppet_enterprise::profile::console::console_ssl_listen_port
- An integer representing the port that the console listens on.
puppet_enterprise::profile::console::ssl_listen_address
- A string containing an IP address repesenting the console's NGINX listen address.
puppet_enterprise::profile::console::classifier_prune_threshold
- An integer representing the number of days to wait before pruning the node
classifier database. The node classifier database contains node check-in
history if
classifier_node_check_in_storage
is enabled. puppet_enterprise::profile::console::classifier_node_check_in_storage
- A Boolean specifying whether to create records when nodes check in with the node classifier. These records describe how nodes match the node groups they're classified into.
puppet_enterprise::profile::console::display_local_time
- A Boolean indicating whether to show timestamps in the local time or UTC.
puppet_enterprise::profile::console::disclaimer_content_path
- Specifies the location of the
disclaimer.txt
file containing disclaimer content that can appear on the console login page if you Create a custom login disclaimer.
pe.conf
, not the console:puppet_enterprise::api_port
- An integer specifying the SSL port that the node classifier is served on.
puppet_enterprise::console_services::no_longer_reporting_cutoff
- Length of time, in seconds, before a node is considered unresponsive.
console_admin_password
- The password to log into the console as the admin.
Orchestrator and orchestration services parameters
Use these parameters to configure and tune the orchestrator and orchestration services.
puppet_enterprise::profile::agent::pxp_enabled
- Boolean used to enable or disable the Puppet Execution Protocol (PXP) service.
puppet_enterprise::profile::bolt_server::concurrency
- An integer that determines the maximum number of simultaneous task or
plan requests the orchestrator can make to
bolt-server
. puppet_enterprise::profile::orchestrator::global_concurrent_compiles
- An integer specifying how many concurrent compile requests can be outstanding to the primary server across all orchestrator jobs.
puppet_enterprise::profile::orchestrator::job_prune_threshold
- An integer of
2
or greater, which specifies the number of days to retain job reports. puppet_enterprise::profile::orchestrator::pcp_timeout
- An integer representing how long, in seconds, an agent can spend attempting to connect to a PCP broker during a Puppet run triggered by the orchestrator. If the agent can’t connect to the broker in the specified time frame, the Puppet run times out.
puppet_enterprise::profile::orchestrator::run_service
- A Boolean used to enable (
true
) or disable (false
) orchestration services. puppet_enterprise::profile::orchestrator::task_concurrency
- An integer representing the number of simultaneous task or plan actions that can run at the same time. All task and plan actions are limited by this concurrency limit regardless of transport type (WinRM, SSH, PCP).
puppet_enterprise::pxp_agent::ping_interval
- An integer specifying the frequency, in seconds, that PXP agents ping PCP brokers. If the broker doesn't respond, the agent tries to reconnect.
puppet_enterprise::pxp_agent::pxp_logfile
- The path, as a string, to the PXP agent log file. This file can be used to debug orchestrator issues.
puppet_enterprise::profile::orchestrator::allowed_pcp_status_requests
- An integer that defines how many times an orchestrator job allows status
requests to time out before a job is considered failed. Status requests
wait 12 seconds between timeouts, so multiply the value of the
allowed_pcp_status_requests
by 12 to determine how many seconds the orchestrator waits on targets that aren’t responding to status requests. puppet_enterprise::profile::orchestrator::default_plan_timeout
- An integer specifying how long a plan can run before being force
stopped. This represents a timeout limit for the entire plan, not
individual plan jobs.CAUTION: Force stopping plans can result in incomplete Puppet runs, partial configuration changes, and other issues. When setting the default timeout limit, consider average plan scope, run time, and your infrastructure's capacity (such as concurrency limits).
puppet_enterprise::profile::orchestrator::default_task_node_timeout
- An integer specifying how many seconds a task can run on a single node
before being force stopped.CAUTION: Force stopping tasks can result in incomplete Puppet runs, partial configuration changes, and other issues. When setting the default timeout limit, consider average task scope, run time, and your infrastructure's capacity (such as concurrency limits).
puppet_enterprise::profile::orchestrator::java_args
- Specifies the Java heap size, which is the amount of JVM memory that each Java process is allowed to request from the OS for orchestration services to use.
puppet_enterprise::profile::orchestrator::jruby_max_active_instances
- An integer that determines the maximum number of JRuby instances that
the orchestrator creates to execute plans. Because each plan uses one
JRuby to run, this value is effectively the maximum number of concurrent
plans. Setting the orchestrator heap size (
java_args
) automatically sets thejruby_max_active_instances
using the formula$java_args ÷ 1024
. If the result is less than one, the default is one JRuby instance. puppet_enterprise::profile::plan_executor::versioned_deploys
- A Boolean used for Running plans alongside code deployments.
PuppetDB parameters
Use these parameters to configure and tune PuppetDB.
puppet_enterprise::profile::master::puppetdb_host
- An array containing a string representing the certname of the node running the PuppetDB service, which is usually the primary server.
-
puppet_enterprise::profile::master::puppetdb_port
- An array containing an integer representing the SSL port that PuppetDB listens on.
puppet_enterprise::profile::master::puppetdb::report_processor_ensure
- Specifies if you want the primary server to generate agent run reports after each Puppet run.
-
puppet_enterprise::profile::puppetdb::node_purge_ttl
- Set the length of time before PE automatically removes deactivated or expired nodes, along with their facts, catalogs, and reports, from PuppetDB.
puppet_enterprise::puppetdb::command_processing_threads
- Integer representing how many command processing threads PuppetDB uses to sort incoming data. Each thread can process one command at a time.
Java parameters
Use these parameters to configure and tune Java.
-
puppet_enterprise::profile::master::java_args
- JVM (Java Virtual Machine) memory, specified as a JSON hash, that is allocated to the
Puppet Server service, for example
{"Xmx": "4096m", "Xms": "4096m"}
. -
puppet_enterprise::profile::puppetdb::java_args
- JVM memory, specified as a JSON hash, that is allocated to the PuppetDB service, for example
{"Xmx": "512m", "Xms": "512m"}
. -
puppet_enterprise::profile::console::java_args
- JVM memory, specified as a JSON hash, that is allocated to console services, for
example
{"Xmx": "512m", "Xms": "512m"}
. -
puppet_enterprise::profile::orchestrator::java_args
- JVM memory, set as a JSON hash, that is allocated to orchestration services, for
example,
{"Xmx": "256m", "Xms": "256m"}
.