doc: add automation chapter

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`:
+
+```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:
+
+```ini
+[db]
+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
+others.
+
+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
+supported.
+
+### 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:
+
+```ini
+[config]
+endpoint = icinga-master
+; host = 127.0.0.1
+; 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.
+