zabbix-agent-install

Ansible playbook and Jenkins pipeline for installing Zabbix Agent2 on Proxmox-hosted VMs and LXC containers. Hosts are discovered automatically via the Proxmox dynamic inventory plugin based on Proxmox tags — no manual inventory management required.

How it works

Jenkins triggers the pipeline with a Proxmox tag as a parameter (default: zabbix).
The Proxmox dynamic inventory plugin queries the Proxmox API and discovers all VMs/LXCs with that tag.
Ansible connects to those hosts via SSH and runs the zabbix_agent role to install and configure Zabbix Agent2.

Prerequisites

On Proxmox hosts (target VMs/LXCs)

Ubuntu 24.04 (the role installs the ubuntu24.04 release package by default)
QEMU guest agent installed and running — required for automatic IP address discovery
SSH accessible by the Ansible user
Tagged in Proxmox with the tag used to filter (e.g. zabbix)

On the Ansible control node / Jenkins agent

Ansible >= 2.14
Python 3
community.general collection >= 8.0.0 — install once on the agent:
```
ansible-galaxy collection install -r requirements.yml
```

Jenkins setup

Credentials

Credential ID	Type	Description
`proxmox-api-token`	Secret text	Proxmox API token in the format `user@realm!tokenid=secret`
`ansible-ssh-key`	SSH username with key	SSH key used by Ansible to connect to target hosts

The Proxmox API token needs at minimum VM.Audit and VM.Config.Network permissions to read VM data from the API.

Pipeline parameters

Parameter	Default	Description
`PROXMOX_TAG`	`zabbix`	Proxmox tag used to select target hosts
`ZABBIX_SERVER`	`zabbix.lan`	Hostname or IP of the Zabbix server
`ZABBIX_VERSION`	`7.0`	Zabbix agent2 version to install
`DRY_RUN`	`false`	Run in `--check --diff` mode without making changes

Project structure

zabbix-agent-install/
├── Jenkinsfile                        # CI/CD pipeline definition
├── ansible.cfg                        # Ansible configuration
├── requirements.yml                   # Ansible Galaxy collection dependencies
├── inventory/
│   ├── proxmox.yml                    # Proxmox dynamic inventory plugin config
│   └── hosts.yml                      # (legacy static inventory, not used by pipeline)
├── playbooks/
│   └── install_zabbix.yml             # Main playbook — targets tagged hosts
└── roles/
    └── zabbix_agent/
        ├── defaults/
        │   └── main.yml               # Default role variables
        └── tasks/
            └── main.yml               # Installation and configuration tasks

Role variables

Defined in roles/zabbix_agent/defaults/main.yml:

Variable	Default	Description
`zabbix_server`	`zabbix.lan`	Zabbix server address (passive and active checks)
`zabbix_version`	`7.0`	Zabbix repository version
`zabbix_release`	`7.0-2`	Exact release package version (update if changing major version)
`zabbix_ubuntu_version`	`24.04`	Ubuntu version for the release package URL

Dynamic inventory

The inventory/proxmox.yml file configures the community.general.proxmox inventory plugin. It reads credentials from environment variables set by the Jenkins pipeline:

Variable	Description
`PROXMOX_URL`	Proxmox API URL (default: `https://proxmox.lan:8006`)
`PROXMOX_USER`	API user (e.g. `ansible@pam`)
`PROXMOX_TOKEN_ID`	API token ID
`PROXMOX_TOKEN_SECRET`	API token secret

Proxmox tags are automatically mapped to Ansible groups with the prefix proxmox_tag_. A VM tagged zabbix will appear in the group proxmox_tag_zabbix, which is the group targeted by the playbook.

Running the inventory manually

export PROXMOX_USER="ansible@pam"
export PROXMOX_TOKEN_ID="mytoken"
export PROXMOX_TOKEN_SECRET="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# List all discovered hosts
ansible-inventory -i inventory/proxmox.yml --list

# Show hosts in the zabbix tag group
ansible-inventory -i inventory/proxmox.yml --graph proxmox_tag_zabbix

Running the playbook manually

export PROXMOX_USER="ansible@pam"
export PROXMOX_TOKEN_ID="mytoken"
export PROXMOX_TOKEN_SECRET="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Install Zabbix agent on all hosts tagged "zabbix"
ansible-playbook playbooks/install_zabbix.yml \
    -i inventory/proxmox.yml \
    -u ansible \
    --private-key ~/.ssh/id_ed25519 \
    -e "proxmox_filter_tag=zabbix" \
    -e "zabbix_server=zabbix.lan" \
    -e "zabbix_version=7.0"

# Dry run (no changes applied)
ansible-playbook playbooks/install_zabbix.yml \
    -i inventory/proxmox.yml \
    -u ansible \
    --private-key ~/.ssh/id_ed25519 \
    -e "proxmox_filter_tag=zabbix" \
    --check --diff

5.2 KiB Raw Permalink Blame History