Ansible Role: Zabbix Agent

This role installs and configures the Zabbix Agent 2. The agent is configured to talk to a Zabbix proxy (or server) and, by default, uses a pre-shared key (PSK) for encryption.

Requirements

Operating System	Version
Alpine	3.23
Debian	13
SLES	15
Ubuntu	24.04 LTS

Dependencies

The role zabbix_prereq must run first. It installs the Zabbix package repository (not needed on Alpine, which uses its own packages). The included playbook.yaml does this for you.

Variables

Variable	Required	Default	Description
zabbix_agent_enable	No	true	Enable or disable the whole role
zabbix_major_version	No	"7.4"	Zabbix major version to install (reinstalls on mismatch)
zabbix_agent_psk_enable	No	true	Enable PSK encryption (TLSConnect and TLSAccept)
zabbix_agent_psk_id	Yes*		PSK identity
zabbix_agent_psk	Yes*	"superlongpsk"	PSK value, written to /etc/zabbix/zabbix_agent.psk
zabbix_agent_listen_port	No	"10050"	Port the agent listens on
zabbix_agent_hostname	No	inventory_hostname	Host name as shown in Zabbix
zabbix_agent_hostinterface	No	inventory_hostname	Address Zabbix uses to connect to the host
zabbix_proxy_address	No	"zabbix.example.com"	Zabbix proxy or server (used for Server and ServerActive)
zabbix_proxy_port	No	"10051"	Port of the proxy or server for active checks
zabbix_user_sudo	No	true	Install a sudoers file giving the zabbix user passwordless sudo

* Only if zabbix_agent_psk_enable is true. The default PSK is a placeholder: always override it.

The PSK is a secret and belongs in sops-encrypted inventory variables.

Example

With PSK:

zabbix_proxy_address: "proxy.monitor.localnet.internal"
zabbix_agent_psk_id: "client-psk"
zabbix_agent_psk: "replace-with-sops-encrypted-psk"

Without PSK:

zabbix_proxy_address: "proxy.monitor.localnet.internal"
zabbix_agent_psk_enable: false

DNS override

If DNS is complicated or permanently broken for some reason, the hostname and hostinterface can be overridden. The hostname is the visible name in Zabbix. The hostinterface is what Zabbix uses to connect to the host.

zabbix_agent_hostname: "server.example.com"
zabbix_agent_hostinterface: "192.168.10.10"

This is possible, but please only use it if really required.

What the role does

• Installs zabbix-agent2 and its plugins (zabbix-agent2-plugin-*) when the installed version does not match zabbix_major_version. The existing agent packages are removed first.
• Writes /etc/zabbix/zabbix_agent2.conf and the PSK file /etc/zabbix/zabbix_agent.psk.
• Copies the plugin configuration files from files/zabbix/plugins.d/ (currently nvidia.conf) to /etc/zabbix/zabbix_agent2.d/plugins.d/.
• Adds the zabbix user to the docker group when that group exists.
• Installs /etc/sudoers.d/zabbix (zabbix ALL=(ALL) NOPASSWD: ALL) when zabbix_user_sudo is true.
• Restarts and enables the zabbix-agent2 service when configuration changes.

The generated configuration also sets AllowKey=system.run[*], so remote commands are permitted. Keep the agent reachable only from your proxy or server.

Usage

Run the role through Semaphore using playbook.yaml. The playbook first runs ansible-galaxy install -f -r roles/requirements.yml on the controller to fetch the latest zabbix_prereq and zabbix_agent roles, then executes both on all hosts.

The agent listens on TCP zabbix_agent_listen_port (default 10050).