Repository navigation
Conversation
scibi
force-pushed
the
feature/zabbix-agent-improvements
branch
from
August 28, 2026 14:54
a03afd0 to
6c95350
Compare
scibi
force-pushed
the
feature/zabbix-agent-improvements
branch
from
September 16, 2026 12:44
6c95350 to
6a160ed
Compare
scibi
force-pushed
the
feature/zabbix-agent-improvements
branch
3 times, most recently
from
September 29, 2026 23:07
fc84b81 to
42e8d60
Compare
scibi
force-pushed
the
feature/zabbix-agent-improvements
branch
from
October 6, 2026 15:24
42e8d60 to
b07bf5b
Compare
scibi
force-pushed
the
feature/zabbix-agent-improvements
branch
from
October 23, 2026 23:58
b07bf5b to
08bd58c
Compare
scibi
force-pushed
the
feature/zabbix-agent-improvements
branch
from
November 16, 2026 18:26
08bd58c to
30d88b3
Compare
scibi
force-pushed
the
feature/zabbix-agent-improvements
branch
from
November 16, 2026 20:02
30d88b3 to
421718f
Compare
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
force-pushed
the
feature/zabbix-agent-improvements
branch
from
November 22, 2026 02:13
421718f to
66c4942
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds two features to the
debops.zabbix_agentrole. The newzabbix_agent__tls_modevariable selects how the agent encrypts itsconnections: a pre-shared key is still the default, the
certmode uses thehost certificate and CA from a PKI realm managed by the
debops.pkirole,and the
unencryptedmode disables TLS. In thecertmode the role addsthe 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
pskmode.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 aremerged by name and macros by the macro name, so an entry in the
absentstate 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
absentstate is removed from the host. A hostwithout 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
certmode with theAPI registration on a Debian 13 host with Zabbix Agent 2 and Zabbix 7.0;
the
pskandunencryptedmodes were tested by rendering theconfiguration, 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.