Gérer Proxmox avec les modules Ansible

La collection community.proxmox fournit des modules Ansible qui pilotent Proxmox VE par son API : d'un côté les modules *_info, en lecture seule, qui interrogent l'état du cluster, de l'autre les modules d'action qui créent, démarrent, arrêtent ou sauvegardent les instances. Ce guide configure l'authentification par token chiffrée avec Ansible Vault, installe proxmoxer sur le bon hôte, puis montre l'inventaire, le cycle de vie et les snapshots. Le provisionnement initial reste confié à Terraform.

Ce n'est plus community.general, et les anciens noms sont en sursis

Les modules Proxmox ont quitté community.general pour leur propre collection, community.proxmox. Relevé le 21 septembre 2026 dans le meta/runtime.yml de community.general : 18 modules proxmox* y sont désormais de simples redirections, toutes marquées dépréciées avec le message « The proxmox content has been moved to community.proxmox » et une removal_version: 15.0.0.

Ces redirections fonctionnent encore, mais la version courante de community.general est la 13.4.0 : il ne reste que deux versions majeures avant la suppression. Un playbook qui écrit encore community.general.proxmox_kvm fonctionne aujourd'hui et cessera de fonctionner sans prévenir.

Le repérage se fait en une commande sur vos playbooks :

grep -rn "community\.general\.proxmox" .

Ce que vous allez apprendre

• Installer la collection community.proxmox avec un requirements.yml épinglé.
• Authentifier Ansible auprès de Proxmox par token, chiffré avec Vault.
• Comprendre où installer proxmoxer, et pourquoi ce n'est pas sur le nœud Proxmox.
• Récupérer des informations avec les modules *_info.
• Gérer les instances et les snapshots.

Configurer l'authentification

Tous les modules partagent les mêmes paramètres de connexion. Pour ne pas exposer le secret, on les place dans un fichier chiffré avec Ansible Vault.

1. Créez le token côté Proxmox, sur le nœud, avec pveum :

   pveum user add ansible@pve
   pveum user add-token ansible@pve automation

   Le secret ne s'affiche qu'une fois. La documentation Proxmox est explicite : il « is only displayed/returned once when the token is generated. It cannot be retrieved again over the API at a later time ». Copiez-le immédiatement, sinon il faut regénérer le token.

2. Donnez-lui un rôle, sinon il ne peut rien faire.

   pveum acl modify / -token 'ansible@pve!automation' -role PVEAuditor

   C'est l'étape que tout le monde saute, et elle explique la quasi-totalité des 403 au premier playbook. Par défaut, un token Proxmox est créé avec la séparation de privilèges active : il ne reçoit rien de son utilisateur, et ses permissions effectives sont l'intersection de celles de l'utilisateur et des siennes propres. Un token sans ACL a donc beau appartenir à un compte administrateur, il ne peut rien lire.

3. Créez proxmox_auth.yml avec les valeurs obtenues :

   proxmox_api_host: proxmox.exemple.lan
   proxmox_api_node: proxmox
   proxmox_api_user: ansible@pve
   proxmox_api_token_id: automation
   proxmox_api_token_secret: "le-secret-affiche-une-seule-fois"

