(FM-7230) Specify defaults for multiple devices using Hiera or Classi…

…fier

This commit implements global and device-type levels of default values.
These defaults are used by `device_manager::devices`.

.rubocop.yml

@@ -73,6 +73,8 @@ Style/StringMethods:
   Enabled: true
 Layout/EndOfLine:
   Enabled: false
+Layout/IndentHeredoc:
+  Enabled: false
 Metrics/AbcSize:
   Enabled: false
 Metrics/BlockLength:

README.md

@@ -31,12 +31,16 @@ On the master, install the `device_manager` module:
 puppet module install puppetlabs-device_manager
 ```
 
-On the master, install the device-specific module associated with the device. For example:
+On the master, install the device-specific module associated with each device. For example:
 
 ```bash
 puppet module install f5-f5
 ```
 
+```bash
+puppet module install puppetlabs-cisco_ios
+```
+
 ### Configure
 
 Devices can be declared either individually via a manifest, or multiple devices can be declared via Hiera or the Classifier. Using Hiera allows for the option of encrypting sensitive information (such as passwords) at rest on the master, using the hiera-eyaml backend.
@@ -49,11 +53,24 @@ Declare individual `device_manager` resources via a manifest applied to the prox
 
 ```puppet
 node 'agent.example.com' {
-  device_manager {'bigip.example.com':
+
+  device_manager { 'bigip.example.com':
     type         => 'f5',
-    url          => 'https://admin:fffff55555@10.0.0.245/',
+    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',
+    },
+  }
+
 }
 ```
 
@@ -66,12 +83,30 @@ Declare multiple `device_manager` resources via the `device_manager::devices` ke
 device_manager::devices:
   bigip1.example.com:
     type:         'f5'
-    url:          'https://admin:fffff55555@10.0.1.245/'
+    url:          'https://admin:password@10.0.1.245/'
     run_interval: 30
   bigip2.example.com:
     type:         'f5'
-    url:          'https://admin:fffff55555@10.0.2.245/'
+    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
 ```
 
 ... and declare the `device_manager::devices` class in a manifest applied to the proxy Puppet agent:
@@ -90,17 +125,85 @@ Declare multiple `device_manager` resources via the `devices` parameter to the `
 {
   'bigip1.example.com' => {
     type         => 'f5',
-    url          => 'https://admin:fffff55555@10.0.1.245/',
+    url          => 'https://admin:password@10.0.1.245/',
     run_interval => 30,
   },
   'bigip2.example.com' => {
     type         => 'f5',
-    url          => 'https://admin:fffff55555@10.0.2.245/',
+    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,
+  }
 }
 ```
 
+#### Defaults When Managing Multiple Devices via Hiera or the Classifier:
+
+When using the `device_manager::devices` class, defaults (for all devices, and/or for each device type) for device parameters can be declared via the `device_manager::devices::defaults` key applied to the proxy Puppet agent via Hiera:
+
+```yaml
+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:
+
+```yaml
+---
+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:
+
+1. The parameter in the resource declaration
+1. The default in `device_manager::devices::defaults::<DEVICE TYPE>`
+1. The default in `device_manager::devices::defaults`
+
+Hash parameters (such as `credentials`) are merged using the same precedence.
+
 ### Run `puppet device`
 
 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:
@@ -180,31 +283,32 @@ Specifies the type of the device in `device.conf` on the proxy Puppet agent. Thi
 
 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. The `url` and `credentials` parameters are mutually exclusive.
+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.
+
+```puppet
+url => 'https://admin:password@10.0.0.245/'
+```
 
 Specifies the URL of the device in `device.conf` on the proxy Puppet agent.
 
 ### credentials
 
 Data type: Hash
 
-This parameter is required for devices that use the Puppet Resource API: refer to the associated device module documentation for details. The `credentials` and `url` parameters are mutually exclusive.
-
-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.
+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.
 
 ```puppet
-device_manager {'cisco.example.com':
-  type        => 'cisco_ios',
-  credentials => {
-                  address         => '10.0.0.246',
-                  port            => 22,
-                  username        => 'admin',
-                  password        => 'password',
-                  enable_password => 'password',
-  },
+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.
+
 ### debug
 
 Data type: Boolean
@@ -233,14 +337,6 @@ Setting `run_interval` to a value between 1 and 1440 will create a Cron (or on W
 
 [comment]: # (Doing so avoids impractical cron mathematics.)
 
-```puppet
-device_manager {'bigip.example.com':
-  type         => 'f5',
-  url          => 'https://admin:fffff55555@10.0.0.245/',
-  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.
 
 ## Orchestration

examples/devices.yaml

@@ -0,0 +1,27 @@
+---
+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'
+
+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'

examples/init.pp

@@ -2,6 +2,6 @@
 
 device_manager {'bigip.example.com':
   type         => 'f5',
-  url          => 'https://admin:fffff55555@10.0.0.245/',
+  url          => 'https://admin:password@10.0.0.245/',
   run_interval => 30,
 }

manifests/conf/device.pp

@@ -7,14 +7,14 @@
   String                    $url,
   Hash                      $credentials,
   Boolean                   $debug = false,
-  Enum['present', 'absent'] $ensure = 'present',
+  Enum[present, absent]     $ensure = present,
 ) {
 
   include device_manager::conf
 
   $credentials_file = "${device_manager::conf::devices_directory}/${name}.conf"
 
-  if ($ensure == 'present') {
+  if ($ensure == present) {
 
     # Either the credentials are in the url,
     # or define the credentials in a HOCON file and set the url to that file.