Tijdens mijn presentatie op de Zabbix Conference Benelux 2025, heb ik gesproken over een “zero downtime” migratie van Zabbix 6.0 naar 7.0. Dit betrof een installatie gebaseerd op PostgreSQL inclusief de TimescaleDB extensie.

Situatie

Een Zabbix 6.0 installatie met meerdere jaren data opgeslagen in PostgreSQL waarbij ook gebruik wordt gemaakt van TimescaleDB. Deze installatie zou gemigreerd worden naar nieuwe servers (het operating system en database zouden hierbij ook bijgewerkt worden naar een recente stabiele release).

De huidige Zabbix installatie bevat meer dan 1000 hosts met +/- 100.000 items. De opgeslagen historie en trends gaan 2 jaar terug en er mag geen historie of trends data verloren gaan. Ook de data van de periode van de migratie (+/- 3 weken ivm testen van nieuwe templates, dashboards, media-items, etc.) moet na migratie zichtbaar zijn in de nieuwe Zabbix (7.0) installatie.

Uitdagingen (er bestaan geen problemen ;-))

Database dump (backup): Een PostgreSQL database met daaraan de extensie TimescaleDB, zorgt ervoor dat bij een “standaard” PostgreSQL dump (aka backup) data uit de TimescaleDB niet in de dump wordt meegenomen. Alleen de layout/schema van de betreffende tabellen zal worden opgeslagen, data niet (!let op bij backups dat je hier rekening mee houdt!).

Opslagruimte: Exporteren van TimescaleDB-gegevens vraagt om veel storage. TimescaleDB compressed de data zeer goed, gemiddeld neemt data maar 10% in van wat het uncompressed zou zijn. In dit geval was voor een Zabbix database van 60 GB dus zo’n 500 GB aan opslagruimte nodig om de data te exporteren!

Ontbrekende metrics: Zodra de configuratie van Zabbix is overgezet naar de nieuwe installatie, zullen nieuw binnengehaalde meetgegevens (Zabbix 6 is nog in productie) niet in de Zabbix 7 installatie worden opgeslagen. Bij een langere migratie periode (om nieuwe templates/dashboards/etc. te testen) zal dus in de Zabbix 7 installatie een periode ontstaan van ontbrekende meetgegevens.

Dubbele data: Uitgezocht moet worden hoe historie en trend data later geïmporteerd kan worden in een reeds draaiende Zabbix 7 server (database) en gegevens die daar reeds in staan, niet worden overschreven.

Voordelen

Snelheid: Door te werken met een PostgreSQL dump zonder historie en trend data, zal deze backup en ook de import (restore) actie zeer snel afgerond zijn. Het daadwerkelijke upgraden naar & testen van Zabbix 7 zal hierdoor ook snel van start kunnen gaan.

Zero downtime: Het is mogelijk 2 Zabbix installaties tegelijk online te hebben, waardoor geen periode ontstaat van ontbrekende meetgegevens. Hiermee wordt de migratie inclusief upgrade dus een “zero downtime” migratie.

Zabbix migratie stappen

Server Zabbix 6:

Allereerst moet de Zabbix 6 database worden “gedumpt”, hierbij neem ik aan dat de Zabbix database op de Zabbix-server staat en “zabbix” is genoemd en het schema op “public” staat.

sudo -u postgres pg_dump -Fc -Z 5 -d zabbix --exclude-table-data=history* --exclude-table-data=trends* -n public --disable-triggers > zabbix_full-nohist.dump

Server Zabbix 7:

Zorg ervoor dat zowel PostgreSQL als TimescaleDB op deze machine zijn geïnstalleerd en functioneren.

Hierna kan een nieuwe database (en mogelijk ook user) worden aangemaakt op de Zabbix 7 server:

su - postgres
createuser --pwprompt zabbix
createdb -O zabbix -E Unicode -T template0 zabbix

Nu kan de eerder gemaakte PostgreSQL backup worden geïmporteerd. Uiteraard moet de zojuist gemaakte PostgreSQL-dump eerst naar de Zabbix 7 server zijn gekopieerd.

