diff options
Diffstat (limited to 'doc/05-Upgrading.md')
| -rw-r--r-- | doc/05-Upgrading.md | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/doc/05-Upgrading.md b/doc/05-Upgrading.md new file mode 100644 index 0000000..63630b6 --- /dev/null +++ b/doc/05-Upgrading.md @@ -0,0 +1,230 @@ +<a id="Upgrading"></a>Upgrading +=============================== + +Icinga Director is very upgrade-friendly. We never had any complaint referring +data loss on upgrade. But to be on the safe side, please always [backup](#backup-first) +your database before running an upgrade. + +Then drop the new version to your Icinga Web 2 module folder, and you're all done. +Eventually refresh the page in your browser<sup>[[1]](#footnote1)</sup>, and you +are ready to go. + +Should there any other actions be required (like [schema migrations](#schema-migrations)), +you will be told so in your frontend. + +Please read more about: + +* [Database Backup](#backup-first) +* [Upgrading to 1.10.x](#upgrade-to-1.10.x) +* [Upgrading to 1.9.x](#upgrade-to-1.9.x) +* [Upgrading to 1.8.x](#upgrade-to-1.8.x) +* [Upgrading to 1.7.x](#upgrade-to-1.7.x) +* [Upgrading to 1.6.x](#upgrade-to-1.6.x) +* [Upgrading to 1.5.x](#upgrade-to-1.5.x) +* [Upgrading to 1.4.x](#upgrade-to-1.4.x) +* [Upgrading to 1.3.0](#upgrade-to-1.3.0) +* [Upgrading to 1.2.0](#upgrade-to-1.2.0) +* [Upgrading to 1.1.0](#upgrade-to-1.1.0) +* [How to work with the latest GIT master](#git-master) +* [Database schema upgrades](#schema-migrations) +* [Job Runner restart](#restart-jobrunner) +* [Downgrading](#downgrade) + +And last but not least, having a look at our [Changelog](82-Changelog.md) is +usually a good idea before applying an upgrade. + +<a name="backup-first"></a>Always take a backup first +----------------------------------------------------- + +All you need for backing up your Director is a snapshot of your database. Please +use the tools provided by your database backend, like `mysqldump` or `pg_dump`. +Restoring from a backup is trivial, and Director will always be able to apply +pending database migrations to an imported old database snapshot. + +<a name="upgrade-to-1.9.x"></a>Upgrading to 1.10.x +-------------------------------------------------- + +Please check module dependencies, we raised some of them. In case you're missing +one of them, the Web UI will tell you after the upgrade. You'll then be prompted +to apply pending Database Migrations. + +PHP 7.3 is now claimed to be required, but we still support 5.6+ on Director +v1.10.x. Same goes for database dependencies: you should upgrade them to recent +versions, but v1.10 still works on the ones supported with v1.9.x. + +<a name="upgrade-to-1.9.x"></a>Upgrading to 1.9.x +------------------------------------------------- + +Please check module dependencies, we raised some of them. In case you're missing +one of them, the Web UI will tell you after the upgrade. You'll then be prompted +to apply pending Database Migrations. + +<a name="upgrade-to-1.8.x"></a>Upgrading to 1.8.x +------------------------------------------------- + +Before upgrading, please upgrade the [incubator module](https://github.com/Icinga/icingaweb2-module-incubator) +to (at least) v0.6.0. As always, you'll be prompted to apply pending Database +Migrations. + +<a name="upgrade-to-1.7.x"></a>Upgrading to 1.7.x +------------------------------------------------- + +Since v1.7.0 Icinga Director requires at least PHP 5.6. Also, this version +introduces new dependencies. Please make sure that the following Icinga Web 2 +modules have been installed and enabled: + +* [ipl](https://github.com/Icinga/icingaweb2-module-ipl) (>=0.3.0) +* [incubator](https://github.com/Icinga/icingaweb2-module-incubator) (>=0.5.0) +* [reactbundle](https://github.com/Icinga/icingaweb2-module-reactbundle) (>=0.7.0) + +Also, the following PHP libraries should be available: + +* php-pcntl (might already be built into your PHP binary) +* php-posix (on RHEL/CentOS this is php-process, or rh-php7x-php-process) +* php-sockets (might already be built into your PHP binary) + +Apart from this, in case you are running 1.6.x or any GIT master since then, +all you need is to replace the Director module folder with the new one. Or to +run `git checkout v1.7.x` in case you installed Director from GIT. + +As always, you'll then be prompted to apply pending Database Migrations. There +is now a new, modern (and mandatory) Background Daemon, the old (optional) Jobs +Daemon must be removed. Please check our [documentation](75-Background-Daemon.md) +for related instructions. + +<a name="upgrade-to-1.6.x"></a>Upgrading to 1.6.x +------------------------------------------------- + +There is nothing special to take care of. In case you are running 1.5.x or any +GIT master since then, all you need is to replace the Director module folder +with the new one. Or to run git checkout v1.6.0 in case you installed Director +from GIT. + +As always, you'll then be prompted to apply pending Database Migrations. + +<a name="upgrade-to-1.5.x"></a>Upgrading to 1.5.x +------------------------------------------------- + +There is nothing special to take care of. In case you are running 1.4.x or any +GIT master since then, all you need is to replace the Director module folder +with the new one. Or to run git checkout v1.5.0 in case you installed Director +from GIT. + +As always, you'll then be prompted to apply pending Database Migrations. + +<a name="upgrade-to-1.4.x"></a>Upgrading to 1.4.x +------------------------------------------------- + +Since v1.4.0 Icinga Director requires at least PHP 5.4. Apart from this, there +is nothing special to take care of. In case you are running 1.3.x or any GIT +master since then, all you need is to replace the Director module folder with +the new one. Or to run `git checkout v1.4.x` in case you installed Director +from GIT. + +<a name="upgrade-to-1.3.x"></a>Upgrading to 1.3.x +------------------------------------------------- + +In case you are running 1.2.0 or any GIT master since then, all you need is to +replace the Director module folder with the new one. Or to run `git checkout v1.3.x` +in case you installed Director from GIT. + +When running Director since 1.1.0 or earlier on PostgreSQL, you might not yet +have the PostgreSQL crypto extension installed (Package: `postgresql-contrib`) and +enabled: + + psql -q -c "CREATE EXTENSION pgcrypto;" + + +<a name="upgrade-to-1.2.0"></a>Upgrading to 1.2.0 +------------------------------------------------- + +There is nothing special to take care of. In case you are running 1.1.0 or any +GIT master since then, all you need is to replace the Director module folder with +the new one. Or to run `git checkout v1.2.0` in case you installed Director from +GIT. + +<a name="upgrade-to-1.1.0"></a>Upgrading to 1.1.0 +------------------------------------------------- + +There is nothing special to take care of. In case you are running 1.0.0 or any +GIT master since then, all you need is to replace the Director module folder with +the new one. Or to run `git checkout v1.1.0` in case you installed Director from +GIT. + +<a name="git-master"></a>Work with the latest GIT master +-------------------------------------------------------- + +Icinga Director is still a very young project. Lots of changes are going on, +a lot of improvements, bug fixes and new features are still being added every +month. People living on the bleeding edge might prefer to use all of them as +soon as possible. + +So here is the good news: this is no problem at all. It's absolutely legal and +encouraged to run Director as a pure GIT clone, installed as such: + +```sh +ICINGAWEB_MODULES=/usr/share/icingaweb2/modules +DIRECTOR_GIT=https://github.com/Icinga/icingaweb2-module-director.git +git clone $DIRECTOR_GIT $ICINGAWEB_MODULES/director +``` + +Don't worry about schema upgrades. Once they made it into our GIT master there +will always be a clean upgrade path for you, no manual interaction should ever +be required. Like every human being, we are not infallible. So, while our strict +policy says that the master should never break, this might of course happen. + +In that case, please [let us know](https://github.com/Icinga/icingaweb2-module-director/issues). +We'll try to fix your issue as soon as possible. + +<a name="schema-migrations"></a>Database schema migrations +---------------------------------------------------------- + +In case there are any DB schema upgrades (and that's still often the case) this +is no problem at all. They will pop up on your Director Dashboard and can be +applied with a single click. And if your Director is deployed automatically by +and automation tool like Puppet, also schema upgrades can easily be handled +that way. Just follow the [related examples](03-Automation.md) in our documentation. + +<a name="schema-migrations"></a>Manual schema migrations +---------------------------------------------------------- + +Please *do not* manually apply our schema migration files. We are very strict +about our connection settings, encodings and SQL modes. Client encoding MUST be +UTF-8, for MySQL and MariaDB we are using the following SQL Mode: + +```sql +SET SESSION SQL_MODE='STRICT_ALL_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, +ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,ANSI_QUOTES,PIPES_AS_CONCAT, +NO_ENGINE_SUBSTITUTION'; +``` + +Our migration files are written based on the assumption that those rules are +strictly followed, and there may be other ones in future. So please use one +of the supported migration methods either on the web or on command line and +stay away from directly interfering with the schema. + +<a name="restart-jobrunner"></a>Restart the Job Runner service +-------------------------------------------------------------- + +The Job Runner forks it's jobs, so usually a changed code base will take effect +immediately. However, there might be (schema or code) changes involving the Runner +process itself. To be on the safe side please always restart it after an upgrade, +even when it's just a quick `git pull`: + +```sh +systemctl restart director-jobs.service +``` + +<a name="downgrade"></a>Downgrading +----------------------------------- + +Downgrading is **not supported**. Most parts of the code will even refuse to +work in case there are new fields in their database tables. Migrations are +intentionally provided for upgrades only. In case you want to travel back in +time please restore a matching former [Database Backup](#backup-first). + +<a name="footnote1">[1]</a>: +Future Icinga Web 2 version will also take care of this step. We want to be +able to have the latest JavaScript and CSS for any active module to be shipped +silently without manual interaction to any connected browser within less then +15 seconds after the latest module has been installed, enabled or upgraded. |