Support merging configuration from multiple files

README.md

@@ -37,67 +37,75 @@ these stanzas.
 To get started, Telegraf can be installed with a very basic configuration by
 just including the class:
 
-    include ::telegraf
+```puppet
+include ::telegraf
+```
 
 However, to customise your configuration you'll want to do something like the following:
 
-    class { '::telegraf':
-        hostname => $::hostname,
-        outputs  => {
-            'influxdb' => {
-                'urls'     => [ "http://influxdb0.${::domain}:8086", "http://influxdb1.${::domain}:8086" ],
-                'database' => 'telegraf',
-                'username' => 'telegraf',
-                'password' => 'metricsmetricsmetrics',
-                }
-            },
-        inputs   => {
-            'cpu' => {
-                'percpu'   => true,
-                'totalcpu' => true,
-            },
-        }
+```puppet
+class { '::telegraf':
+    hostname => $::hostname,
+    outputs  => {
+        'influxdb' => {
+            'urls'     => [ "http://influxdb0.${::domain}:8086", "http://influxdb1.${::domain}:8086" ],
+            'database' => 'telegraf',
+            'username' => 'telegraf',
+            'password' => 'metricsmetricsmetrics',
+            }
+        },
+    inputs   => {
+        'cpu' => {
+            'percpu'   => true,
+            'totalcpu' => true,
+        },
     }
+}
+```
 
 Or here's a Hiera-based example (which is the recommended approach):
 
-    ---
-    telegraf::global_tags:
-      role: "%{::role}"
-      hostgroup: "%{::hostgroup}"
-      domain: "%{::domain}"
-    telegraf::inputs:
-      cpu:
-        percpu: true
-        totalcpu: true
-      mem:
-      io:
-      net:
-      disk:
-      swap:
-      system:
-    telegraf::outputs:
-      influxdb:
-        urls:
-          - "http://influxdb0.%{::domain}:8086"
-          - "http://influxdb1.%{::domain}:8086"
-        database: 'influxdb'
-        username: 'telegraf'
-        password: 'telegraf'
+```yaml
+---
+telegraf::global_tags:
+  role: "%{::role}"
+  hostgroup: "%{::hostgroup}"
+  domain: "%{::domain}"
+telegraf::inputs:
+  cpu:
+    percpu: true
+    totalcpu: true
+  mem:
+  io:
+  net:
+  disk:
+  swap:
+  system:
+telegraf::outputs:
+  influxdb:
+    urls:
+      - "http://influxdb0.%{::domain}:8086"
+      - "http://influxdb1.%{::domain}:8086"
+    database: 'influxdb'
+    username: 'telegraf'
+    password: 'telegraf'
+```
 
 To configure individual inputs, you can use `telegraf::input`.
 
 Example 1
 
-    telegraf::input { 'my_exec':
-      plugin_type => 'exec'
-      options     => {
-        'commands'    => ['/usr/local/bin/my_input.py',],
-        'name_suffix' => '_my_input',
-        'data_format' => 'json',
-      },
-      require     => File['/usr/local/bin/my_input.py'],
-    }
+```puppet
+telegraf::input { 'my_exec':
+  plugin_type => 'exec'
+  options     => {
+    'commands'    => ['/usr/local/bin/my_input.py',],
+    'name_suffix' => '_my_input',
+    'data_format' => 'json',
+  },
+  require     => File['/usr/local/bin/my_input.py'],
+}
+```
 
 Will create the file `/etc/telegraf/telegraf.d/my_exec.conf`:
 
@@ -108,12 +116,13 @@ Will create the file `/etc/telegraf/telegraf.d/my_exec.conf`:
 
 Example 2
 
-    telegraf::input { 'influxdb-dc':
-      plugin_type => 'influxdb',
-      options     => {
-        'urls' => ['http://remote-dc:8086',],
-      },
-    }
+```puppet
+telegraf::input { 'influxdb-dc':
+  plugin_type => 'influxdb',
+  options     => {
+    'urls' => ['http://remote-dc:8086',],
+  },
+}
 
 Will create the file `/etc/telegraf/telegraf.d/influxdb-dc.conf`:
 
@@ -122,20 +131,22 @@ Will create the file `/etc/telegraf/telegraf.d/influxdb-dc.conf`:
 
 Example 3
 
-    telegraf::input { 'my_snmp':
-      plugin_type => 'snmp',
-      options     => {
-        'interval' => '60s',
-      },
-      sections    => {
-        'snmp.host' => {
-          'address'   => 'snmp_host1:161',
-          'community' => 'read_only',
-          'version'   => 2,
-          'get_oids'  => ['1.3.6.1.2.1.1.5',],
-        },
-      },
-    }
+```puppet
+telegraf::input { 'my_snmp':
+  plugin_type => 'snmp',
+  options     => {
+    'interval' => '60s',
+  },
+  sections    => {
+    'snmp.host' => {
+      'address'   => 'snmp_host1:161',
+      'community' => 'read_only',
+      'version'   => 2,
+      'get_oids'  => ['1.3.6.1.2.1.1.5',],
+    },
+  },
+}
+```
 
 Will create the file `/etc/telegraf/telegraf.d/snmp.conf`:
 
@@ -148,6 +159,47 @@ Will create the file `/etc/telegraf/telegraf.d/snmp.conf`:
       version = 2
       get_oids = ["1.3.6.1.2.1.1.5"]
 
+## Hierarchical configuration from multiple files
+
+Hiera YAML and JSON backends support deep hash merging which is needed for inheriting configuration from multiple files.
+
+First of all, make sure that `gem 'deep_merge'` is installed on your Puppet master.
+
+An example of `hiera.yaml`:
+```yaml
+---
+:hierarchy:
+    - "roles/%{role}"
+    - "type/%{virtual}"
+    - "domain/%{domain}"
+    - "os/%{osfamily}"
+    - "common"
+:backends:
+    - yaml
+:yaml:
+    :datadir: /etc/puppet/hiera
+:merge_behavior: deeper
+```
+
+Then you can define configuration shared for all `physical` servers and place it into `type/physical.yaml`:
+```yaml
+telegraf::inputs:
+  cpu:
+    percpu: true
+    totalcpu: true
+  mem:
+  io:
+  net:
+  disk:
+```
+specific roles will include some extra plugins, e.g. `role/frontend.yaml`:
+
+```yaml
+telegraf::inputs:
+  nginx:
+    urls: ["http://localhost/server_status"]
+```
+
 ## Limitations
 
 This module has been developed and tested against:

manifests/params.pp

@@ -20,20 +20,22 @@
   $manage_service         = true
   $manage_repo            = true
 
-  $outputs = {
+  # currently the only way how to obtain merged hashes
+  # from multiple files (`:merge_behavior: deeper` needs to be
+  # set in your `hiera.yaml`)
+  $outputs = hiera_hash('telegraf::outputs', {
     'influxdb'  => {
       'urls'     => [ 'http://localhost:8086' ],
       'database' => 'telegraf',
       'username' => 'telegraf',
       'password' => 'metricsmetricsmetrics',
     }
-  }
+  })
 
-  $inputs = {
+  $inputs = hiera_hash('telegraf::inputs', {
     'cpu'  => {
       'percpu'   => true,
       'totalcpu' => true,
     }
-  }
-
+  })
 }