zabbix apiを使ってメンテナンス設定・解除する

サーバアプリケーションのデプロイ時等に、不要なアラートや自動復旧設定を抑制するためzabbixをメンテナンス状態にしたい場合があります。zabbixのGUIからメンテナンス設定しておけば良いのですが、Jenkins等のCI/CD環境が整っているのに、メンテナンス設定だけはGUIから手動というのは面倒なのと、設定漏れのリスクがあります。
そんなこんなで、zabbix APIについて調べたので残しておきます。

注意点

zabbixのVerによって、zabbix APIの仕様やサポート是非が異なっていることがあります
この記事はzabbix ver：4.0系で記載しています
Verが異なる場合は、API仕様で確認しながら実装すると良いです

Zabbix APIを使ってみる

早速使ってみます
基本は、認証（TOKEN取得）→実行したい処理（TOKEN利用）→ログアウト（TOKEN破棄）の流れになります

TOKENを取得する

まずは、どのAPIを使うにも認証を済ませる必要があります
userにはエイリアス（ログインID）、passwordにはログインパスワードを指定します

curl -s -d '
{
    "jsonrpc": "2.0" ,
    "method": "user.login",
    "params": {
        "user": "XXXXXXX",
        "password": "YYYYYYYY"
    },
    "id": 1
}
' -H "Content-Type: application/json-rpc" https://xxxxxx.xxxx.xxx/zabbix/api_jsonrpc.php

認証が通れば、TOKENが返却されます
以降のAPIを使うためには、このTOKENが必要になります

{"jsonrpc":"2.0","result":"hogehogehogehogehogehogehogehoge","id":1}

ホストグループを取得する

ホストグループのgroupidを確認できます
filterは任意項目で、指定しなければ全てのホストグループが取得できます

curl -s -d '
{
    "jsonrpc": "2.0" ,
    "method": "hostgroup.get",
    "params": {
        "output": "extend",
        "filter": {
            "name": [
                "fuga"
            ]
        }
    },
    "auth": "hogehogehogehogehogehogehogehoge",
    "id": 1
}
' -H "Content-Type: application/json-rpc" https://xxxxxx.xxxx.xxx/zabbix/api_jsonrpc.php

メンテナンスを設定する

メンテナンスの設定例です
この例では、ホストグループを指定したメンテナンスを設定しています
ホストグループは、groupidで指定する必要があるので上のAPIで取得しておきましょう
active_since、active_tillは十分な期間にしておけば良いと思います

curl -s -d '
{
    "jsonrpc": "2.0",
    "method": "maintenance.create",
    "params": {
            "name": "testmaintenance",
            "active_since": 1645714800,
            "active_till": 1964271600,
            "groupids": [
                "15"
            ],
            "timeperiods": [
                {
                    "timeperiod_type": 0,
                    "period": 6000
                }
            ]
    },
    "auth": "hogehogehogehogehogehogehogehoge",
    "id": 1
}
' -H "Content-Type: application/json-rpc" https://xxxxxx.xxxx.xxx/zabbix/api_jsonrpc.php

メンテナンスを設定すると、maintenanceidが割り振られます

{"jsonrpc":"2.0","result":{"maintenanceids":["12"]},"id":1}

メンテナンス情報を取得する

メンテナンス設定後でも、maintenanceidを取得することができます
ホストグループの取得と同じように、filterを指定することも可能です

curl -s -d '
{
    "jsonrpc": "2.0",
    "method": "maintenance.get",
    "params": {
        "output": "extend"
    },
    "auth": "hogehogehogehogehogehogehogehoge",
    "id": 1
}
' -H "Content-Type: application/json-rpc" https://xxxxxx.xxxx.xxx/zabbix/api_jsonrpc.php

メンテナンスを削除する

maintenanceid指定で、メンテナンスを削除（解除）することができます

curl -s -d '
{
    "jsonrpc": "2.0",
    "method": "maintenance.delete",
    "params": [
        "12"
    ],
    "auth": "hogehogehogehogehogehogehogehoge",
    "id": 1
}
' -H "Content-Type: application/json-rpc" https://xxxxxx.xxxx.xxx/zabbix/api_jsonrpc.php

TOKENを破棄する

APIを使い終えたら、TOKENを破棄してしまいしょう

curl -s -d '
{
    "jsonrpc": "2.0" ,
    "method": "user.logout",
    "params": [ ],
    "auth": "hogehogehogehogehogehogehogehoge",
    "id": 1
}
' -H "Content-Type: application/json-rpc" https://xxxxxx.xxxx.xxx/zabbix/api_jsonrpc.php

まとめ

zabbix APIは、curlで簡単に使うことができます
Ver違いによるAPI差分には注意した方が良いです
shell script等で実装すれば、デプロイ前後で自動メンテナンス設定することができそうです
他にもかなりの種類のAPI（API仕様）があるようです、アイテムやトリガーの設定等もGUIより楽かもしれないですね