129 lines
5.2 KiB
Markdown
129 lines
5.2 KiB
Markdown
# 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
|
|
|
|
1. Jenkins triggers the pipeline with a Proxmox tag as a parameter (default: `zabbix`).
|
|
2. The Proxmox dynamic inventory plugin queries the Proxmox API and discovers all VMs/LXCs with that tag.
|
|
3. 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:
|
|
```bash
|
|
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](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](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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
```
|