willmeek / device_manager

Manage devices used by 'puppet device' on puppet agents

device_manager

Table of Contents

1. Description
2. What does this module provide?
3. Usage
4. Parameters
5. Orchestration
6. Reference

Description

Devices require a proxy Puppet agent to request certificates, collect facts, retrieve and apply catalogs, and store reports. This module manages the configuration file used by the puppet device command, applies the base class of associated device modules, and provides additional resources for scheduling and orchestrating puppet device runs on those proxy Puppet agents.

What does this module provide?

• Allows for the configuration devices in device.conf via a manifest, the Classifier, and/or Hiera.
• Provides an option for scheduling of puppet device runs on proxy Puppet agents.
• Provides an optional task for direct orchestration of puppet device runs on newer proxy Puppet agents.
• Provides an option for indirect orchestration of puppet device runs on older proxy Puppet agents.
• Defines a structured fact that can be used to query PuppetDB to identify the Puppet agent proxying for a device.
• Applies the base class of associated device modules to the proxy Puppet agent.

Usage

Install

On the master(s), install the device_manager module:

puppet module install puppetlabs-device_manager

Also, install the device-specific module on the master(s):

puppet module install f5-f5

Configure

Devices can be declared either individually via a manifest, or multiple devices can be declared via the Classifier and/or Hiera.

Note: If the same device (identified by name) is declared via the Classifier and Hiera, the Classifier will take precedence.

Declare Individual Resources via a Manifest:

Declare individual device_manager resources via a manifest applied to the proxy Puppet agent:

node 'agent.example.com' {
  device_manager {'bigip.example.com':
    type         => 'f5',
    url          => 'https://admin:[email protected]/',
    run_interval => 30,
  }
}

Declare Multiple Resources via the Classifier:

Declare multiple device_manager resources via the devices parameter to the device_manager::devices class applied to the proxy Puppet agent via the Classifier:

{
  'bigip1.example.com' => {
    type         => 'f5',
    url          => 'https://admin:[email protected]/',
    run_interval => 30,
  },
  'bigip2.example.com' => {
    type         => 'f5',
    url          => 'https://admin:[email protected]/',
    run_interval => 30,
  },
}

Also, apply the class of the device-specific module to the proxy Puppet agent via the Classifier.

Declare Multiple Resources via Hiera:

Declare multiple device_manager resources via the device_manager::devices key applied to the proxy Puppet agent via Hiera:

---
device_manager::devices:
  bigip1.example.com:
    type:         'f5'
    url:          'https://admin:[email protected]/'
    run_interval: 30
  bigip2.example.com:
    type:         'f5'
    url:          'https://admin:[email protected]/'
    run_interval: 30

... and declare the device_manager::devices class in a manifest applied to the proxy Puppet agent:

node 'agent.example.com'  {
  include device_manager::devices
}

Run puppet device

Declaring these resources will configure device.conf and apply the base class of associated device modules on the proxy Puppet agent, allowing it to execute puppet device runs on behalf of its configured devices:

puppet device --user=root --verbose --target bigip.example.com

Parameters

name

Data type: String

This parameter is optional, and defaults to the title of the resource.

Specifies the certname of the device.

ensure

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 device_managers fact, and negates the effect of any other parameters.

type

Data type: String

Specifies the type of the device in device.conf on the proxy Puppet agent.

url

Data type: String

Specifies the URL of the device in device.conf on the proxy Puppet agent.

credentials

Data type: Hash

This parameter is specific to devices that use the Puppet Resource API.

Specifies the credentials of the device in a HOCON file in confdir/devices, and sets that file as the URL of the device in device.conf, on the proxy Puppet agent.

device_manager {'cisco.example.com':
  type        => 'cisco_ios',
  credentials => {
                  address         => '10.0.1.245',
                  port            => 22,
                  username        => 'admin',
                  password        => 'cisco2600',
                  enable_password => 'cisco2600',
  },
}

debug

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.

include_module

Data type: Boolean, 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. Automatically including that class will automatically install any requirements of the device module.

run_interval

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.

device_manager {'bigip.example.com':
  type         => 'f5',
  url          => 'https://admin:[email protected]/',
  run_interval => 30,
}

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.

run_via_exec (deprecated)

Data type: Boolean

This parameter is optional, with a default of false.

Setting run_via_exec to true will create an Exec resource for the device that executes puppet device --target during each puppet agent on the proxy Puppet agent. This parameter is deprecated in favor of run_interval, as run_via_exec will increase the execution time of a puppet agent run by the execution time of each puppet device run.

device_manager {'bigip.example.com':
  type         => 'f5',
  url          => 'https://admin:[email protected]/',
  run_via_exec => true,
}

Note: On versions of Puppet (lower than Puppet 5.x.x) that do not support puppet device --target, this parameter will instead create one Exec resource that executes puppet device for all devices in device.conf.

Orchestration

Puppet Tasks

On versions of Puppet Enterprise (2017.3.x or higher) that support Puppet Tasks, this module provides a device_manager 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 command.

Examples:

To run puppet device for all devices in device.conf on the specified proxy Puppet agent:

puppet task run device_manager --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 --query 'inventory { facts.device_managers."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 --query 'inventory { facts.device_managers."bigip.example.com" = true }' target=bigip.example.com

Puppet Job (deprecated)

On versions of Puppet Enterprise (2017.2.x or lower) that do not support Puppet Tasks, this module provides an run_via_exec parameter which can be used by the puppet job command to indirectly orchestrate a puppet device run via an orchestrated puppet agent run on the proxy Puppet agent.

Examples:

To run puppet device for each device with run_via_exec set to true on the specified proxy Puppet agent:

puppet job run --nodes 'agent.example.com'

To run puppet device for each device with run_via_exec set to true on the proxy Puppet agent identified by a PuppetDB query:

puppet job run --query 'inventory { facts.device_managers."bigip.example.com" = true }'

Reference

For more information, see:

• Man Page: puppet device
• Config Files: device.conf
• Running Tasks