This tool allow manipulate on Zabbix objects, like template, over the restful API, keep congituration in YAML files and store them in git.
It current supports the following:
- Templates (with almost full set of objects)
- Hostgroups
- Autoregistration
- Alerts
- Macros
What it's doesn't support yet, but highly desirable:
- It doesn't flush zabbix configuration
- No users\groups management yet
- No medias yet
The zabbixcli use py-zabbix module. Which can be installed with pip.
pip install py-zabbix
This tool takes yaml formated template files, resolve dependencies, and make appropriate API calls to zabbix server for create template hierarchy or make another actions.
Important: I highly recommend remove any current templates before use this tool, and manage your zabbix templates only with zabbixcli.
Feel free to use any of those templates zabbixcli-templates, modify them or make your own.
The tool usage guide can be found by running zabbixcli with -h
flag
$ zabbixcli -h
usage: zabbixcli [-h] [-t TEMPLATE] [-s SERVER] [-u USER] [-p PASS] [-o] [-d]
[-D DELETE [DELETE ...]]
Template based zabbix configuration tool
optional arguments:
-h, --help show this help message and exit
-t TEMPLATE, --template TEMPLATE
Template name for sync
-s SERVER, --server SERVER
Zabbix server URL
-u USER, --user USER Zabbix user name
-p PASS, --pass PASS Zabbix user password
-o, --only Sync only specified templates
-d, --debug Enable debug mode
-D DELETE [DELETE ...], --delete DELETE [DELETE ...]
Delete object from zabbix. Example: -D item "Template
OS Linux" "Available memory"
First you should configure zabbixcli to works with appropriate zabbix server and use right credentials. You can either specify these as command arguments, or use environment varible, or mix them.
Notice: Command line arguments have precedence over environment variables.
cat >> ~/.bash_profile <<'EOM'
# Cretentials for zabbixcli
export ZBXCLI_USER=admin
export ZBXCLI_PASS=zabbix
export ZBXCLI_URL=https://localhost
export ZBXCLI_TEMPLATES=~/zabbix_templates
EOM
Just run:
$ zabbixcli -t "Template OS Linux"
[05/29/2015 23:48:54] Template 'Template OS Linux' was fully loaded.
...
[05/29/2015 23:48:55] Done.
or go to template directory and run:
$ zabbixcli -t ./
You can delete single object from zabbix. To delete an item from specific template do:
$ zabbixcli -D item "Template OS Linux" "Available memory"
Ok, now you know something about zabbixcli, and started store your zabbix config in repo. We all love automation, so it's time to configure automatic changes apply.
You can use zabbixcli-worker as cronjob to run every minute:
$ crontab -e
# Apply changes to zabbix
*/1 * * * * /usr/local/bin/zabbixcli-worker ~/repo/ configs/zabbix/templates/ >> /var/log/zabbixcli-worker 2>&1
That's it. Now as soon as you will merge your changes to master, they will applied to zabbix.
I'd preffer configure
sparce-checkout
in git to pull only folder with templates (because templates folder was part of saltstack states repo in my case).
I will not detailed describe how to configure sparce-checkout. You can google it. But basicaly you should add in
~/repo/.git/config
:
[core]
sparcecheckout = true
and in ~/repo/.git/info/sparce-checkout
you should add relative path to dir which you only want to pull:
configs/zabbix/templates/
This is kind of tutorual will help you create your first template and apply it to zabbix.
First we need to create a directory for our template:
$ mkdir "Template MyApp"
$ cd ./"Template MyApp"
Then, we should to create init template file.
Template should be written in yaml format.
When zabbixcli runs it search all *.yaml
files in this directory, subdirectories and merge them. So you can specify all setting in one huge init.yaml file, or split it to multiple.
$ cat >> ./init.yaml <<'EOM'
name: "Template MyApp" # Name of template in Zabbix
groups:
- "Templates" # All templates should be added to Templates group
EOM
This will create "Template MyApp" and add it to group "Templates".
Lets try to add an item to monitoring:
$ mkdir apps
$ cat >> ./apps/myapp.yaml <<'EOM'
applications:
"MyApp": # Application name
- name: "MyApp service running" # Item name
key: "proc.num[,,,myapp]" # Item key
description: |
Monitor if MyApp service running or not.
EOM
As you can see many of parameters were not specified. All of them have predefined values, if you not specify something, that values will be use.
Also you can specify just needed section and pass an other.
$ cat >> triggers.yaml <<'EOM'
triggers:
- # Describe trigger
name: "MyApp service is not running on {HOST.NAME}"
warn_level: "Warning"
expression: "{Template MyApp:proc.num[,,,myapp].last(#1)}=0"
EOM
Now we have next structure:
$ tree ./"Template MyApp"
./Template\ MyApp
├── init.yaml
├── apps
│ └── myapp.yaml
└── triggers.yaml
Which will be compile into (yes, you can define all of these in one file):
name: "Template MyApp"
groups:
- "Templates"
applications:
"MyApp":
- name: "MyApp service running"
key: "proc.num[,,,myapp]"
description: |
Monitor if MyApp service running or not.
triggers:
-
name: "MyApp service is not running on {HOST.NAME}"
warn_level: "Warning"
expression: "{Template MyApp:proc.num[,,,myapp].last(#1)}=0"
All you need to do now to apply this template to zabbix is run zabbixcli:
cd ./"Template MyApp"
zabbixcli -t ./
You can aggregate multiple templates into the Role.
Notice: The Role official not implemented in zabbix, so this kind of template aggregation. It will shows under
Roles
hostgroup in templates (That's weird that zabbix mix hostgroups with templates! That's driving me crazy.)
Basically Role is just a template with specific tags and linked templates. So lets create it to see what it is:
$ cd ..
$ mkdir "Role MyApp Server"
$ cat >> ./"Role MyApp Server"/init.yaml <<'EOM'
name: "Role MyApp Server"
templates: # Describe a list of linked templates
- "Template MyApp"
autoreg: # Enable Autoregistration node
metadata: "my_app_role" # If this metadata is found in zabbix_agent.config
add_to_group: # then add discovered host to specifig hostgroup
- "MyApp Servers"
groups:
- "Roles" # Put this role to Roles hostgroup
EOM
It will do next:
- Create template "Role MyApp Server"
- Create "MyApp Servers" hostgroup
- Add "Role MyApp Server" to hostgroup "Roles"
- Link "Template MyApp" to "Role MyApp Server"
- Create AutoRegistration rule:
- If metadata field in zabbix_agent.conf on host contain: "Role MyApp Server" then add host to "MyApp Servers" group and apply "Role MyApp Server" template on it.
Lets apply it to local zabbix server:
$ zabbixcli -t ./"Role MyApp Server"
You can target alerts from specific Role to specific user or groups.
alert:
do:
-
to: "Email" # Media type
to_group: "Zabbix administrators" # Zabbix Group
It will create zabbix action with trigger as an event source:
Name: Alert for "{role name}" Team
Maintenance status not in maintenance
Template = Role Gateway Server
Trigger value = PROBLEM
Trigger severity >= Warning
Send message to user groups: Zabbix administrators via SMS
zabbixcli have default values for mostly objects, so no need specify exactly every parameter in template. If it's not specified, it will use default value.