first commit

README.md

@@ -0,0 +1,96 @@
+# 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 |