Configure compile masters for a multi-region infrastructure for Puppet Enterprise 2016.x to 2017.1 and 2017.3 to 2019.0

If your Puppet Enterprise infrastructure spans a large geographic area, and you'd like to implement an architecture in which a master or group of masters serve a group of local agents, configure your deployment so that one or more compile masters serve each geographic region.

If all of your nodes are in the same region, and you want to set up a group of load-balanced compile masters to address scaling, see our documentation on compile master installation for Puppet Enterprise 2019.0. Use the version selector on our docs site to make sure you've got the right version of our docs for your deployment.

Version and installation information

PE version: 2016.x, 2017.1 2017.3 to 2019.0
Installation type: monolithic (all listed versions), split (2016.x, 2017.1.x, 2017.3.x, 2018.x)

Note: We do not support split installations for PE 2019.0 and later.

Solution

Configure one or more compile masters to serve each geographic region.

Before you begin:

• This requires the puppetlabs-inifile module to be installed.

• This article assumes you've already set up a master or master of masters.

• Decide if each region will require a single compile master or more than one compile master. A single compile master per region is adequate for most deployments. However, you might want to have multiple compile masters per region due to failover or scaling considerations.

1. Provision a new node or group of nodes to act as a compile master or masters for the region, each with the same OS / version as your master of masters (MoM). SSH into each new node and install the Puppet agent on it using the following command:

   For a single regional compile master:

   Run the following:

   curl -k https://<MASTER.EXAMPLE.COM>:8140/packages/current/install.bash | sudo bash

   For multiple regional compile masters:

   Assign the same dns_alt_name to all compile masters in the same region. Run the following command to install and configure the Puppet agent on each new node:

   curl -k https://<MASTER.EXAMPLE.COM>:8140/packages/current/install.bash | sudo bash -s main:dns_alt_names=<REGIONAL_DNS_ALT_NAME>

2. On the MoM, sign the certificate for each new compile master by running: puppet cert --allow-dns-alt-names sign compile.master.example.com

3. From the command line on each new compile master, run puppet agent -t

4. Use the PE console to classify each new node as a compile master.

   1. In the console, click Nodes > Classification. In the PE Infrastructure node group, click the PE Master node group.

   2. In the Certname section, in the Node name field, enter each node's FQDN, for example COMPILE.MASTER.EXAMPLE.COM.

   3. Click Pin node and then click commit changes.

5. Configure pe_repo::master to send agent installation requests to the regional compile master (for a single regional compile master) or its shared dns-alt-name (for multiple compile masters.).

   1. In the console, click Nodes > Classification > Add group.

   2. In the Group name field, enter a name, for example: PE US Compile masters

   3. Under Parent name select the PE Master group, and click Add.

   4. Click the PE US Compile masters group. In the Certname section, in the Node name field, enter the certname of each compile master.

   5. Click Classes. In the Add new class field, enter the value pe_repo. Click Add class.

   6. Under the pe_repo class, select the master parameter. In the Value field, enter the FQDN of your regional compile master or its dns-alt-name.

   7. Click Add parameter, and then click Commit change.

6. Run puppet agent -t on each node as follows.

   Important: The following Puppet runs MUST be done in the order listed. Puppet has to be run on these nodes in this order for the compile master to be active as quickly as possible. You must wait for the run to finish on each node before moving on to the next node.

   For a monolithic installation:

   1. COMPILE.MASTER.EXAMPLE.COM (on each new compile master)

   2. MASTER.EXAMPLE.COM

   For a split installation (PE 2016.x, 2017.1, 2017.3, 2018.x):

   1. COMPILE.MASTER.EXAMPLE.COM (on each new compile master)

   2. PUPPETDB.EXAMPLE.COM

   3. CONSOLE.EXAMPLE.COM

   4. MASTER.EXAMPLE.COM

7. Point all agents in a region to the new compile master(s) by applying a manifest in the node classifier updating puppet.conf. Replace master_new_compile_master with the certname of your regional compile master (for a single regional compile master) or its shared dns-alt-name (for multiple compile masters).

   For example:

   ini_setting { "change master hostname":
    ensure  => present,
    path    => '/etc/puppetlabs/puppet/puppet.conf',
    section => 'main',
    setting => 'server',
    value   => 'master_new_compile_master',
   }