From 7570abb8c1dcccac66f853df6a28297f88bce00d Mon Sep 17 00:00:00 2001
From: Bazaah <github@luxolus.com>
Date: Sat, 10 Dec 2022 08:25:17 +0000
Subject: [PATCH] doc: add example config file for kdnotify watch

This should serve as a good starter for documenting how to use the watch
command of kdnotify.
---
 .gitignore             |  1 +
 doc/example.watch.yaml | 55 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 doc/example.watch.yaml

diff --git a/.gitignore b/.gitignore
index f338c43..35aa823 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,7 @@
 !Makefile
 
 !*.sh
+!*.yaml
 
 !*/
 
diff --git a/doc/example.watch.yaml b/doc/example.watch.yaml
new file mode 100644
index 0000000..758e541
--- /dev/null
+++ b/doc/example.watch.yaml
@@ -0,0 +1,55 @@
+---
+## This is an example configuration file for kdnotify
+
+# Configuration related to the 'kdnotify watch' subcommand
+watch:
+  # Arbitrary KV storage, you can add anything you like here
+  context:
+    MyInstance:
+      VirtualIP: 10.1.0.100/24
+      Device: eth0
+    AnotherInstance:
+      VirtualIP: 10.1.0.200/24
+      Device: eth1
+  # List of rules to apply to incoming VRRP messages
+  rules:
+      # Exec runs the templated command when the rule is triggered
+      #
+      # This rule runs unconditionally, for every message received,
+      # but we can add conditions
+      #
+      # The .Event object has three items: Instance, State and Type, which
+      # can be be used to filter which rules are hit by which events
+    - exec: /bin/logger {{.Event.Instance}} state changed to {{.Event.State}}
+      # This rule only runs when an event with a state of MASTER is detected
+      #
+      # Possible states are: MASTER, BACKUP and STOP
+      # - MASTER | The instance has been promoted to master of its' VIP(s)
+      # - BACKUP | The instance has been demoted, and no longer controls its' VIP(s)
+      # - STOP   | The instance is shutting down, typically because Keepalived is exiting
+    - exec: /bin/logger {{.Event.Instance}} is now MASTER
+      state: MASTER
+      # Conditions can be combined, with each forming a logical AND
+      # Omitted conditions are ignored
+      #
+      # Possible types are:
+      # - INSTANCE | A vrrp_instance as defined in keepalived.conf
+      # - GROUP    | A vrrp_group as defined in the same
+    - exec: /bin/logger Group {{.Event.Instance}} is stopping
+      state: STOP
+      type: GROUP
+      # A more complicated example, introducing the .Cxt object
+      #
+      # The .Cxt object is taken from the watch.context map listed above.
+      # You can add arbitrary metadata to this map and utilize it in your rules,
+      # as shown below
+      #
+      # A couple key points:
+      # - We use the index function from Go's text/template stdlib
+      # - We can list multiple matches for rule conditions, this applies to all
+      #   conditions, not just 'instance'!
+    - exec: >-
+        {{ $i := index .Cxt .Event.Instance }}
+        /bin/logger {{.Event.Instance}} now owns {{$i.VirtualIP}}%{{$i.Device}}
+      instance: [MyInstance, AnotherInstance]
+      state: MASTER