# Proxmox OS Update

Ansible-based automation for managing and updating virtual machines and LXC containers on a Proxmox hypervisor. Uses Jenkins as a CI/CD orchestrator to execute playbooks for various maintenance tasks.

## Features

- **Dynamic Inventory**: Automatically discovers running VMs and LXCs from the Proxmox API
- **Tag-Based Targeting**: Group machines by Proxmox tags (update, docker, k8s)
- **CI/CD Integration**: Jenkins pipeline for scheduled and on-demand execution
- **Dry-Run Mode**: Test changes before applying them
- **Flexible Targeting**: Update specific hosts, groups, or all running machines

## Project Structure

```
proxmox-os-update/
├── Jenkinsfile                      # CI/CD pipeline configuration
├── README.md
├── inventories/
│   └── inventory.proxmox.yml        # Dynamic Proxmox inventory
└── playbooks/
    └── update.yaml                  # System update playbook
```

## Prerequisites

- Ansible with `community.proxmox` collection
- Proxmox VE cluster with API token configured
- SSH access to target machines (as `jenkins` user)
- Jenkins server (for CI/CD execution)

## Configuration

### Proxmox API Token

Create an API token in Proxmox for the `dynamic-inventory@pve` user. The token credentials should be stored in Jenkins.

### Inventory Groups

The dynamic inventory automatically creates these groups:

| Group | Description |
|-------|-------------|
| `proxmox_all_running` | All running VMs and LXCs |
| `vms` | QEMU virtual machines |
| `lxcs` | LXC containers |
| `update_targets` | Machines tagged with 'update' |
| `docker_hosts` | Machines tagged with 'docker' |
| `kubernetes` | Machines tagged with 'k8s' |

## Usage

### Via Jenkins (Recommended)

Trigger the Jenkins pipeline and select:
- **Playbook**: Which playbook to run
- **Limit**: Target specific hosts or groups (optional)
- **Dry Run**: Test without applying changes

### Manual Execution

```bash
# Update all running machines
ansible-playbook -i inventories/inventory.proxmox.yml playbooks/update.yaml

# Target specific group
ansible-playbook -i inventories/inventory.proxmox.yml playbooks/update.yaml --limit docker_hosts

# Dry run
ansible-playbook -i inventories/inventory.proxmox.yml playbooks/update.yaml --check --diff
```

### Ad-hoc Commands

```bash
# Test connectivity to all VMs
ansible -i inventories/inventory.proxmox.yml vms -m ping

# Test connectivity to a specific host
ansible -i inventories/inventory.proxmox.yml hostname -m ping
```

## Available Playbooks

| Playbook | Description |
|----------|-------------|
| `update.yaml` | Updates apt cache and performs dist-upgrade |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `PROXMOX_URL` | Proxmox API endpoint |
| `PROXMOX_USER` | API username |
| `PROXMOX_TOKEN_ID` | API token ID |
| `PROXMOX_TOKEN_SECRET` | API token secret |