Extended and refined example3, especially README

examples/example3/README.md

@@ -1,14 +1,45 @@
 ## Example 3 – Using virtual resources and collection in a master-agent set-up.
 
-
 This is an (almost) complete example for a master-agent set-up using virtual resources in Puppet.
 
 ### Manifests
 
-All nodes that should be monitored inherit from the monitorednode role, thus applying the profile::icinga::agent class.
+All nodes that should be monitored inherit from the monitorednode role, thus applying the `profile::icinga::agent` class.
 
 Each monitored node exports itself as an endpoint and a zone. This information is then automatically collected on the master to generate the necessary configuration files.
 
+Agents also export a `Host` object (`@@icinga2::object::host`) and use array_hash() to get and assemble host properties from the respective hiera files throughout the hiera hierarchy.
+
+#### A word of caution on services and apply rules
+
+This set-up does not use any "manually" created `Service` objects, but _applies_ services to hosts based on their vars exclusively. The result is a much simplier Icinga2 configuration, among other things.
+
+There are two things to note here about `Apply Rules`:
+
+1. We don't use `icinga2::object::service` to define the apply rules, since the current version (0.8.0) of this Puppet module does not yet support the entire range of available functions and macros. Instead, we use `file` resources from a custom, dedicated module, together with the _icinga2::config::file_ tag. The tag makes sure the files will be put in place at the correct point in time and the icinga2 service restarted afterwards (see the module's [README](https://github.com/Icinga/puppet-icinga2-rewrite#custom-configuration) for more information).
+
+An example for one such apply rule file would be:
+
+```
+apply Service "nginx-status" to Host {
+    import "generic-service"
+
+    vars += host.vars.checks["nginx-status"]
+    check_command = "nginx_status"
+    command_endpoint = host.vars.client_endpoint
+
+    assign where host.vars.os == "Linux" && host.vars.checks["nginx-status"]
+    ignore where !host.address || !host.vars.client_endpoint || !host.vars.checks
+}
+```
+
+2. Most apply rules are defined on the master and not on the individual nodes. Although it would be preferable to define apply rules as exported resources on the individual nodes – so that they are created only as additional services (profiles) are added to a node, this is not possible when you have more than one node with the same services in your infrastructure since it will lead to duplicate resource definitions.
+
+Compare the `profile::backuppc::server` manifest to the `profile::nginx` profile. In the first, you will find the apply rule definition is exported as a file resource to be collected in `profile::icinga::applyrules` at the very bottom, whereas the second does not contain any `Service` object at all.
+Apply rules for the _nginx_ profile have been defined in `profile::icinga::applyrules` since there are several nodes using this same profile.
+
+The nginx profile, however, additionally installs a check script that does not come with any of the _monitoring-plugins-*_ packages on Debian.
+
 ### Hiera
 
 With a hiera hierarchy as the following (simplified), all nodes will consume both common.yaml and their dedicated yaml file, if they have one:
@@ -38,3 +69,7 @@ We use hiera_array() and hiera_hash() lookup functions from the manifests in ord
 ### Notes
 
 The example is not 100% complete, some of the profile classes that are not relevant to illustrate a master-agent set-up using virtual resources in Puppet are not included and are left as an exercise to the reader.
+
+### Disclaimer
+
+This example does not claim to be a perfect setup. You might have improvements to suggest and those are of course welcome.

examples/example3/site/profile/manifests/backuppc/server.pp

@@ -0,0 +1,54 @@
+class profile::backuppc::server {
+    class { '::backuppc::server': }
+    create_resources('backuppc::server::user', hiera('backuppc_users', []))
+
+    # Icinga CheckCommand and Apply Rules
+    @@icinga2::object::checkcommand { 'backuppc':
+        import      => [
+            'plugin-check-command',
+        ],
+        command     => [
+            'sudo', '-u', 'backuppc',
+            'PluginContribDir + /check_backuppc',
+        ],
+        arguments   => {
+            '-w' => '$backuppc_wtime$',
+            '-c' => '$backuppc_ctime$',
+            '-H' => {
+                'value' => '$backuppc_desired$',
+                'set_if' => '$backuppc_desired$',
+            },
+            '-x' => {
+                'value' => '$backuppc_exclude$',
+                'set_if' => '$backuppc_exclude$',
+            },
+            '-V' => {
+                'set_if' => '$backuppc_version$'
+            },
+            '-a' => {
+                'set_if' => '$backuppc_archiveonly$',
+            },
+            '-b' => {
+                'set_if' => '$backuppc_backuponly$',
+            },
+            '-s' => {
+                'set_if' => '$backuppc_statusonly$',
+            },
+        },
+        vars        => {
+            'backuppc_wtime' => '2',
+            'backuppc_ctime' => '4',
+        },
+        target      => '/etc/icinga2/zones.d/global-templates/backuppc-command.conf',
+    }
+
+    @@file { '/etc/icinga2/conf.d/services/backuppc.conf':
+        ensure  => file,
+        owner   => 'nagios',
+        group   => 'nagios',
+        tag     => 'icinga2::config::exported',
+        source => [
+            "puppet:///modules/1024/icinga/services/backuppc.conf",
+        ],
+    }
+}

examples/example3/site/profile/manifests/icinga/applyrules.pp

@@ -0,0 +1,53 @@
+class profile::icinga::applyrules {
+
+    # Global apply rules
+    # We attempt to export them with the respective services where possible.
+    # However, that only works if the service is unique on the infrastructure and would
+    # not lead to duplicate resources.
+    #
+    # All multi-use (apply) services are defined here.
+    #
+    # We do not use "icinga2::object::service" but files with the "icinga2::config::file" tag. See the
+    # example's README on why this is the case.
+
+    file { '/etc/icinga2/conf.d/services/nginx.conf':
+        ensure  => file,
+        owner   => 'nagios',
+        group   => 'nagios',
+        tag     => 'icinga2::config::file',
+        source => [
+            "puppet:///modules/1024/icinga/services/nginx.conf",
+        ],
+    }
+
+    file { '/etc/icinga2/conf.d/services/postgres.conf':
+        ensure  => file,
+        owner   => 'nagios',
+        group   => 'nagios',
+        tag     => 'icinga2::config::file',
+        source => [
+            "puppet:///modules/1024/icinga/services/postgres.conf",
+        ],
+    }
+
+    file { '/etc/icinga2/conf.d/services/elasticsearch.conf':
+        ensure  => file,
+        owner   => 'nagios',
+        group   => 'nagios',
+        tag     => 'icinga2::config::file',
+        source => [
+            "puppet:///modules/1024/icinga/services/elasticsearch.conf",
+        ],
+    }
+
+    # Collect any files exported and tagged elsewhere (can be created inside
+    # services or master zone)
+    # We need to use a different tag then icinga itself (icinga2::config::file)
+    # or the agent will try to collect any resources tagged so on himself.
+    File <<| ensure != 'directory' and tag == 'icinga2::config::exported' |>> {
+        require => [
+            File['icinga2_masterzone'],
+            File['icinga2_services'],
+        ],
+    }
+}

examples/example3/site/profile/manifests/icinga/server.pp

@@ -69,10 +69,12 @@
     Icinga2::Object::Checkcommand <<| |>> { }->
     Icinga2::Object::NotificationCommand <<| |>> { }
 
+    # Define apply rules that
+    contain profile::icinga::applyrules
+
     # Note: these manifests are not included in this example
     contain profile::icinga::hostgroups
     contain profile::icinga::users
-    contain profile::icinga::applyrules
     contain profile::icinga::timeperiods
     contain profile::icinga::notifications
     contain profile::icinga::checkcommands

examples/example3/site/profile/manifests/nginx.pp

@@ -0,0 +1,25 @@
+class profile::nginx {
+
+    # This profile can be used by many nodes and thus the node configuration is
+    # in the hiera file for the respective node!
+    class { '::nginx':
+        manage_repo => true,
+        package_source => 'nginx-stable'
+    }->
+    class { '::collectd::plugin::nginx':
+        url => 'http://localhost:8433/nginx-status',
+    }
+
+    # Icinga: install check into PluginContribDir
+    # (PluginContribDir could be a fact "icinga2 variable get PluginContribDir",
+    # but for that to work, puppet would probably have to run twice…)
+    file { '/usr/lib/nagios/plugins/check_nginx_status.pl':
+        ensure  => file,
+        mode    => '+x',
+        source => [
+            'puppet:///modules/1024/icinga/plugins/check_nginx_status.pl',
+        ],
+        require => Package['monitoring-plugins-standard'],
+    }
+
+}