The Puppet orchestrator is part of the pe-client-tools package. It is automatically installed on the same node as the Puppet master, or you can install it on a separate workstation that may or may not be managed by Puppet Enterprise.
Once you’ve installed PE or the client tools package, there are a few tasks you need to do to prepare your PE infrastructure for orchestration services.
Before you begin: If you have not already installed the PE client tools package, follow the steps in Installing the PE client tools package.
Before you run any orchestrator jobs, you need to set the appropriate permissions in PE’s role-based access control (RBAC) and establish token-based authentication.
Most users require the following permissions:
Type | Permission | Definition |
---|---|---|
Puppet agent | Run Puppet on agent nodes. | The ability to run Puppet on nodes using the console or orchestrator. Instance must always be "*" . |
Nodes | View node data from PuppetDB. | The ability to view node data imported from PuppetDB. Object must always be "*" . |
The following links provide instructions for creating user roles and setting permissions:
The RBAC permissions page has a full list of available permissions.
Before running an orchestrator job, you must generate an RBAC access token to authenticate to the orchestration service. If you attempt to run a job without a token, PE will prompt you to supply credentials.
For information about generating a token with the CLI, see the documentation on token-based authentication.
Enabling cached catalogs on your agents ensures Puppet will not enforce any catalog changes on your agents until you run an orchestrator job to enforce changes.
When you use the orchestrator to enforce change in a Puppet environment (for example, in the production
environment), you want the Puppet agents in that environment to rely on their cached catalogs until you run an orchestrator job that includes configuration changes for those agents. Puppet agents in such environments will check in during the runinterval (30 minutes by default) to reinforce configuration in their cached catalogs and only apply new configuration when you run Puppet with an orchestration job.
Note: This is an optional configuration. You can run Puppet on nodes with the orchestrator in workflows that don’t require cached catalogs.
Run Puppet on the new agents.
Be sure you run Puppet on the new agents before assigning any application components to them or performing the next step.
In each agent’s puppet.conf
file, add the following settings to the [agent]
section:
use_cached_catalog=true
If you have many agents participating in orchestration services, manually editing each agent’s puppet.conf
file to add these settings can be cumbersome. Instead, add the settings using one of the following methods:
From the command line on each agent machine, run:
puppet config set use_cached_catalog true --section agent
Add an ini_setting
resource in the node default {}
section of the environment’s site.pp
:
if $facts['kernel'] = 'windows' {
$config = 'C:/ProgramData/PuppetLabs/puppet/etc/puppet.conf'
} else {
$config = $settings::config
}
ini_setting { 'use_cached_catalog':
ensure => present,
path => $config,
section => 'agent',
setting => 'use_cached_catalog',
value => 'true',
}
Note that this last example adds this setting to all agents in that environment.
Note: Refer to the static catalog documentation for an overview on how static catalogs prevent file resource errors when running cached catalogs.
The configuration file for the Puppet orchestrator allows you to run commands from the CLI without having to pass additional flags.
Whether you are running the orchestrator from the Puppet master or from a separate work station, there are two types of configuration files:
A global configuration file
This file is installed on both managed and non-managed workstations at:
/etc/puppetlabs/client-tools/orchestrator.conf
C:/ProgramData/PuppetLabs/client-tools/orchestrator.conf
In most situations, this file and its default settings can be used as is. Edit this file as needed.
An optional user-specified configuration file
This file needs to be located at ~/.puppetlabs/client-tools/orchestrator.conf
for both *nix and Windows.
You must manually create this file and populate it with orchestrator configuration file settings.
If present, the user specified configuration always takes precedence over the global configuration file. For example, if both files have contradictory settings for the environment, the user specified settings will prevail.
Both global and user-specified configuration files for the orchestrator must be named orchestrator.conf
, and must be stored in the correct directory.
The orchestrator configuration file is formatted in JSON. For example:
{
"options" : {
"service-url": "https://<PUPPET MASTER HOSTNAME>:8143",
"environment": "production",
"cacert": "/etc/puppetlabs/puppet/ssl/certs/ca.pem",
"token-file": "~/.puppetlabs/token",
"color": true,
"noop": false
}
}
The orchestrator configuration files (the user-specified or global files) can take the following settings:
Setting | Definition |
---|---|
service-url |
The URL that points to the Puppet master and the port used to communicate with the orchestration service. (You can set this with the orchestrator_url parameter in the puppet_enterprise::profile::controller class.) Default value: https://{PUPPET MASTER HOSTNAME}:8143 |
environment |
The environment used when you issue commands with Puppet orchestrator. This will default to the production environment if you don't set it to another environment. |
cacert |
The path for the Puppet Enterprise CA cert.
|
token-file |
The location for the authentication token. Default value: ~/.puppetlabs/token |
color |
Determines whether the orchestrator output will use color. Set to true or false . |
noop |
Determines whether the orchestrator should run the Puppet agent in no-op mode. Set to true or false . |
If you’re running the Puppet orchestrator from a PE-managed machine, on either the Puppet master or a Puppet agent node, PE manages the global configuration file.
The class that manages the global configuration file is puppet_enterprise::profile::controller
.
For the orchestrator, the following parameters and values are available for this class:
Parameter | Value |
---|---|
manage_orchestrator |
true or false (default is true ) |
orchestrator_url |
url and port (default is Puppet master url and port 8143) |
The only value PE sets in the global configuration file is the orchestrator_url
(which sets the orchestrator’s service-url
in /etc/puppetlabs/client-tools/orchestrator.conf
).
You can add additional configuration settings manually.
Both application management and orchestration services are on by default in PE. If you need to disable these services, refer to Disabling application management and Disabling orchestration services.