Installing PE
Sections
Installing PE begins with setting up a standard installation. From here, you can scale up to the large or extra-large installation as your infrastructure grows, or customize configuration as needed.
To install a FIPS-enabled PE primary server, install the
appropriate FIPS-enabled PE tarball, for example puppet-enterprise-2021.5.0-redhatfips-7-x86_64.tar
, on a third party supported
platform with FIPS mode enabled. The node must be configured
with sufficient available entropy for the installation process to
succeed.
Verify the installation package
If your organization requires that you verify authenticity before installing packages, follow these steps to verify the PE installation tarball using GPG.
You must have GnuPG installed to sign for the release key. GnuPG is an open source
program that allows you to safely encrypt and sign digital communications. Visit the
GnuPG website
to download, or install using your package management system, for example yum
install gnupg
.
Install PE
Installation uses default settings to install PE infrastructure components on a single node. After installing, you can scale or customize your installation as needed.
root
. If you're installing on a system that
doesn't enable root
login, use the command sudo su -
to switch to the root
user.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 PE. A default
pe.conf
file is available in the conf.d
directory in the
installer tarball.
pe.conf
file by running ./puppet-enterprise-installer -c
<PATH_TO_pe.conf>
.The following are examples of valid parameter and value expressions:
Type | Value |
---|---|
FQDNs |
"puppet_enterprise::puppet_master_host": "primary.example.com"
|
Strings |
"console_admin_password":
"mypassword"
|
Arrays |
[ "puppet", "puppetlb-01.example.com"
]
|
Booleans |
"puppet_enterprise::profile::orchestrator::run_service": true
Valid Boolean values are
Note: Don't use Yes (y), No (n), 1, or
0.
|
JSON hashes |
"puppet_enterprise::profile::orchestrator::java_args": {"Xmx": "256m",
"Xms": "256m"}
|
Integer |
"puppet_enterprise::profile::console::rbac_session_timeout": "60"
|
Installation parameters
These parameters are required for installation.
%{::trusted.certname}
for your primary server and provide a
console administrator password after running the installer. -
puppet_enterprise::puppet_master_host
- The FQDN of the node hosting the primary server, for example
primary.example.com
.
Database configuration parameters
These are the default parameters and values supplied for the PE databases.
-
puppet_enterprise::activity_database_name
- Name for the activity database.
-
puppet_enterprise::activity_database_read_user
- Activity database user that can perform only read functions.
-
puppet_enterprise::activity_database_write_user
- Activity database user that can perform only read and write functions.
-
puppet_enterprise::activity_database_super_user
- Activity database superuser.
-
puppet_enterprise::activity_service_migration_db_user
- Activity service database user used for migrations.
-
puppet_enterprise::activity_service_regular_db_user
- Activity service database user used for normal operations.
-
puppet_enterprise::classifier_database_name
- Name for the classifier database.
-
puppet_enterprise::classifier_database_read_user
- Classifier database user that can perform only read functions.
-
puppet_enterprise::classifier_database_write_user
- Classifier database user that can perform only read and write functions.
-
puppet_enterprise::classifier_database_super_user
- Classifier database superuser.
-
puppet_enterprise::classifier_service_migration_db_user
- Classifier service user used for migrations.
-
puppet_enterprise::classifier_service_regular_db_user
- Classifier service user used for normal operations.
-
puppet_enterprise::orchestrator_database_name
- Name for the orchestrator database.
-
puppet_enterprise::orchestrator_database_read_user
- Orchestrator database user that can perform only read functions.
-
puppet_enterprise::orchestrator_database_write_user
- Orchestrator database user that can perform only read and write functions.
-
puppet_enterprise::orchestrator_database_super_user
- Orchestrator database superuser.
-
puppet_enterprise::orchestrator_service_migration_db_user
- Orchestrator service user used for migrations.
-
puppet_enterprise::orchestrator_service_regular_db_user
- Orchestrator service user used for normal operations.
-
puppet_enterprise::puppetdb_database_name
- Name for the PuppetDB database.
-
puppet_enterprise::rbac_database_name
- Name for the RBAC database.
-
puppet_enterprise::rbac_database_read_user
- RBAC database user that can perform only read functions.
-
puppet_enterprise::rbac_database_write_user
- RBAC database user that can perform only read and write functions.
-
puppet_enterprise::rbac_database_super_user
- RBAC database superuser.
-
puppet_enterprise::rbac_service_migration_db_user
- RBAC service user used for migrations.
-
puppet_enterprise::rbac_service_regular_db_user
- RBAC service user used for normal operations.
External PostgreSQL parameters
These parameters are required to install an external PostgreSQL instance. Password parameters can be added to standard installations if needed.
-
puppet_enterprise::database_host
- Agent certname of the node hosting the database component. Don't use an alt name for this value.
-
puppet_enterprise::database_port
- The port that the database is running on.
-
puppet_enterprise::database_ssl
-
true
orfalse
. For unmanaged PostgreSQL installations don't use SSL security, set this parameter tofalse
. -
puppet_enterprise::database_cert_auth
-
true
orfalse
.Important: For unmanaged PostgreSQL installations don't use SSL security, set this parameter tofalse
. -
puppet_enterprise::puppetdb_database_password
- Password for the PuppetDB database user. Must be a string,
such as
"mypassword"
. -
puppet_enterprise::classifier_database_password
- Password for the classifier database user. Must be a
string, such as
"mypassword"
. -
puppet_enterprise::classifier_service_regular_db_user
- Database user the classifier service uses for normal operations.
-
puppet_enterprise::classifier_service_migration_db_user
- Database user the classifier service uses for migrations.
-
puppet_enterprise::activity_database_password
- Password for the activity database user. Must be a
string, such as
"mypassword"
. -
puppet_enterprise::activity_service_regular_db_user
- Database user the activity service uses for normal operations.
-
puppet_enterprise::activity_service_migration_db_user
- Database user the activity service uses for migrations.
-
puppet_enterprise::rbac_database_password
- Password for the RBAC database user. Must be a
string, such as
"mypassword"
. -
puppet_enterprise::rbac_service_regular_db_user
- Database user the RBAC service uses for normal operations.
-
puppet_enterprise::rbac_service_migration_db_user
- Database user the RBAC service uses for migrations.
-
puppet_enterprise::orchestrator_database_password
- Password for the orchestrator database user. Must be
a string, such as
"mypassword"
. -
puppet_enterprise::orchestrator_service_regular_db_user
- Database user the orchestrator service uses for normal operations.
-
puppet_enterprise::orchestrator_service_migration_db_user
- Database user the orchestrator service uses for migrations.
Primary server parameters
Use these parameters to configure and tune the primary server.
-
pe_install::puppet_master_dnsaltnames
- An array of strings that represent the DNS altnames to be added to the SSL certificate generated for the primary server.
-
pe_install::install::classification::pe_node_group_environment
- String indicating the environment that infrastructure nodes are running
in. Specify this parameter if you moved your primary server and other
infrastructure nodes from the default
production
environment after install. With non-default environments, this setting ensures that your configuration settings are backed up. -
puppet_enterprise::master::recover_configuration::pe_environment
- String indicating the environment that infrastructure nodes are running
in. Specify this parameter if you moved your primary server and other
infrastructure nodes from the default
production
environment after install. With non-default environments, this setting ensures that your configuration settings are backed up. -
puppet_enterprise::profile::certificate_authority
- 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
-
true
to check for updates whenever the pe-puppetserver service restarts, orfalse
. -
puppet_enterprise::profile::master::code_manager_auto_configure
-
true
to automatically configure the Code Manager service, orfalse
. -
puppet_enterprise::profile::master::r10k_remote
- String that represents the Git URL to be passed to
the
r10k.yaml
file, for example"git@your.git.server.com:puppet/control.git"
. The URL can be any URL that's supported by r10k and Git. This parameter is required only if you want r10k configured when PE is installed; it must be specified in conjunction withpuppet_enterprise::profile::master::r10k_private_key
. -
puppet_enterprise::profile::master::r10k_private_key
- String that represents the local file system 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"
. This parameter is required only if you want r10k configured when PE is installed; it must be specified in conjunction withpuppet_enterprise::profile::master::r10k_remote
.
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, or"false"
. -
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 days after which job reports should be 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"}
.