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-2021.6.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 cctivity database user that can perform only 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 only 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 only 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::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 only 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
Use these parameters to customize the behavior of the console and console-services in
the PE Console node group. Parameters that begin with
puppet_enterprise::profile
can be modified from the console itself.
-
puppet_enterprise::profile::console::classifier_synchronization_period
- Integer representing, in seconds, the classifier synchronization period, which controls how long it takes the node classifier to retrieve classes from the primary server.
-
puppet_enterprise::profile::console::rbac_failed_attempts_lockout
- Integer specifying how many failed login attempts are allowed on an account before that account is revoked.
-
puppet_enterprise::profile::console::rbac_password_reset_expiration
- Integer representing, in hours, how long a user's generated token is valid for. An administrator generates this token for a user so that they can reset their password.
-
puppet_enterprise::profile::console::rbac_session_timeout
- Integer representing, in minutes, how long a user's session can last. The session length is the same for node classification, RBAC, and the console.
-
puppet_enterprise::profile::console::session_maximum_lifetime
- Integer representing the maximum allowable period that a console session can be valid. To not expire before the maximum token lifetime, set to '0'.
puppet_enterprise::profile::console::rbac_token_auth_lifetime
- A value representing the default authentication lifetime for a token. It
cannot exceed the
rbac_token_maximum_lifetime
. This is represented as a numeric value followed by "y" (years), "d" (days), "h" (hours), "m" (minutes), or "s" (seconds). The default is "1h". puppet_enterprise::profile::console::rbac_token_maximum_lifetime
- A value representing the maximum allowable lifetime for all tokens. This is represented as a numeric value followed by "y" (years), "d" (days), "h" (hours), "m" (minutes), or "s" (seconds). The default is "10y".
-
puppet_enterprise::profile::console::console_ssl_listen_port
- Integer representing the port that the console is available on.
-
puppet_enterprise::profile::console::ssl_listen_address
- Nginx listen address for the console.
-
puppet_enterprise::profile::console::classifier_prune_threshold
- Integer representing the number of days to wait before pruning the size of
the classifier database. If you set the value to
0
, the node classifier service is never pruned. -
puppet_enterprise::profile::console::classifier_node_check_in_storage
-
true
to store an explanation of how nodes match each group they're classified into, orfalse
. -
puppet_enterprise::profile::console::display_local_time
-
"true"
to display timestamps in local time, with hover text showing UTC time, or"false"
to show timestamps in UTC time. puppet_enterprise::profile::console::disclaimer_content_path
- Specifies the location of the
disclaimer.txt
file, which contains the disclaimer content that appears on the console login page.
pe.conf
, not the console:-
puppet_enterprise::api_port
- 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, for example
"myconsolepassword"
.
Orchestrator and orchestration services parameters
Use these parameters to configure and tune the orchestrator and orchestration services.
-
puppet_enterprise::profile::agent::pxp_enabled
-
true
to enable the Puppet Execution Protocol service, which is required to use the orchestrator and run Puppet from the console, orfalse
. -
puppet_enterprise::profile::bolt_server::concurrency
- An integer that determines the maximum number of
concurrent requests orchestrator can make to bolt-server. CAUTION: Do not set a concurrency limit that is higher than the bolt-server limit. This can cause timeouts that lead to failed task runs.
-
puppet_enterprise::profile::orchestrator::global_concurrent_compiles
- Integer representing how many concurrent compile requests can be outstanding to the primary server, across all orchestrator jobs.
-
puppet_enterprise::profile::orchestrator::job_prune_threshold
- Integer representing the number of days to keep job reports. After this threshold, job reports are removed.
-
puppet_enterprise::profile::orchestrator::pcp_timeout
- Integer representing the length of time, in seconds, before timeout when agents attempt to connect to the Puppet Communications Protocol broker in a Puppet run triggered by the orchestrator.
-
puppet_enterprise::profile::orchestrator::run_service
-
true
to enable orchestration services, orfalse
. -
puppet_enterprise::profile::orchestrator::task_concurrency
- Integer representing the number of tasks that can run at the same time.
-
puppet_enterprise::pxp_agent::ping_interval
- Integer representing the interval, in seconds, between agents' attempts to ping Puppet Communications Protocol brokers.
-
puppet_enterprise::pxp_agent::pxp_logfile
- String representing the path to the Puppet Execution Protocol agent log file. Change as needed.
PuppetDB parameters
Use these parameters to configure and tune PuppetDB.
-
puppet_enterprise::puppetdb::command_processing_threads
- Integer representing how many command processing threads PuppetDB uses to sort incoming data. Each thread can process a single command at a time.
-
puppet_enterprise::profile::master::puppetdb_report_processor_ensure
-
present
to generate agent run reports and submit them to PuppetDB, orabsent
-
puppet_enterprise::puppetdb_port
- Integer in brackets representing the SSL port that PuppetDB listens on.
-
puppet_enterprise::profile::puppetdb::node_purge_ttl
- “Time-to-live” value before deactivated or expired
nodes are deleted, along with all facts, catalogs, and reports for the
node. For example, a value of
"14d"
sets the time-to-live to 14 days.
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"}
.