Ansible for Proxmox VE

Hands-on workshop · 3.5 h · beginner level

Author

credativ GmbH

About this workshop

Three and a half hours of hands-on automation: starting with three unconfigured Proxmox VE nodes, forming a cluster with Ansible, and automating recurring operational tasks (repositories, storage, service accounts, API tokens, virtual machines, backups).

The workshop assumes no prior Ansible experience. If you have written playbooks before, module 01 is a quick recap and you can focus on the optional exercises.

Your lab

Your personal lab. Every participant has an identical, isolated set.
Machine Role Address (management) Access
desktop Linux desktop, your Ansible control node 192.168.0.254 the VDI session you are in
pve01 Proxmox VE node 1, later the cluster primary 192.168.0.1 SSH from desktop, GUI on :8006
pve02 Proxmox VE node 2 192.168.0.2 SSH from desktop, GUI on :8006
pve03 Proxmox VE node 3 192.168.0.3 SSH from desktop, GUI on :8006
  • Proxmox VE version: 9, based on Debian 13 “trixie”. Package sources are in the deb822 .sources format.
  • Lab network: 192.168.0.0/24. The desktop is also the gateway for it, so the nodes reach the internet through the machine you are working on.
  • Host names and addresses are the same for every participant, which is why the starter project ships a ready-made inventory.
  • Shared NFS library: nas01.training.credativ.de:/mnt/pool01/shared, holding ISOs, container templates and the cloud image. You attach it yourself in module 05.
  • Proxmox VE login: user root, password password123, identical on all three nodes. The same credentials work for SSH and for the web GUI (realm Proxmox VE authentication server). It is a throwaway password in a throwaway lab.
  • SSH: deploy.sh generates a key and installs it on all three nodes, so neither ssh nor Ansible prompts for anything. The password above is still the fallback, and exercise 01 uses it once on purpose.
  • Working directory on desktop: ~/ansible-proxmox, created by deploy.sh from the starter project. The virtualenv with ansible-core, community.proxmox and proxmoxer is in ~/ansible-venv/bin and already on your PATH.

The nodes are installed but not configured: no cluster, enterprise repository still active, no extra storage, no users. That is on purpose. You build all of it with Ansible.

Presenting

One deck for the whole workshop: slides.qmd. That is what you present from; the module decks below are the same content, split up for handing out single topics.

quarto preview courses/ansible-proxmox/slides.qmd   # fullscreen: f, speaker notes: s
./slides-pdf.sh trainer                             # PDF export of every deck

Modules

Every module is self-contained and renders its own slides, handout and exercise.
# Module Slides Handout Exercise
00 Welcome & the lab reveal.js — —
01 Ansible in 30 minutes reveal.js HTML · PDF Exercise
02 Preparing the nodes reveal.js HTML · PDF Exercise
03 Forming the cluster reveal.js HTML · PDF Exercise
04 From playbook to role reveal.js HTML · PDF Exercise
05 Operating the cluster reveal.js HTML · PDF Exercise
06 Dynamic inventory reveal.js HTML · PDF Exercise
07 Where to go next reveal.js — —

Plus one cheat sheet covering the whole workshop, and bonus exercises for participants who finish early.

Two Ansible projects ship with this workshop

starter/ is the skeleton participants start from; deploy.sh puts it in their home as ~/ansible-proxmox. Configuration and inventory are complete (all participants share the same addresses), every playbook is present with the right task names and structure, and each unfinished task is a debug carrying a TODO. It runs successfully from the first minute and changes nothing. This exists so that nobody spends the workshop debugging YAML indentation.

code/ is the finished project: the same files, filled in, plus the pve_node role and the verification suite in code/tests/. Use it to unblock someone, and hand it out afterwards as the take-home artefact.

Timing

Reference schedule.
Block Content Minutes
00 Welcome, goals, lab tour, first SSH login 15
01 Ansible in 30 minutes: inventory, ad-hoc, idempotency 25
02 Preparing the nodes: repositories, packages, name resolution, time 30
— Break 10
03 Forming the cluster with Ansible 40
04 From playbook to role: structure, variables, handlers 25
05 Operating the cluster: storage, NFS, users, cloud-init guest, backup 45
06 Dynamic inventory from Proxmox VE 15
07 Wrap-up, next steps, questions 5
Total 210