How to configure PE

After you've installed Puppet Enterprise (PE), you can optimize it by configuring and tuning settings. For example, you might want to add your certificate to the allowlist, increase the max-threads setting for http and https requests, or configure the number of JRuby instances.

PE shares configuration settings used in open source Puppet (which are documented in the Configuration Reference). However, the default values for PE might differ from the default values for Puppet. Some examples of settings that have different defaults in PE include disable18n, environment_timeout, always_retry_plugins, and the Puppet Server JRuby max-active-instances settings. To verify PE's configuration defaults, check the puppet.conf file after installation.

There are three ways to configure PE settings:

For consistency, it is important to always configure settings in the same way, unless a situation calls for you to use a specific method. For example, if you choose to configure settings in the PE console, then always configure settings in the console, unless a specific setting requires using Hiera or editing pe.conf.

This page provides generic instructions for configuring PE settings. You'll find information about specific settings in other Configuring Puppet Enterprise topics and throughout the PE documentation.

Configure settings in the PE console

You can use the Puppet Enterprise (PE) console's graphical interface to configure settings for your PE installation.

Changes you make in the console override your Hiera data and data in pe.conf. It is best to use the console when you want to:

Change parameters in profile classes starting with puppet_enterprise::profile.
Add parameters to PE-managed configuration files.
Set parameters that configure at runtime.

To change settings in the console you can Set configuration data or Set parameters.

Set configuration data

Configuration data set in the console is used for automatic parameter lookup in the same way that Hiera data is used. Console configuration data takes precedence over Hiera data, but you can combine data from both sources to configure nodes.

Tip: In most cases, setting configuration data in Hiera is the more scalable and consistent method, but there are some cases where the console is preferable. Use the console to set configuration data if:

You want to override Hiera data. Data set in the console overrides Hiera data when configured as recommended.
You want to give someone permission to define or edit data, and they don’t have the skill set to do it in Hiera.
You simply prefer the console user interface.

Important: If your installation includes a disaster recovery replica, make sure you enable data editing in the console for both your primary server and replica.

In the console, click Node groups and select the node group that you want to add configuration data to.
On the Configuration data tab, specify a Class and select a Parameter to add.

You can select from existing classes and parameters in the node group's environment, or you can specify free-form values. Classes aren’t validated, but any class you specify must be present in the node’s catalog at runtime in order for the parameter value to be applied.

When you select a parameter, the Value field is automatically populated with the inherited or default value.
Optional: If necessary, change the parameter's default Value.

Set parameters

Parameters are declared resource-style, which means you can use them to override other data; however, this override capability can introduce class conflicts and declaration errors that cause Puppet runs to fail.

Important: You can structure parameters as JSON, but, if they can't be parsed as JSON, they're treated as strings.

In the console, click Node groups and select the node group you want to add a parameter to.
On the Classes tab, select the class you want to modify, and select the Parameter you want to add.
The Parameter list shows all parameters available for the selected class in the node group’s environment. When you select a parameter, the Value field is automatically populated with the inherited or default value.
Optional: If necessary, change the parameter's default Value.

Configure settings with Hiera

Hiera is hierarchy-based configuration management that relies on a defaults with overrides system. When you add a parameter or setting to your Hiera data, Hiera searches through the data, in the order defined, to find the value you want to change. Once found, it overrides the default value with the new parameter or setting. You can use Hiera to manage your Puppet Enterprise (PE) configuration settings.

Before you begin

Separating data (Hiera) in the Puppet documentation explains more about how to use Hiera and what you can configure in Hiera.

Changes to PE configuration settings in Hiera override configuration settings in pe.conf, but not those set in the PE console. However, settings declared in the console override Hiera data. It's best to use Hiera when you want to:

Change parameters in non-profile classes.
Set parameters that are static and version-controlled.
Configure for high availability.

To configure a setting in Hiera:

Open a Hiera data file in a text editor.
The default location for Hiera data files on *nix systems is:
```
/etc/puppetlabs/code/environments/<ENVIRONMENT>/data/common.yaml
```
On Windows systems, it is:
```
%CommonAppData%\PuppetLabs\code\environments\<ENVIRONMENT>\data\common.yaml
```
Tip: The datadir setting in the hiera.yaml configuration file changes the Hiera data file location. You can also change the common data file path in the hierarchy section of the hiera.yaml file. If you changed either of these settings, you'll find the default Hiera data files in your customized location.
Add your new parameter to the Hiera data file.
For example, the following declaration increases sets number of seconds before a node is considered unresponsive to 4000, whereas the defeault setting is 3600 seconds:
```
puppet_enterprise::console_services::no_longer_reporting_cutoff: 4000
```
Save the file and run puppet agent -t to compile the changes.

Configure settings in `pe.conf`

Puppet Enterprise (PE) configuration data includes any data set in /etc/puppetlabs/enterprise/conf.d/, but pe.conf is the file used for most configuration activities during installation.

PE configuration settings made in Hiera and the console always override settings made in pe.conf. Configure settings in pe.conf when you want to:

Access settings during installation.
Configure for high availability.

To configure settings in pe.conf:

On your primary server, open the pe.conf file in a text editor. The file is located at:
```
/etc/puppetlabs/enterprise/conf.d/pe.conf
```
Add the parameter and value you want to set.
For example, this declaration changes the proxy location in your PE repo:
```
pe_repo::http_proxy_host: "proxy.example.vlan"
```
Save the file and run puppet agent -t

Tip: If you had stopped any PE services, run puppet infrastructure configure instead of puppet agent -t.

Configuration file syntax

Puppet supports two formats for configuration files: valid JSON and Human-Optimized Config Object Notation (HOCON), which is a JSON superset. We've provided these syntax examples to guide you when you're writing configuration files.

For details about HOCON itself, refer to the HOCON documentation.

Brackets

JSON example with brackets:

{
   "authorization": {
    	"version": 1
    }
}

In HOCON, you can omit the brackets ({ }) around the root object. For example:

"authorization": {
    "version": 1
}

Quotation marks

With JSON, wrap keys in double quotes. Quotation marks around values depends on the value type, such as an integer or string. For example:

"authorization": {
    "version": 1
}

In HOCON, double quotes around keys and string values are usually optional. However, double quotes are required if the string contains any of these characters: *, ^, +, :, or =

For example:

authorization: {
    version: 1
}

Commas

In JSON, use commas to separate items in a map or array.

JSON map example:

rbac: {
 password-reset-expiration: 24,
 session-timeout: 60,
 failed-attempts-lockout: 10,
}

JSON array example:

http-client: {
    ssl-protocols: [TLSv1, TLSv1.1, TLSv1.2]
}

When writing a map or array in HOCON, you can use a new line instead of a comma.

HOCON map example:

rbac: {
 password-reset-expiration: 24
 session-timeout: 60
 failed-attempts-lockout: 10
}

HOCON array example:

http-client: {
    ssl-protocols: [
    TLSv1
    TLSv1.1
    TLSv1.2
    ]
}

Comments

JSON does not support comments.

In HOCON, you can use // or # to delineate comments. Inline comments are supported. For example:

authorization: {
    version: 1
    rules: [
        {
            # Allow nodes to retrieve their own catalog
            match-request: {
                path: "^/puppet/v3/catalog/([^/]+)$"
                type: regex
                method: [get, post]
            }
        }
    ]
}