su - postgres 
pg_restore -Fc -v -d zabbix zabbix_full-nohist.dump

Zodra deze backup is geïmporteerd, kan de TimescaleDB extensie worden geactiveerd:

su - postgres
psql -d zabbix -X
\dx
CREATE EXTENSION IF NOT EXISTS timescaledb CASCADE;
\dx
\q

Start de Zabbix 7 server voor de eerste keer om de database upgrade te doorlopen en controleer of de upgrade goed gaat. Zodra deze 100% is afgerond, mag Zabbix weer worden uitgezet voor de volgende stap.

sudo systemctl start zabbix-server
sudo tail -f /var/log/zabbix/zabbix_server.log

Na de upgrade moet het TimescaleDB schema op de Zabbix database worden toegepast:

sudo systemctl stop zabbix-server
cat /usr/share/zabbix-sql-scripts/postgresql/timescaledb/schema.sql | sudo -u zabbix psql zabbix

sudo systemctl start zabbix-server

Na deze stappen te hebben uitgevoerd, is de Zabbix 6 server gemigreerd en bijgewerkt naar versie 7.0. Op dit moment is alle configuratie (hosts, items, templates, dashboards, etc.) overgezet. Het enige wat mist, is de historie en trends data. Deze kunnen op een later tijdstip worden toegevoegd, maar monitoring via deze server kan al gestart worden!

Migratie historie en trends data

Op een later te kiezen tijdstip (dit mag uiteraard ook direct worden uitgevoerd) kunnen de historie en trends gegevens uit TimescaleDB worden gehaald en in de reeds functionerende Zabbix 7 server worden geïmporteerd. De stappen uit te voeren, volgen hieronder:

Allereerst moeten wat SQL-scripts vanuit GitHub worden gedownload.

Server Zabbix 6:

Zet het export-hist-trends.sql in een directory waar ook de data in geëxporteerd mag worden (let op dat er genoeg opslagruimte vrij is!) en waar de user postgres lees & schrijf rechten heeft:

su - postgres
cd /<pad waar data mag komen te staan>
psql -U zabbix -h localhost -d zabbix -f export-hist-trends.sql

Na een tijd (dit kan bij veel data lang duren, gebruik dus screen of tmux!) zullen een aantal .CSV bestanden in deze directory komen te staan. Dit zijn:

• history.csv
• history_log.csv
• history_str.csv
• history_text.csv
• history_uint.csv
• history_bin.csv ¹
• trends.csv
• trends_uint.csv

Server Zabbix 7:

Zorg dat de CSV-bestanden van de Zabbix 6 server naar de Zabbix 7 server (of database-server) zijn gekopieerd. Hierna kan het importeren van deze data starten. Vanaf de eerder genoemde GitHub pagina, dient het script import-hist-trends-no-duplicates.sql in dezelfde directory als de CSV-bestanden te staan.

Het importeren van data kan lang duren, zeker bij veel data, zorg dus ook hier dat het importeren met tmux of screen wordt uitgevoerd.

su - postgres
cd /<pad waar CSV-bestanden staan>
psql -U zabbix -h localhost -d zabbix -e -f import-hist-trends-no-duplicates.sql

Met de uitvoering van dit script wordt de data vanuit CSV in de Zabbix 7 database geïmporteerd, waarbij gecontroleerd wordt of van bepaalde items al data bestaat die op hetzelfde tijdstip zijn aangemaakt als waar de data uit Zabbix 6 op is aangemaakt. Zodra dit niet zo is, wordt data geïmporteerd. Is dit wel zo, dan wordt data van dat tijdstip voor dat specifieke item genegeerd.

Einde en “zero downtime” migratie uitgevoerd!

Zodra alle data is geïmporteerd, zal dit o.a. te zien zijn aan de grafieken van items die nu weer voor langere tijd terug data kunnen tonen. Hiermee is de migratie volledig afgerond en zullen ook geen periodes zichtbaar zijn waarin geen meetgegevens zijn binnengekomen.

1. Deze is afwezig of leeg aangezien deze tabel pas vanaf Zabbix 7 bestaat! ↩︎