Documentation: Add dependency example for setting locally scoped variables

fixes #7319

diff --git a/doc/1-about.md b/doc/1-about.md
index 58fa5b12ac9cca1a4e028b9cf1f7548134d5cf5a..6a6e93fa5f1f1608446bd5169c488d3469b08437 100644 (file)
--- a/doc/1-about.md
+++ b/doc/1-about.md
@@ -205,6 +205,8 @@ same way as "mixed" dependencies from a service to a parent host and vice versa.
 depending on an upstream link port (as service) are not a problem anymore.
 No more additional parents settings - host dependencies already define the host parent relationship
 required for network reachability calculations.
+Set parent host/services based on [host/service custom attributes](#dependencies-apply-custom-attributes)
+generated from your cloud inventory or CMDB and make your dependency rules simple and short.
 
 * [Recurring Downtimes](#recurring-downtimes)
 

diff --git a/doc/4-monitoring-basics.md b/doc/4-monitoring-basics.md
index 7b872c6d679702d443732764448aeb7719348213..f37fc16ec7a2f18a4ef57cbf25c7a38d0f853ad5 100644 (file)
--- a/doc/4-monitoring-basics.md
+++ b/doc/4-monitoring-basics.md
@@ -1405,6 +1405,76 @@ be suppressed. This is achieved by setting the `disable_checks` attribute to `tr
       assign where host.name != "dsl-router"
     }
 
+### <a id="dependencies-apply-custom-attributes"></a> Apply Dependencies based on Custom Attributes
+
+You can use [apply rules](#using-apply) to set parent or
+child attributes e.g. `parent_host_name`to other object's
+attributes.
+
+A common example are virtual machines hosted on a master. The object
+name of that master is auto-generated from your CMDB or VMWare inventory
+into the host's custom attributes (or a generic template for your
+cloud).
+
+Define your master host object:
+
+    /* your master */
+    object Host "master.example.com" {
+      import "generic-host"
+    }
+
+Add a generic template defining all common host attributes:
+
+    /* generic template for your virtual machines */
+    template Host "generic-vm" {
+      import "generic-host"
+    }
+
+Add a template for all hosts on your example.com cloud setting
+custom attribute `vm_parent` to `master.example.com`:
+
+    template Host "generic-vm-example.com" {
+      import "generic-vm"
+      vars.vm_parent = "master.example.com"
+    }
+
+Define your guest hosts:
+
+    object Host "www.example1.com" {
+      import "generic-vm-master.example.com"
+    }
+
+    object Host "www.example2.com" {
+      import "generic-vm-master.example.com"
+    }
+
+Apply the host dependency to all child hosts importing the
+`generic-vm` template and set the `parent_host_name`
+to the previously defined custom attribute `host.vars.vm_parent`.
+
+    apply Dependency "vm-host-to-parent-master" to Host {
+      parent_host_name = host.vars.vm_parent
+      assign where "generic-vm" in host.templates
+    }
+
+You can extend this example, and make your services depend on the
+`master.example.com` host too. Their local scope allows you to use
+`host.vars.vm_parent` similar to the example above.
+
+    apply Dependency "vm-service-to-parent-master" to Service {
+      parent_host_name = host.vars.vm_parent
+      assign where "generic-vm" in host.templates
+    }
+
+That way you don't need to wait for your guest hosts becoming
+unreachable when the master host goes down. Instead the services
+will detect their reachability immediately when executing checks.
+
+> **Note**
+>
+> This method with setting locally scoped variables only works in
+> apply rules, but not in object definitions.
+
 
 ### <a id="dependencies-agent-checks"></a> Dependencies for Agent Checks