first commit
This commit is contained in:
128
README.md
Normal file
128
README.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user