Gérer Proxmox avec les modules Ansible

La collection community.general fournit des modules Ansible pour piloter Proxmox VE via son API : d'un côté les modules *_info qui interrogent l'état du cluster (utilisateurs, stockage, tâches, VMs), de l'autre les modules d'action qui démarrent, arrêtent ou sauvegardent les instances. Ce guide configure l'authentification par token (chiffrée avec Ansible Vault), installe le prérequis proxmoxer, puis montre comment récupérer des informations et gérer les instances et snapshots. Le provisionnement initial reste confié à Terraform.

Ce que vous allez apprendre

• Authentifier Ansible auprès de Proxmox par token, chiffré avec Vault.
• Installer le prérequis proxmoxer.
• Récupérer des informations avec les modules *_info.
• Gérer les instances (démarrer, arrêter) 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 proxmox_auth.yml avec un token API (créé côté Proxmox via pveum) :

   proxmox_api_host: proxmox.exemple.lan
   proxmox_api_node: proxmox
   proxmox_api_user: ansible@pve
   proxmox_api_token_id: automation
   proxmox_api_token_secret: "votre-secret-de-token"

2. 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 }}"

Token plutôt que mot de passe

Un token API (révocable, à périmètre limité) est préférable à un mot de passe. Pour la simple lecture d'informations, un token avec le rôle PVEAuditor suffit.

Installer le prérequis proxmoxer

Les modules s'appuient sur la bibliothèque Python proxmoxer. Installez-la sur la machine cible avec un premier playbook :

---
- name: Préparer le nœud Proxmox
  hosts: proxmox
  become: true
  tasks:
    - name: Installer proxmoxer et pip
      ansible.builtin.package:
        name:
          - python3-pip
          - python3-proxmoxer
        state: present

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

ansible-playbook install.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: proxmox
  tasks:
    - name: Récupérer les LXC
      community.general.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

La sortie liste chaque instance avec ses métriques (extrait) :

"proxmox_vms": [
    {
        "id": "lxc/101",
        "name": "test2",
        "node": "proxmox",
        "status": "running",
        "type": "lxc",
        "vmid": 101
    }
]

Ces données alimentent ensuite des conditions ou des boucles dans vos playbooks (par exemple agir uniquement sur les instances running).

Gérer les instances

Au-delà de la lecture, le module community.general.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: proxmox
  tasks:
    - name: Stopper l'instance test2
      community.general.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 automatiquement les plus anciens.

---
- name: Snapshot d'une instance
  hosts: proxmox
  tasks:
    - name: Créer un snapshot avec rétention
      community.general.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

• La collection community.general fournit des modules *_info (lecture) et d'action pour Proxmox.
• L'authentification par token se chiffre avec Ansible Vault ; le bloc de connexion est commun à tous les modules.
• Le prérequis proxmoxer doit être installé sur la machine cible.
• 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 ?

La collection community.general fournit des modules d'information en lecture seule (proxmox_user_info, proxmox_storage_info, proxmox_vm_info, proxmox_tasks_info) et des modules d'action : proxmox pour le cycle de vie des conteneurs LXC, proxmox_kvm pour les VMs, et proxmox_snap pour les snapshots.

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

On crée un token API côté Proxmox, puis on place api_host, api_user, api_token_id et api_token_secret dans un fichier chiffré avec Ansible Vault. Les playbooks réutilisent ces variables. Un token est révocable et limité ; pour la lecture seule, le rôle PVEAuditor suffit.

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

Les modules Proxmox de community.general s'appuient sur la bibliothèque Python proxmoxer. Il faut l'installer sur la machine qui exécute les appels API (python3-proxmoxer et python3-pip), sinon les tâches échouent avec une erreur de module Python manquant.

Comment créer un snapshot Proxmox avec Ansible ?

Avec le module community.general.proxmox_snap : on précise le vmid, state present et un snapname. Le paramètre retention purge automatiquement les snapshots les plus anciens au-delà du nombre indiqué. Pour des sauvegardes complètes, on utilise plutôt Proxmox Backup Server.

Prochaines étapes

Inventaire dynamique Ansible Lister automatiquement les VMs avant de les piloter.

Provisionner avec Terraform Créer les ressources Proxmox en amont d'Ansible.

Proxmox Backup Server Sauvegarder ses VMs au-delà des snapshots.

Ansible Vault Chiffrer les secrets de vos playbooks.

×

📖 Voir la documentation →