Skip to content

zabbix_agent: selectable TLS mode and host registration through the API - #2747

Draft
scibi wants to merge 4 commits into
debops:masterfrom
scibi:feature/zabbix-agent-improvements
Draft

scibi wants to merge 4 commits into
debops:masterfrom
scibi:feature/zabbix-agent-improvements

Conversation

@scibi

@scibi scibi commented Aug 24, 2026 •

Copy link
Copy Markdown
Member

This adds two features to the debops.zabbix_agent role. The new
zabbix_agent__tls_mode variable selects how the agent encrypts its
connections: a pre-shared key is still the default, the cert mode uses the
host certificate and CA from a PKI realm managed by the debops.pki role,
and the unencrypted mode disables TLS. In the cert mode the role adds
the Zabbix account to the group which owns the private key of the realm and
installs a PKI hook which restarts the agent after the certificate is
renewed, because the agent reads it only at startup. The PSK identity and
key are generated and installed only in the psk mode.

The second feature is an optional registration of the host in Zabbix
through the JSON-RPC API, because the built-in active agent autoregistration
cannot configure certificate-based encryption on the hosts it creates. The
host groups, templates, macros and tags of the host object are defined in
the inventory, and the encryption settings follow the TLS mode of the agent;
interfaces, groups, templates, macros and tags added to the host in Zabbix
by other means are preserved. The lists use the usual DebOps layers with the
defaults in separate __default_* variables; groups and templates are
merged by name and macros by the macro name, so an entry in the absent
state on the host level can remove the host from a group, unlink a template
without clearing its items or remove a macro set on an inventory group. Tags
stay pairs of a name and a value, since Zabbix allows one tag with several
values, and a pair in the absent state is removed from the host. A host
without IPv4 gets its default IPv6 address in the agent interface. The
registration requires Zabbix 6.4 or newer
and an API token created in Zabbix and stored in the secret/ directory,
and in check mode it only queries the API. I use the cert mode with the
API registration on a Debian 13 host with Zabbix Agent 2 and Zabbix 7.0;
the psk and unencrypted modes were tested by rendering the
configuration, and the registration against a mock of the API, with
ansible-core 2.18 and 2.21. The role is also added to the CI pipeline.

@scibi
scibi force-pushed the feature/zabbix-agent-improvements branch from a03afd0 to 6c95350 Compare August 28, 2026 14:54
@scibi
scibi force-pushed the feature/zabbix-agent-improvements branch from 6c95350 to 6a160ed Compare September 16, 2026 12:44
@scibi
scibi force-pushed the feature/zabbix-agent-improvements branch 3 times, most recently from fc84b81 to 42e8d60 Compare September 29, 2026 23:07
@scibi
scibi force-pushed the feature/zabbix-agent-improvements branch from 42e8d60 to b07bf5b Compare October 6, 2026 15:24
@scibi
scibi force-pushed the feature/zabbix-agent-improvements branch from b07bf5b to 08bd58c Compare October 23, 2026 23:58
@scibi
scibi force-pushed the feature/zabbix-agent-improvements branch from 08bd58c to 30d88b3 Compare November 16, 2026 18:26
@scibi scibi changed the title zabbix_agent: TLS modes, UserParameters, cgroup metrics, API self-registration zabbix_agent: selectable TLS mode and host registration through the API Nov 16, 2026
@scibi
scibi force-pushed the feature/zabbix-agent-improvements branch from 30d88b3 to 421718f Compare November 16, 2026 20:02
scibi and others added 4 commits November 22, 2026 02:02
The new zabbix_agent__tls_mode variable selects how the agent encrypts
its connections to the Zabbix Server or Proxy. A pre-shared key stays
the default; the "cert" mode uses the host certificate, private key and
CA bundle from a PKI realm managed by the debops.pki role, and the
"unencrypted" mode disables TLS. The PSK identity and key are generated
only in the "psk" mode, and the key file is removed in other modes.

In the "cert" mode the Zabbix UNIX account is added to the group which
owns the private files of the PKI realm, and a PKI hook restarts the
agent when its certificate is renewed, because the agent reads the
certificate only at startup. Additional UNIX groups for the account can
now also be defined for inventory groups and hosts. The role checks the
selected mode before it changes the configuration.

An LLM wrote the changes under my direction and rewrote them after a
review of an earlier, larger version of this branch. I reviewed the
result. The "cert" mode and the PKI hook run on a Debian 13 host with
Zabbix Agent 2 and Zabbix 7.0; the "psk" and "unencrypted" modes were
tested by rendering the templates with ansible-core 2.18 and 2.21.

Generated-By: LLM (Claude Code, Cursor)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When zabbix_agent__api_register is enabled, the role creates or updates
the host object in Zabbix through its JSON-RPC API, by default from the
Ansible Controller. The built-in active agent autoregistration cannot
configure certificate-based encryption on the hosts it creates, so it
does not work together with the "cert" TLS mode.

Host groups, templates, user macros and tags are defined in the
inventory, on top of the "Linux servers" host group and the "Linux by
Zabbix agent" template set in separate default variables of the role.
Host groups and templates are merged by name and macros by the macro
name, so a later inventory level overrides an earlier one. Entries in
the "absent" state remove the host from a host group, unlink a template
without clearing its items, or remove a macro. Tags are kept as pairs
of a name and a value, since Zabbix allows several values of one tag,
and a pair in the "absent" state is removed from the host. Missing host
groups are created, and templates which do not exist in Zabbix are
skipped with a warning.

Interfaces, host groups, templates, macros and tags added to the host
object by other means are kept, and only their writable fields are sent
back; macros and tags created by Zabbix itself are left out, and tags
are compared by both name and value. Tags without a value get an empty
one, as stored by Zabbix. The agent interface uses the default IPv4
address of the host, or the default IPv6 address on a host without
IPv4. The encryption settings of the host object, including the
expected certificate subject and issuer, follow the TLS mode of the
agent. In check mode the role only makes the read-only API calls.

The API token has to be created in Zabbix and stored in the secret
directory on the Ansible Controller. The token authentication and the
API parameters used by the role require Zabbix 6.4 or newer.

Generated-By: LLM (Claude Code, Cursor)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Describe the TLS modes and the PKI hook, the requirements of the host
registration through the API and what it does not change in Zabbix, and
show how to define a custom UserParameter with the configuration
variables of the role. The format of the API lists, their states and
the order in which the inventory levels are combined are described with
an example.

Generated-By: LLM (Claude Code, Cursor)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add the zabbix_agent playbook to the CI pipeline manifest as an excluded
entry, because Ubuntu 24.04 used by the hosted runners does not provide
Zabbix packages. The entry can be enabled once the runners use a release
which includes them.

Generated-By: LLM (Claude Code, Cursor)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scibi
scibi force-pushed the feature/zabbix-agent-improvements branch from 421718f to 66c4942 Compare November 22, 2026 02:13

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant