Configure Zabbix with Ansible

Besides the ability to setup your Zabbix server, proxy and agents, the Ansible collection for Zabbix (ie. community.zabbix) also allows to configure every aspects of your Zabbix system. From hosts to users, discovery rules or even templates. In this blog post, we will see how this module helped me to automatically configure hosts I provision with YaK in my Zabbix server configuration.

Setup community.zabbix

The first step is easy and fast. In your YaK environment, run the following command:

ansible-galaxy collection install community.zabbix

This collection is actually an interface with Zabbix API which make our work easier when we already know Ansible and don’t want to go through complex HTTP API calls (see my other blog post about it).

Setup Ansible Variables

If you know Ansible, you know that all tasks are going through a ssh connection to the target host. Once agent is installed on target host, we want to configure it in Zabbix server. This is achieved by modifying few variables before calling zabbix modules:

- name: Set api configuration facts
  ansible.builtin.set_fact:
    ansible_network_os: community.zabbix.zabbix
    ansible_connection: httpapi
    ansible_httpapi_port: 80
    ansible_zabbix_url_path: ''
    ansible_host: "{{ zabbix_server_ip }}" # Zabbix server
    ansible_user: "{{ zabbix_api_login_user }}"

For requests to be redirected, all tasks concerning our host must go to the zabbix server (line 7). Zabbix server does not understand ssh connection, but httpapi connections (line 4) with ansible_network_os specific to the API (line 3). Authentication against the http api is made with ansible_user as login and ansible_httpapi_pass as password. For better security, we could create an API token and use https.

Usage

Host Group

Before creating our host, we can start with a simpler task like creating a host group:

- name: Create host groups
  community.zabbix.zabbix_group:
    host_group: "{{ zabbix_agent_groups }}"
  register: zabbix_api_hostgroup_created
  until: zabbix_api_hostgroup_created is succeeded

This task calls zabbix_group module with a list of group in host_group argument. Could it be more easier than that?

Note that lines 4 and 5 are there to ensure host group is created as concurrent access (while running against multiple hosts) might raise creation failure. The default value for retries is 3 and with a delay of 5 seconds between each retry.

Host

To create a host in Zabbix configuration, there are a bit more variables to provide to the module:

- name: Create host in zabbix server configuration
  community.zabbix.zabbix_host:
    host_name: "{{ hostname }}"
    host_groups: "{{ zabbix_agent_groups }}"
    link_templates: "{{ zabbix_agent_link_templates }}"
    interfaces: "{{ zabbix_agent_interfaces }}"
    tags: "{{ zabbix_agent_tags }}"
    tls_connect: 2 # PSK
    tls_psk_identity: "{{ zabbix_agent2_tlspskidentity }}"
    tls_psk: "{{ zabbix_agent2_tlspsk_secret }}"
  register: zabbix_api_host_created
  until: zabbix_api_host_created is succeeded

host_name is the how the host will be named in Zabbix configuration (coming from inventory – line 3). host_groups is the list of groups we’ve created previously. link_templates is a list of Zabbix templates.

interfaces (line 6) will be the list of defined interfaces to reach the Zabbix agent from the Zabbix server. This variable content looks like:

    zabbix_agent_interfaces:
      - type: 1
        main: 1
        useip: "{{ zabbix_useuip }}"
        ip: "{{ ansible_host }}"
        dns: ""
        port: "{{ zabbix_agent_listenport }}"

Next tls_* variables are set to encrypt trafic between agent and server.

tags variable allows to have host added with tags in Zabbix configuration.

Et voilà!