1<a id="Automation"></a>Automation - Configuration management
2============================================================
3
4Director has been designed to work in distributed environments. In case
5you're using tools like Puppet, Ansible, Salt (R)?ex or similar, this
6chapter is what you're looking for!
7
8Generic hints
9-------------
10
11Director keeps all of its configuration in a relational database. So,
12all you need to tell him is how it can reach and access that db. In case
13you already rolled out Icinga Web 2 you should already be used to handle
14resource definitions.
15
16The Director needs a `database resource`, and your RDBMS must either by
17MySQL, MariaDB or PostgreSQL. This is how such a resource could look like
18in your `/etc/icingaweb2/resources.ini`:
19
20```ini
21[Director DB]
22type = "db"
23db = "mysql"
24host = "localhost"
25dbname = "director"
26username = "director"
27password = "***"
28charset = "utf8"
29```
30
31Please note that the charset is required and MUST be `utf8`.
32
33Next you need to tell the Director to use this database resource. Create
34its `config.ini` with the only required setting:
35
36```ini
37[db]
38resource = "Director DB"
39```
40
41Hint: `/etc/icingaweb2/modules/director/config.ini` is usually the full
42path to this config file.
43
44#### Schema creation and migrations
45
46You do not need to manually care about creating the schema and to migrate
47it for newer versions. Just `grant` the configured user all permissions on
48his database.
49
50On CLI then please run:
51
52    icingacli director migration run --verbose
53
54You should run this command after each upgrade, or you could also run it
55at a regular interval. Please have a look at...
56
57    icingacli director migration pending --verbose
58
59...in case you are looking for an idempotent way of managing the schema.
60Use `--help` to learn more about those commands.
61
62If you have any good reason for doing so and feel experienced enough you
63can of course also manage the schema on your own. All required files are
64to be found in our `schema` directories.
65
66
67Deploy Icinga Director with Puppet
68----------------------------------
69
70Drop the director source repository to a directory named `director` in
71one of your `module_path`'s and enable the module as you did with all the
72others.
73
74Deploy the mentioned database resource and `config.ini`. Director could
75now be configured and kick-started via the web frontend. But you are here
76for automation, so please read on.
77
78### Handle schema migrations
79
80It doesn't matter whether you already have a schema, did a fresh install
81or just an upgrade. Migrations are as easy as defining:
82
83    exec { 'Icinga Director DB migration':
84        path    => '/usr/local/bin:/usr/bin:/bin',
85        command => 'icingacli director migration run',
86        onlyif  => 'icingacli director migration pending',
87    }
88
89Hint: please do not travel back in time, schema downgrades are not
90supported.
91
92### Kickstart an empty Director database
93
94The Director kickstart wizard helps you with setting up a connection to
95Icinga2 master node, import its endpoint and zone definition and it also
96syncs already configured command definitions. But this wizard is not only
97available through the web frontend, you can perfectly trigger it in an
98idempotent way with Puppet:
99
100    exec { 'Icinga Director Kickstart':
101        path    => '/usr/local/bin:/usr/bin:/bin',
102        command => 'icingacli director kickstart run',
103        onlyif  => 'icingacli director kickstart required',
104        require => Exec['Icinga Director DB migration'],
105     }
106
107Nothing will happen so far. Kickstart will not do anything unless you
108drop a `kickstart.ini` allowing the CLI kickstart helper to do so:
109
110```ini
111[config]
112endpoint = icinga-master
113; host = 127.0.0.1
114; port = 5665
115username = director
116password = ***
117```
118
119Usually `/etc/icingaweb2/modules/director/kickstart.ini` should be the
120full path to this file. `endpoint` (master certificate name), `username`
121and `password` (fitting an already configured `ApiUser`) are required.
122`host` can be a resolvable hostname or an IP address. `port` is 5665 per
123default in case none is given. And of course your Icinga2 installation
124needs to have a corresponding `ApiListener` (look at your enabled
125features) listening at the given port.
126
127You can run the `kickstart` from the CLI if you don't use a tool for
128automation.
129
130    icingacli director kickstart run
131
132You can rerun the kickstart if you have to reimport changed local
133config, even when the beforementioned check tells you you don't need to.
134Or you could use the import/synchronisation features of Director.
135