Install PE using PIM (beta)

Puppet Installation Manager (PIM) supports the deployment of standard, large, and extra-large PE architectures. For an interactive experience, choose the guided installation and follow the step-by-step process in your terminal to configure and install the PE infrastructure you require. Alternatively, if you do not require guidance, you can create a JSON file containing your custom installation parameters, and run the installation from the command line.

Regardless of the installation process you choose, you can use PIM on a jump host to install PE infrastructure components on remote nodes that run a supported PE operating system. Alternatively, you can install PE locally by using PIM on a machine running a supported PE operating system. In this scenario, if you require additional infrastructure nodes to host PE components, your local machine can serve as a jump host.

PE infrastructure nodes are the hosts where PE components are installed. The following table lists the infrastructure nodes you can include in your installation when you use PIM to install PE:
PE infrastructure node Description
Primary server (required)

Essential for a PE installation. Can host all components and services for smaller scale environments that include up to 2,500 nodes.
Primary server replica (optional) To set up disaster recovery, install a replica of the primary server. If your primary server fails, the replica takes over to continue critical operations.
Database server In an extra-large PE installation, a dedicated database server hosts a PostgreSQL instance containing the PuppetDB database.
Database server replica (optional) Provides backup support during failovers.
Compilers Compilers process Puppet code and convert it into catalogs that can be applied to agent nodes. The primary server can handle requests and compile catalogs for up to 2,500 agent nodes. In large and extra-large PE installations, dedicated compiler nodes help accelerate catalog compilation.

Install PE using the guided process

For an interactive experience, use the guided installation process. Based on information you provide about your environment and requirements, PIM automatically configures your PE installation.

Before you begin
  • Ensure that you have the required access to the nodes where you want to install PE infrastructure.
    • To install the primary server locally on the machine where PIM is running, you must log in as the root user.
    • To install PE components on remote nodes, the machine running PIM must have root SSH access to those nodes.
  • Ensure that Puppet is not already installed on any of the nodes where you want to install PE infrastructure.
To install PE by using the PIM guided process:
  1. Download PIM.
    Go to the Puppet Installation Manager download page and download the binary for your operating system.
  2. Start the guided installation process.
    In your terminal, navigate to the pim directory and run the following command:
    ./pim wizard
  3. Follow the guided steps in your terminal to complete the installation.
    If you require additional guidance during the installation process, you can view help content by pressing Ctrl+H.

Install PE with your defined parameters

If you know which PE infrastructure components you want to install and you do not require guidance, you can specify your installation parameters in a JSON file. Then use PIM to start the installation by running a single command.

Before you begin
  • Ensure that you have the required access to the nodes where you want to install PE infrastructure.
    • To install the primary server locally on the machine where PIM is running, you must log in as the root user.
    • To install PE components on remote nodes, the machine running PIM must have root SSH access to those nodes. You can configure SSH, or use the -b flag to pass the SSH key or SSH credentials when you run the installation command.
  • Ensure that Puppet is not already installed on any of the nodes where you want to install PE infrastructure.
To install PE from the PIM command line:
  1. Download PIM.
    Go to the Puppet Installation Manager download page and download the binary for your operating system.
  2. Create a JSON file specifying the installation parameters you require.
    For examples illustrating the JSON properties required for different PE architectures, see Creating an installation parameters file.
  3. Start the installation.
    In your terminal, navigate to the pim directory and run one of the following commands, replacing parameters.json with the actual file name (including the file path, if necessary):
    • To run the installation without debugging and without configuring SSH, use a command like the following example:
      ./pim install parameters.json
    • To enable debug logging, add -d or --debug. For example: 
      ./pim install parameters.json --debug
    • To pass an SSH key or SSH credentials for accessing remote nodes, use the -b flag with the installation command as shown in the following examples:
      ./pim install -b user=root -b private-key=~/.ssh/ssh_key params.json
      ./pim install -b user=root -b password=ssh_password params.json
  4. Follow the CLI prompts to complete the installation process.
    Note: PIM uses the Puppet Enterprise Administration Module (PEADM), which depends on Puppet Bolt, a tool for automating Puppet infrastructure maintenance tasks. When you run the ./pim install command, PIM checks whether Bolt is present and, if necessary, provides the option to install Bolt.

Creating an installation parameters JSON file

To install PE from the Puppet Installation Manager (PIM) command line, you must create a JSON file containing your installation parameters and pass that file with the install command. The JSON file defines your installation architecture, including the option for disaster recovery.

Important: Creating a JSON file containing installation parameters is not required if you use the guided installation process. With the guided process, PIM automatically configures your installation based on the information you provide about your environment and requirements.

Installation configuration examples

The following examples illustrate how to structure the JSON file for different PE configurations.

Installation parameters for an extra-large architecture with disaster recovery
{
  "primary_host": "pe-xl-core-0.lab1.puppet.vm",
  "primary_postgresql_host": "pe-xl-core-1.lab1.puppet.vm",
  "replica_host": "pe-xl-core-2.lab1.puppet.vm",
  "replica_postgresql_host": "pe-xl-core-3.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-xl-compiler-0.lab1.puppet.vm",
    "pe-xl-compiler-1.lab1.puppet.vm"
  ],
  "console_password": "puppetlabs",
  "dns_alt_names": ["puppet", "puppet.lab1.puppet.vm"],
  "version": "2023.6.0"
}
Installation parameters for an extra-large architecture without disaster recovery
{
  "primary_host": "pe-xl-core-0.lab1.puppet.vm",
  "primary_postgresql_host": "pe-xl-core-1.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-xl-compiler-0.lab1.puppet.vm",
    "pe-xl-compiler-1.lab1.puppet.vm"
  ],
  "console_password": "puppetlabs",
  "dns_alt_names": ["puppet", "puppet.lab1.puppet.vm"],
  "version": "2023.6.0"
}
Installation parameters for a large architecture with disaster recovery
{
  "primary_host": "pe-l-core-0.lab1.puppet.vm",
  "replica_host": "pe-l-core-2.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-l-compiler-0.lab1.puppet.vm",
    "pe-l-compiler-1.lab1.puppet.vm"
  ],
  "console_password": "puppetlabs",
  "dns_alt_names": ["puppet", "puppet.lab1.puppet.vm"],
  "version": "2023.6.0"
}
Installation parameters for a large architecture without disaster recovery
{
  "primary_host": "pe-l-core-0.lab1.puppet.vm",
  "compiler_hosts": [
    "pe-l-compiler-0.lab1.puppet.vm",
    "pe-l-compiler-1.lab1.puppet.vm"
  ],
  "console_password": "puppetlabs",
  "dns_alt_names": ["puppet", "puppet.lab1.puppet.vm"],
  "version": "2023.6.0"
}
Installation parameters for a standard architecture with disaster recovery
{
  "primary_host": "pe-core-0.lab1.puppet.vm",
  "replica_host": "pe-core-2.lab1.puppet.vm",
  "console_password": "puppetlabs",
  "dns_alt_names": ["puppet", "puppet.lab1.puppet.vm"],
  "version": "2023.6.0"
}
Installation parameters for a standard architecture without disaster recovery
{
  "primary_host": "pe-core-0.lab1.puppet.vm",
  "console_password": "puppetlabs",
  "dns_alt_names": ["puppet", "puppet.lab1.puppet.vm"],
  "version": "2023.6.0"
}