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