[icinga-checkins] icinga.org: icingaweb2-module-director/master: doc: add automation chapter

git at icinga.org git at icinga.org
Thu Feb 25 11:44:57 CET 2016

Module: icingaweb2-module-director
Branch: master
Commit: 40d505a7fe6783af8ea0372ef9ffbc7030c619e5
URL:    https://git.icinga.org/?p=icingaweb2-module-director.git;a=commit;h=40d505a7fe6783af8ea0372ef9ffbc7030c619e5

Author: Thomas Gelf <thomas at gelf.net>
Date:   Thu Feb 25 11:44:44 2016 +0100

doc: add automation chapter


 doc/30-Automation.md |  126 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)

diff --git a/doc/30-Automation.md b/doc/30-Automation.md
new file mode 100644
index 0000000..fa833b9
--- /dev/null
+++ b/doc/30-Automation.md
@@ -0,0 +1,126 @@
+Automation - Configuration management
+Director has been designed to work in distributed environments. In case
+you're using tools like Puppet, Ansible, Salt (R)?ex or similar, this
+chapter is what you're looking for!
+Generic hints
+Director keeps all of it's configuration in a relational database. So,
+all you need to tell him is how it can reach and access that db. In case
+you already rolled out Icinga Web 2 you should already be used to handle
+resource definitions.
+The Director needs a `database resource`, and your RDMBS must either by
+MySQL, MariaDB or PostgreSQL. This is how such a resource could look like
+in your `/etc/icingaweb2/resources.ini`:
+[Director DB]
+type = "db"
+db = "mysql"
+host = "localhost"
+dbname = "director"
+username = "director"
+password = "***"
+charset = "utf8"
+Please note that the charset is required and MUST be `utf8`.
+Next you need to tell the Director to use this database resource. Create
+it's `config.ini` with the only required setting:
+resource = "Director DB"
+Hint: `/etc/icingaweb2/modules/director/config.ini` is usually the full
+path to this config file.
+#### Schema migrations
+You do not need to manually care about creating the schema and to migrate
+it for newer versions. Just `grant` the configured user all permissions on
+his database.
+On CLI then please run:
+    icingacli director migration run --verbose
+You should run this command after each upgrade, or you could also run it
+at a regular interval. Please have a look at...
+    icingacli director migration pending --verbose
+...in case you are looking for an idempotent way of managing the schema.
+Use `--help` to learn more about those commands.
+If you have any good reason for doing so and feel experienced enough you
+can of course also manage the schema on your own. All required files are
+to be found in our `schema` directories.
+Deploy Icinga Director with Puppet
+Drop the director source repository to a directory named `director` in
+one of your `module_path`'s and enable the module as you did with all the
+Deploy the mentioned database resource and `config.ini`. Director could
+now be configured and kick-started via the web frontend. But you are here
+for automation, so please read on.
+### Handle schema migrations
+It doesn't matter whether you already have a schema, did a fresh install
+or just an upgrade. Migrations are as easy as defining:
+    exec { 'Icinga Director DB migration':
+        path    => '/usr/local/bin:/usr/bin:/bin',
+        command => 'icingacli director migration run',
+        onlyif  => 'icingacli director migration pending',
+    }
+Hint: please do not travel back in time, schema downgrades are not
+### Kickstart an empty Director database
+The Director kickstart wizard helps you with setting up a connection to
+Icinga2 master node, import it's endpoint and zone definition and it also
+syncs already configured command definitions. But this wizard is not only
+available through the web frontend, you can perfectly trigger it in an
+idempotent way with Puppet:
+    exec { 'Icinga Director Kickstart':
+        path    => '/usr/local/bin:/usr/bin:/bin',
+        command => 'icingacli director kickstart run',
+        onlyif  => 'icingacli director kickstart required',
+        require => Exec['Icinga Director DB migration'],
+     }
+Nothing will happen so far. Kickstart will not do anything unless you
+drop a `kickstart.ini` allowing the CLI kickstart helper to do so:
+endpoint = icinga-master
+; host =
+; port = 5665
+username = director
+password = ***
+Usually `/etc/icingaweb/modules/director/kickstart.ini` should be the
+full path to this file. `endpoint` (master certificate name), `username`
+and `password` (fitting an already configured `ApiUser`) are required.
+`host` can be a resolvable hostname or an IP address. `port` is 5665 per
+default in case none is given. And of course your Icinga2 installation
+needs to have a corresponding `ApiListener` (look at your enabled
+features) listening at the given port.

More information about the icinga-checkins mailing list