# 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
```