4. Chiffrez le fichier (et l'inventaire si besoin) :

   ansible-vault encrypt proxmox_auth.yml

Dans chaque playbook, les modules réutilisent ces variables. Le bloc d'authentification commun est donc toujours le même :

api_host: "{{ proxmox_api_host }}"
api_user: "{{ proxmox_api_user }}"
api_token_id: "{{ proxmox_api_token_id }}"
api_token_secret: "{{ proxmox_api_token_secret }}"

Le rôle minimal dépend de ce que le playbook fait

Un token API est révocable et à périmètre limité, ce qui le rend préférable à un mot de passe. Encore faut-il lui donner le rôle le plus étroit qui couvre l'opération, et pas Administrator par facilité :

Ce que fait le playbook	Privilège requis	Rôle prédéfini suffisant
Lire l'inventaire, les stockages, les tâches	VM.Audit	PVEAuditor, lecture seule
Démarrer, arrêter, redémarrer une instance	VM.PowerMgmt	PVEVMUser
Créer et supprimer des snapshots	VM.Snapshot	PVEVMAdmin
Créer ou détruire une instance	VM.Allocate et Datastore.AllocateSpace	PVEVMAdmin plus PVEDatastoreUser

Glissez pour voir

La deuxième ligne est celle qu'on rate le plus souvent : arrêter une instance ne demande pas PVEVMAdmin. PVEVMUser porte VM.PowerMgmt sans donner ni VM.Allocate ni VM.Snapshot, donc sans permettre de détruire quoi que ce soit. Pour la même raison, un playbook qui ne fait que des snapshots n'a aucune raison de recevoir le droit de créer des instances.

Donnez enfin le rôle sur le chemin le plus étroit possible plutôt que sur / :

pveum acl modify /vms/101 -token 'ansible@pve!automation' -role PVEVMUser

limite le token à une seule instance.

Le piège du certificat auto-signé

Les modules valident le certificat TLS par défaut. Le paramètre validate_certs de la collection vaut true, ce qui est le bon défaut mais surprend sur un Proxmox de laboratoire, dont le certificat est auto-signé : le premier playbook échoue alors sur une erreur TLS, pas sur une erreur d'authentification.

Deux issues, et une seule est recommandable. La bonne consiste à installer un certificat reconnu sur le nœud, par exemple via Let's Encrypt, ce que Proxmox sait faire nativement. La seconde, réservée à un lab jetable, désactive la vérification :

validate_certs: false   # ❌ laboratoire uniquement, jamais en production

La collection lit aussi la variable d'environnement PROXMOX_VALIDATE_CERTS, ce qui évite de disséminer ce réglage dans chaque tâche.

Installer la collection et ses prérequis

Ces modules parlent à l'API Proxmox, ils ne s'exécutent pas sur l'hyperviseur. C'est la confusion la plus coûteuse du sujet, et elle change tout : où installer proxmoxer, et quel hosts: écrire dans vos playbooks.

Épingler la collection dans un requirements.yml

La collection ne fait pas partie d'ansible-core : elle s'installe, et elle s'épingle, comme n'importe quelle dépendance.

requirements.yml

collections:
  - name: community.proxmox
    version: "2.0.0"

ansible-galaxy collection install -r requirements.yml

La 2.0.0, publiée le 21 mai 2026, déclare dans son meta/runtime.yml un prérequis qu'il vaut mieux connaître avant de découvrir l'erreur :

requires_ansible: ">=2.17.0"

Vérifiez donc votre ansible-core avant d'installer :

ansible --version | head -1

Où installer proxmoxer, et pourquoi pas sur Proxmox

Les modules déclarent leurs dépendances dans un fragment de documentation commun à toute la collection :

requirements: ["proxmoxer >= 2.3", "requests"]

Ces bibliothèques sont nécessaires sur la machine qui exécute le module. Comme ces modules ne font qu'appeler une API HTTP, cette machine est votre contrôleur Ansible, pas le nœud Proxmox.

pip install "proxmoxer>=2.3" requests

N'installez pas de dépendances Python sur votre hyperviseur

Faire tourner ces playbooks avec hosts: proxmox fonctionne, mais impose d'installer proxmoxer, requests et pip sur l'hyperviseur lui-même. Vous ajoutez des paquets Python sur la machine qui porte toutes vos VM, pour un module qui n'a besoin que d'un accès réseau à son API.

Écrivez plutôt vos plays sur le contrôleur, avec hosts: localhost, ou gardez votre inventaire et ajoutez delegate_to: localhost sur les tâches concernées. Le nœud Proxmox n'a alors rien à installer.

On lance ensuite les playbooks en fournissant les variables chiffrées et le mot de passe Vault :

ansible-playbook inventaire.yml -e @proxmox_auth.yml --vault-password-file=~/.vault_pass

Récupérer des informations

Les modules *_info sont en lecture seule (changed: false) : ils interrogent l'API et renvoient un dictionnaire exploitable avec register puis debug. Tous prennent le même bloc d'authentification.

Module	Ce qu'il retourne
proxmox_domain_info	les royaumes d'authentification (pam, pve...)
proxmox_user_info	les utilisateurs et leurs tokens
proxmox_group_info	les groupes d'utilisateurs
proxmox_storage_info	les stockages (type, contenu, chemin)
proxmox_tasks_info	l'historique des tâches d'un nœud
proxmox_vm_info	les VMs et conteneurs (filtrables par type ou name)

Glissez pour voir

Exemple type avec proxmox_vm_info filtré sur les conteneurs LXC :

---
- name: Inventaire des conteneurs
  hosts: localhost
  connection: local
  gather_facts: false
  tasks:
    - name: Récupérer les LXC
      community.proxmox.proxmox_vm_info:
        api_host: "{{ proxmox_api_host }}"
        node: "{{ proxmox_api_node }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        type: lxc
      register: infos

    - name: Afficher le résultat
      ansible.builtin.debug:
        var: infos

Le module renvoie la clé proxmox_vms, une liste de dictionnaires. Chaque entrée porte l'identité de l'instance et ses compteurs de consommation, ce que la documentation du module illustre ainsi :

"proxmox_vms": [
    {
        "cpu": 0.258944410905281,
        "cpus": 1,
        "disk": 0,
        "diskread": 0,
        "diskwrite": 0,
        "id": "qemu/100",
        "name": "test1",
        "node": "proxmox",
        "status": "running",
        "type": "qemu",
        "vmid": 100
    }
]

Deux champs méritent attention. id préfixe le type (qemu/100, lxc/101), alors que vmid ne porte que le nombre : c'est vmid qu'attendent les autres modules. Et status est la valeur à tester pour n'agir que sur ce qui tourne :

- name: Arrêter uniquement les conteneurs LXC en marche
  community.proxmox.proxmox:
    # bloc d'authentification commun, omis ici pour la lisibilité
    hostname: "{{ item.name }}"
    state: stopped
  loop: >-
    {{ infos.proxmox_vms
       | selectattr('type', 'equalto', 'lxc')
       | selectattr('status', 'equalto', 'running')
       | list }}

Le filtre sur type n'est pas décoratif. proxmox_vms mélange les VM QEMU et les conteneurs LXC, alors que le module proxmox ne gère que les seconds : sans ce premier selectattr, la boucle tente d'arrêter une VM avec le mauvais module. Pour les VM, c'est proxmox_kvm qui prend le relais.

Gérer les instances

Au-delà de la lecture, le module community.proxmox.proxmox gère le cycle de vie des conteneurs LXC : création, démarrage, arrêt, suppression via le paramètre state.

---
- name: Arrêter un conteneur
  hosts: localhost
  connection: local
  gather_facts: false
  tasks:
    - name: Stopper l'instance test2
      community.proxmox.proxmox:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        node: "{{ proxmox_api_node }}"
        hostname: test2
        state: stopped

Pour les machines virtuelles (QEMU), le module dédié est proxmox_kvm, avec la même logique de state (started, stopped, restarted, absent).

Gérer les snapshots

Le module proxmox_snap crée et supprime des snapshots d'instances. Le paramètre retention purge les plus anciens, mais il porte deux subtilités que la documentation du module énonce et qu'il vaut mieux connaître avant de compter dessus.

retention: 0 ne supprime rien, il garde tout. Ce n'est pas la valeur « aucune rétention » qu'on suppose spontanément. Et la purge n'a lieu que si un snapshot est réellement créé : sur une exécution où le snapshot existe déjà, rien n'est supprimé, et une tâche planifiée qui échoue à créer laisse donc l'historique grossir en silence.

---
- name: Snapshot d'une instance
  hosts: localhost
  connection: local
  gather_facts: false
  tasks:
    - name: Créer un snapshot avec rétention
      community.proxmox.proxmox_snap:
        api_host: "{{ proxmox_api_host }}"
        api_user: "{{ proxmox_api_user }}"
        api_token_id: "{{ proxmox_api_token_id }}"
        api_token_secret: "{{ proxmox_api_token_secret }}"
        vmid: 101
        state: present
        snapname: avant-maj
        retention: 2

Pour des sauvegardes complètes plutôt que des snapshots, orientez-vous vers Proxmox Backup Server.

À retenir

• Les modules Proxmox vivent dans community.proxmox, plus dans community.general, dont les redirections disparaissent en 15.0.0.
• L'authentification par token se chiffre avec Ansible Vault ; le bloc de connexion est commun à tous les modules.
• proxmoxer >= 2.3 et requests s'installent sur le contrôleur Ansible, pas sur l'hyperviseur : ces modules appellent une API.
• proxmox_vm_info liste VMs et conteneurs (filtrables) ; proxmox et proxmox_kvm gèrent leur cycle de vie.
• proxmox_snap gère les snapshots avec une rétention automatique.

FAQ : questions fréquentes sur les modules Ansible Proxmox

Quels modules Ansible permettent de gérer Proxmox ?

Les modules Proxmox vivent désormais dans la collection community.proxmox, plus dans community.general, où ils ne sont que des redirections dépréciées supprimées en 15.0.0. On y trouve les modules *_info en lecture seule et les modules d'action comme proxmox, proxmox_kvm et proxmox_snap.

Comment authentifier Ansible auprès de Proxmox de façon sécurisée ?

Avec un token API créé par pveum user add-token, chiffré dans un fichier Ansible Vault. Le point critique est la séparation de privilèges, active par défaut : un token sans ACL explicite n'a aucun droit, même si son utilisateur est administrateur.

Quelle bibliothèque Python faut-il pour les modules Proxmox d'Ansible ?

proxmoxer en version 2.3 minimum, plus requests. Elles s'installent sur le contrôleur Ansible et non sur le nœud Proxmox, car ces modules appellent l'API par le réseau et ne s'exécutent pas sur l'hyperviseur.

Comment créer un snapshot Proxmox avec Ansible ?

Avec community.proxmox.proxmox_snap, en state present et un snapname. Le paramètre retention purge les plus anciens, mais retention à 0 conserve tout, et la purge n'a lieu que si un snapshot est réellement créé.

Pour aller plus loin

• Les collections Ansible : Épingler community.proxmox dans un requirements.yml pour figer la version des modules Proxmox.
• Ansible Vault : Chiffrer le token API Proxmox au lieu de le laisser en clair dans un playbook.
• Formation Ansible : Le parcours complet, des premiers playbooks aux rôles et aux collections.

×

📖 Voir la documentation →