---
id: MOD-003
type: module
status: active
title: Monitoring Role (Zabbix Agent 2)
created: 2026-09-09
updated: 2026-09-09
tags: [module, monitoring, zabbix, ansible]
related: [MOD-001, TECH-INTEGRATIONS-ZABBIX, REQ-003, NFR-002]
source_paths:
- roles/monitoring/
confidence: confirmed
---

# Monitoring Role (Zabbix Agent 2)

## Responsibility

Install Zabbix Agent 2, configure TLS-PSK and the Docker plugin, and
register/update the host on the Zabbix server via the API.

## Source Paths

- `roles/monitoring/tasks/main.yml` → `validate.yml`,
  `install-repository.yml`, `install-agent.yml`, `configure-docker.yml`,
  `configure-psk.yml`, `configure-agent.yml`, `register-host.yml`
- Templates: `zabbix_agent2.conf.j2`, `docker.conf.j2`

## Public Interfaces

- Playbook: `playbooks/monitoring.yml` (loads `../vault.yml`)
- Tag: `monitoring`
- Key variables (`defaults/main.yml`, overridden per site in
  `inventory/group_vars/<site>.yml`): `monitoring_zabbix_version` (7.0),
  `monitoring_zabbix_passive_servers`, `monitoring_zabbix_active_servers`,
  `monitoring_zabbix_api_url`, `monitoring_zabbix_api_user`,
  `monitoring_zabbix_api_password` (vault), `monitoring_zabbix_register_host`,
  `monitoring_zabbix_proxy` / `monitoring_zabbix_proxy_address`,
  `monitoring_zabbix_host_groups`, `monitoring_zabbix_templates`,
  `monitoring_zabbix_docker_templates`, PSK settings
  (`monitoring_zabbix_psk_bits: 256`,
  `monitoring_zabbix_psk_store: {{ role_path }}/../../.zabbix-psk`).

## Important Flows

1. Validate inputs → add repo.zabbix.com repo → install `zabbix-agent2`.
2. Docker plugin config when `/var/run/docker.sock` exists.
3. PSK: generate once on the controller (`openssl rand -hex 32`, umask 077,
   `creates:` guard), persist under `.zabbix-psk/<hostname>.psk` (0700),
   validate hex format/length, deploy to `/etc/zabbix/zabbix_agent2.psk`
   (0600), notify restart handler.
4. Agent config: TLS connect/accept = PSK, identity =
   `monitoring_zabbix_host_name`, passive/active servers, listen port 10050.
5. Registration: `community.zabbix.zabbix_host` over httpapi (connection
   params derived from `monitoring_zabbix_api_url` via `urlsplit`), agent
   interface from `ansible_host`, template union adds
   `monitoring_zabbix_docker_templates` when the Docker socket is present,
   `monitored_by` switches to proxy when `monitoring_zabbix_proxy` is set.

## Dependencies

- `community.zabbix` collection; vault variable
  `monitoring_zabbix_api_password`.
- Composed by [bootstrap](./MOD-001-bootstrap-role.md) unless
  `skip_monitoring`.

## Tests

- None automated.

## Notes For Agents

- PSK store is controller-side state; never commit it (git-ignored). When
  renaming a host, migrate/regenerate the PSK, otherwise registration
  drifts (documented in AGENTS.md).
- Template name mismatch between role default (`Docker by Zabbix agent2`)
  and group_vars (`Docker by Zabbix agent 2`) - see open question OQ-005.