Agentless devices require a proxy Puppet agent to request certificates, collect facts, retrieve and apply catalogs, and store reports. This module manages the configuration files used by the puppet device command, installs libraries required by device modules, and provides additional resources for scheduling and orchestrating puppet device runs on those proxy Puppet agents.
- Allows for the configuration of devices in
device.confvia a manifest, Hiera, and/or the Classifier - Defines a
devicesfact on the proxy Puppet agent identifying the devices for which it is a proxy - Installs libraries required by associated device modules the proxy Puppet agent
- Provides an option for scheduling of
puppet deviceruns on the proxy Puppet agent - Provides an optional task for orchestration of
puppet deviceruns on newer proxy Puppet agents
On the server, install the device_manager module:
puppet module install puppetlabs-device_managerOn the server, install the device-specific module associated with each device. For example:
puppet module install f5-f5puppet module install puppetlabs-cisco_iosYou can declare individual devices via a manifest, or multiple devices via Hiera or the Classifier. Using Hiera allows you to encrypt sensitive information, such as passwords, at rest on the server, using the hiera-eyaml backend.
Note: If you declare the same device (identified by name) via Hiera and the Classifier, the declaration in the Classifier takes precedence.
Declare individual device_manager resources via a manifest and apply to the proxy Puppet agent:
node 'agent.example.com' {
device_manager { 'bigip.example.com':
type => 'f5',
url => 'https://admin:password@10.0.0.245/',
run_interval => 30,
}
device_manager { 'cisco.example.com':
type => 'cisco_ios',
credentials => {
address => '10.0.0.246',
port => 22,
username => 'admin',
password => 'password',
enable_password => 'password',
},
}
}Declare multiple device_manager resources via the device_manager::devices key and apply to the proxy Puppet agent via Hiera:
---
device_manager::devices:
bigip1.example.com:
type: 'f5'
url: 'https://admin:password@10.0.1.245/'
run_interval: 30
bigip2.example.com:
type: 'f5'
url: 'https://admin:password@10.0.2.245/'
run_interval: 30
cisco1.example.com:
type: 'cisco_ios'
credentials:
address: '10.0.1.246'
port: 22
username: 'admin'
password: 'password'
enable_password: 'password'
run_interval: 60
cisco2.example.com:
type: 'cisco_ios'
credentials:
address: '10.0.2.246'
port: 22
username: 'admin'
password: 'password'
enable_password: 'password'
run_interval: 60Declare the device_manager::devices class in a manifest and apply to the proxy Puppet agent:
node 'agent.example.com' {
include device_manager::devices
}Declare multiple device_manager resources, via the devices parameter, to the device_manager::devices class and apply to the proxy Puppet agent via the Classifier:
{
'bigip1.example.com' => {
type => 'f5',
url => 'https://admin:password@10.0.1.245/',
run_interval => 30,
},
'bigip2.example.com' => {
type => 'f5',
url => 'https://admin:password@10.0.2.245/',
run_interval => 30,
},
'cisco1.example.com' => {
type => 'cisco_ios'
credentials => {
address => '10.0.1.246',
port => 22,
username => 'admin',
password => 'password',
enable_password => 'password',
},
run_interval => 60,
}
'cisco2.example.com' => {
type => 'cisco_ios',
credentials => {
address => '10.0.2.246',
port => 22,
username => 'admin',
password => 'password',
enable_password => 'password',
},
run_interval => 60,
}
}When using the device_manager::devices class, you can declare defaults (for all devices and for each device type) for device parameters via the device_manager::devices::defaults key and apply to the proxy Puppet agent via Hiera:
device_manager::devices::defaults:
type: 'cisco_ios'
run_interval: 45
f5:
run_interval: 30
cisco_ios:
run_interval: 60
credentials:
port: 22
username: 'admin'
password: 'password'
enable_password: 'password'This allows for deduplication of common parameters:
---
device_manager::devices:
bigip1.example.com:
type: 'f5'
url: 'https://admin:password@10.0.1.245/'
bigip2.example.com:
type: 'f5'
url: 'https://admin:password@10.0.2.245/'
cisco1.example.com:
credentials:
address: '10.0.1.246'
cisco2.example.com:
credentials:
address: '10.0.2.246'The order of precedence for parameters and defaults is:
- The parameter in the resource declaration
- The default in
device_manager::devices::defaults::<DEVICE TYPE> - The default in
device_manager::devices::defaults
Hash parameters (such as credentials) are merged using the same precedence.
Declaring these resources will configure device.conf and apply the base class (if one is defined) of associated device modules on the proxy Puppet agent, allowing it to execute puppet device runs on behalf of its configured devices:
puppet device --verbose --target bigip.example.comThe first run of puppet device for a device will generate a certificate request for the device:
Info: Creating a new SSL key for bigip.example.com
Info: Caching certificate for ca
Info: csr_attributes file loading from /opt/puppetlabs/puppet/cache/devices/bigip.example.com/csr_attributes.yaml
Info: Creating a new SSL certificate request for bigip.example.com
Info: Certificate Request fingerprint (SHA256): ...
Info: Caching certificate for caUnless autosign is enabled, the following (depending upon waitforcert) will be output:
Notice: Did not receive certificate
Notice: Did not receive certificate
Notice: Did not receive certificate
...Or:
Exiting; no certificate found and waitforcert is disabledOn the server, execute the following to sign the certificate for the device:
puppet cert sign bigip.example.comThis will output that the certificate for the device has been signed:
Signing Certificate Request for:
"bigip.example.com" (SHA256) ...
Notice: Signed certificate request for bigip.example.com
Notice: Removing file Puppet::SSL::CertificateRequest bigip.example.com at '/etc/puppetlabs/puppet/ssl/ca/requests/bigip.example.com.pem'Data type: String
This parameter is optional, and defaults to the title of the resource.
Specifies the certname of the device.
Data type: String
This parameter is optional, with valid options of 'present' (the default) and 'absent'.
Setting to 'absent' deletes the device from device.conf and the devices fact, and negates the effect of any other parameters.
Data type: String
Specifies the type of the device in device.conf on the proxy Puppet agent. This identifies the module used to access the device.
Data type: String
This parameter is required for devices that do not use the Puppet Resource API: refer to the associated device module documentation for details regarding its format. The url and credentials parameters are mutually exclusive.
url => 'https://admin:password@10.0.0.245/'Specifies the URL of the device in device.conf on the proxy Puppet agent.
Data type: Hash
This parameter is required for devices that use the Puppet Resource API: refer to the associated device module documentation for details regarding its format. The credentials and url parameters are mutually exclusive.
credentials => {
address => '10.0.0.246',
port => 22,
username => 'admin',
password => 'password',
enable_password => 'password',
}This saves the credentials of the device in a HOCON file in confdir/devices and specifies that file as the url of the device in device.conf on the proxy Puppet agent.
Data type: Boolean
This parameter is optional, with a default of false.
Specifies transport-level debugging of the device in device.conf on the proxy Puppet agent, and is limited to debugging the telnet and ssh transports.
Note: This parameter specifies the debug property defined in: Config Files: device.conf rather than the --debug option defined in: Man Page: puppet device.
Data type: Boolean
This parameter is optional, with a default of true.
Specifies automatically including the base class (if one is defined) of the associated device module (specified by the type parameter) on the proxy Puppet agent. Device modules may implement a base class that applies an install class. Including that class will install libraries required by the device module.
Data type: Integer
This parameter is optional, with a default of 0.
Setting run_interval to a value between 1 and 1440 will create a Cron (or on Windows, a Scheduled Task) resource for the device that executes puppet device --target every run_interval minutes (with a randomized offset) on the proxy Puppet agent. When creating a Cron resource, values greater than thirty minutes will be rounded up to the nearest hour.
Note: On versions of Puppet (lower than Puppet 5.x.x) that do not support puppet device --target, this parameter will instead create one Cron (or Scheduled Task) resource that executes puppet device for all devices in device.conf every 60 minutes (at a randomized minute) on the proxy Puppet agent.
Data type: String
This parameter is optional, with a default of $::identity['user'].
Specifies the user to own the configuration files and any cron job or scheduled task for the device on the proxy Puppet agent.
Note: On versions of Puppet (lower than Puppet 5.x.x) that do not support puppet device --target, this parameter will not set the user of the one Cron (or Scheduled Task) resource.
Data type: String
This parameter is optional, with a default of $::identity['group'].
Specifies the group to own the configuration files for the device on the proxy Puppet agent.
On versions of Puppet Enterprise (2017.3.x or higher) that support Puppet Tasks, this module provides a device_manager::run_puppet_device task which can be used by the puppet task command to orchestrate a puppet device run on the proxy Puppet agent. Help for this task is available via: puppet task show device_manager::run_puppet_device command.
To run puppet device for all devices in device.conf on the specified proxy Puppet agent:
puppet task run device_manager::run_puppet_device --nodes 'agent.example.com'To run puppet device for all devices in device.conf on the proxy Puppet agent identified by a PuppetDB query:
puppet task run device_manager::run_puppet_device --query 'inventory { facts.devices."bigip.example.com" = true }'To run puppet device --target for a specific device in device.conf on the proxy Puppet agent identified by a PuppetDB query:
puppet task run device_manager::run_puppet_device --query 'inventory { facts.devices."bigip.example.com" = true }' target=bigip.example.comThis codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of AGPL, BSD-2, BSD-3, GPL2.0, LGPL, MIT and MPL Licensing.
For more information, see: