Collection Ansible

Automatisez l’infrastructure VergeOS avec la collection Ansible vergeio.vergeos — modules pour les instantanés de VM, le tagging et les imports, plus un plugin d’inventaire dynamique pour les environnements multi-sites.

Ansible apporte une automatisation sans agent et à base de push pour la gestion de l’infrastructure. Le vergeio.vergeos La collection Ansible étend Ansible avec des modules conçus à cet effet et un plugin d’inventaire pour VergeOS, vous permettant de gérer les instantanés de VM, d’organiser les ressources avec des balises, d’importer des images de VM et de découvrir dynamiquement l’infrastructure sur plusieurs sites — le tout via des playbooks YAML familiers.

Présentation de la collection

La collection Ansible VergeOS est publiée sur Ansible Galaxy et s’intègre directement à l’API REST de VergeOS via pyvergeos le SDK Python.

Détail	Valeur
Espace de noms	vergeio
Collection	vergeos
Référence complète	vergeio.vergeos
Python	>= 3.9
Ansible	>= 2.14.0
Dépendance du SDK	pyvergeos >= 1.0.1
Source	GitHub

Installation

Installez la collection depuis Ansible Galaxy :

# Installer depuis Galaxy (recommandé)
ansible-galaxy collection install vergeio.vergeos

# Installer le SDK Python requis
pip install pyvergeos

Pour les environnements de développement ou hors ligne, construisez et installez depuis les sources :

git clone https://github.com/verge-io/ansible-collection-vergeos.git
cd ansible-collection-vergeos
ansible-galaxy collection build
ansible-galaxy collection install vergeio-vergeos-*.tar.gz --force

Authentification

La collection utilise des variables d’environnement pour l’authentification à l’API, ce qui permet de garder les identifiants hors de vos playbooks et fichiers d’inventaire :

export VERGEOS_HOST="https://vergeos.example.com"
export VERGEOS_USERNAME="admin"
export VERGEOS_PASSWORD="your-password"
export VERGEOS_INSECURE="true"   # Définir à true pour les certificats SSL auto-signés

Vous pouvez également utiliser l’authentification par clé API pour les scénarios non interactifs comme les pipelines CI/CD. Les clés API sont créées dans Système > Utilisateurs > [sélectionner l’utilisateur] > Clés API dans l’interface VergeOS et fournissent une authentification par jeton Bearer sans nécessiter d’identifiants nom d’utilisateur/mot de passe.

Modules

La collection fournit des modules pour les opérations du cycle de vie des VM, la gestion des balises et la gestion des images. Chaque module communique avec l’API VergeOS via le SDK pyvergeos.

Module d’instantané de VM

Le vergeio.vergeos.vm_snapshot le module crée et gère des instantanés de VM par programmation — utile pour l’automatisation des sauvegardes, les points de contrôle avant changement et les workflows de reprise après sinistre.

- name: Créer un instantané du serveur de base de données
  vergeio.vergeos.vm_snapshot:
    vm_name: "db-server-01"
    description: "Instantané avant mise à niveau"
    retention: 86400 # Conserver pendant 24 heures (secondes)
    quiesce: true # Quiescer le système de fichiers invité

Modules de gestion des balises

Les balises fournissent un système de classification flexible pour organiser les ressources VergeOS. La collection inclut deux modules pour la gestion des balises :

Module	Rôle
vergeio.vergeos.tag_category	Créer et gérer des catégories de balises (par exemple, "Environnement", "Département")
vergeio.vergeos.tag	Appliquer et gérer des balises individuelles au sein des catégories

- name: Créer une catégorie de balises d’environnement
  vergeio.vergeos.tag_category:
    name: "Environment"
    description: "Classification de l’environnement de déploiement"

- name: Marquer la VM comme production
  vergeio.vergeos.tag:
    category: "Environment"
    name: "Production"
    resource_type: "vm"
    resource_name: "web-server-01"

Capacités d’importation de VM

La collection déploie des VM à partir de modèles OVA déjà téléversés dans VergeOS — le vm_import le module référence un OVA existant par nom ou ID, et le CPU ainsi que la RAM sont repris depuis l’OVA lui-même. Téléversez d’abord l’OVA (interface ou API), puis exécutez le playbook pour créer la VM.

Plugin d’inventaire dynamique

Le vergeos_vms le plugin d’inventaire interroge l’API VergeOS pour découvrir dynamiquement les VM et construire l’inventaire Ansible — supprimant ainsi le besoin de maintenir des fichiers d’hôtes statiques.

Inventaire API uniquement

Le plugin d’inventaire récupère les métadonnées des VM depuis l’API VergeOS. Il ne pas définit ansible_host et ne prend pas en charge les connexions SSH directes nativement. Vous devez configurer ansible_host via les variables d’hôte, les règles de composition ou une stratégie de connexion distincte pour l’exécution des playbooks basée sur SSH.

Configuration de l’inventaire

Créez un fichier d’inventaire (par exemple, vergeos_inventory.yml):

plugin: vergeio.vergeos.vergeos_vms
sites:
  - name: "datacenter-east"
    host: "https://east.vergeos.example.com"
    username: "ansible-svc"
    password: "{{ lookup('env', 'VERGEOS_PASSWORD') }}"
    verify_ssl: false

  - name: "datacenter-west"
    host: "https://west.vergeos.example.com"
    username: "ansible-svc"
    password: "{{ lookup('env', 'VERGEOS_PASSWORD') }}"
    verify_ssl: false

# Filtres facultatifs
filters:
  status: "running"
  name_pattern: "prod-*"

# Activer la mise en cache pour les grands environnements
cache: true
cache_plugin: jsonfile
cache_connection: /tmp/vergeos_inventory_cache
cache_timeout: 300

Regroupement automatique

Le plugin organise automatiquement les VM découvertes en groupes selon plusieurs dimensions :

Dimension du groupe	Exemples de groupes	Cas d’utilisation
Site	datacenter_east, datacenter_west	Cibler les playbooks vers des emplacements spécifiques
Statut	status_running, status_stopped	Exécuter les tâches uniquement sur les VM actives
Balises	tag_Production, tag_Development	Configuration spécifique à l’environnement
Tenant	tenant_acme, tenant_globex	Automatisation multi-locataire
Famille d’OS	os_linux, os_windows	Playbooks spécifiques au système d’exploitation
Cluster	cluster_compute01, cluster_compute02	Maintenance consciente du cluster
Nœud	node_node1, node_node2	Opérations au niveau du nœud

Variables d’hôte

Chaque VM découverte expose plus de 20 variables d’hôte, notamment l’ID de la VM, son nom, ses cœurs CPU, sa RAM, sa famille d’OS, son état d’alimentation, son affectation au cluster, son emplacement sur le nœud, sa configuration réseau, ses balises et l’ensemble du dictionnaire de données de la VM pour les cas d’usage avancés.

Modèles de playbooks

Orchestration d’instantanés multi-sites

Utilisez le filtrage par balises avec l’inventaire dynamique pour orchestrer des instantanés sur plusieurs sites :

---
- name: Prendre un instantané de toutes les bases de données de production sur les sites
  hosts: tag_Production:&os_linux
  gather_facts: false

  tasks:
    - name: Créer un instantané avant maintenance
      vergeio.vergeos.vm_snapshot:
        vm_name: "{{ inventory_hostname }}"
        description: "Instantané de maintenance planifiée - {{ ansible_date_time.date }}"
        retention: 172800 # Rétention de 48 heures
        quiesce: true
      delegate_to: localhost

Mise en place du marquage des infrastructures

Établissez une taxonomie de balises cohérente dans votre environnement VergeOS :

---
- name: Configurer l’infrastructure de balisage
  hosts: localhost
  connection: local

  tasks:
    - name: Créer des catégories de balises
      vergeio.vergeos.tag_category:
        name: "{{ item.name }}"
        description: "{{ item.description }}"
      loop:
        - { name: "Environment", description: "Environnement de déploiement" }
        - { name: "Department", description: "Responsable de l’unité commerciale" }
        - { name: "Compliance", description: "Cadre réglementaire" }
        - { name: "Backup", description: "Niveau de politique de sauvegarde" }

    - name: Appliquer des balises d’environnement aux VM
      vergeio.vergeos.tag:
        category: "Environment"
        name: "Production"
        resource_type: "vm"
        resource_name: "{{ item }}"
      loop:
        - "db-server-01"
        - "web-server-01"
        - "app-server-01"

Flux d’importation de VM Windows

Automatisez l’importation de modèles de VM Windows à partir de fichiers OVA :

---
- name: Importer un modèle Windows Server
  hosts: localhost
  connection: local

  tasks:
    # Téléversez d’abord win2022-standard.ova vers VergeOS (interface ou API) ;
    # vm_import référence l’OVA existant par nom de fichier ou ID.
    - name: Importer Windows Server 2022 depuis OVA
      vergeio.vergeos.vm_import:
        name: "win2022-template"
        ova_file_name: "win2022-standard.ova"
        preferred_tier: "4"
        override_drive_interface: virtio
        override_nic_interface: virtio

    - name: Marquer le modèle importé
      vergeio.vergeos.tag:
        category: "Environment"
        name: "Template"
        resource_type: "vm"
        resource_name: "win2022-template"

Modèles d’intégration

Pipeline Terraform + Ansible

Un schéma courant combine Terraform pour le provisionnement et Ansible pour la configuration : Terraform déclare l’infrastructure, Ansible configure ce qui s’y exécute.

Phase	Outil	Responsabilité
Provisionnement	Terraform	Créer des VM, réseaux, utilisateurs, disques
Découverte	Inventaire	Interroger l’API VergeOS pour les nouvelles VM créées
Configuration	Ansible	Installer les paquets, configurer les services, appliquer les bases de sécurité
Validation	Ansible	Exécuter des tests de fumée, vérifier la connectivité, contrôler la conformité

SDK Python + Ansible

Pour les workflows complexes qui nécessitent une logique programmatique au-delà de ce que proposent les playbooks YAML, combinez le pyvergeos SDK Python avec Ansible :

- name: Automatisation VergeOS personnalisée avec Python
  hosts: localhost
  tasks:
    - name: Exécuter des opérations avancées sur les VM via pyvergeos
      ansible.builtin.script:
        cmd: scripts/bulk_snapshot.py
      environment:
        VERGEOS_HOST: "{{ vergeos_host }}"
        VERGEOS_USERNAME: "{{ vergeos_user }}"
        VERGEOS_PASSWORD: "{{ vergeos_password }}"

Intégration CI/CD

Les playbooks Ansible s’intègrent naturellement dans les pipelines CI/CD pour l’automatisation de l’infrastructure :

GitLab CI

Déclencher des playbooks Ansible depuis .gitlab-ci.yml des étapes pour le provisionnement et la configuration automatisés des VM lors d’une fusion vers main.

Jenkins

Utilisez le plugin Ansible pour Jenkins afin d’exécuter des playbooks comme étapes de build, avec des identifiants gérés via le Jenkins Credential Store.

GitHub Actions

Exécutez des playbooks Ansible dans les workflows GitHub Actions à l’aide de ansible-playbook pour les changements d’infrastructure déclenchés par les pull requests.

AWX / Tower

Déployez Ansible AWX pour une interface web, le RBAC et l’exécution planifiée des playbooks sur les environnements VergeOS.

Bonnes pratiques

Gestion des identifiants

• Ne codez jamais en dur les identifiants dans les playbooks ou les fichiers d’inventaire — utilisez des variables d’environnement ou Ansible Vault
• Utilisez des clés API pour les comptes de service en production — elles prennent en charge les listes d’IP autorisées et les dates d’expiration
• Faites tourner les identifiants régulièrement et auditez l’utilisation des clés API via l’interface VergeOS

Stratégie d’inventaire

• Activez la mise en cache pour les grands environnements afin de réduire les appels API et d’accélérer les exécutions de playbooks
• Utilisez des filtres pour limiter l’inventaire aux VM pertinentes — évitez de récupérer l’ensemble de l’environnement
• Inventaires séparés par environnement (dev, staging, production) pour plus de sécurité

Conception des playbooks

• Utilisez delegate_to: localhost pour les appels à l’API VergeOS — les modules communiquent avec l’API, pas avec les VM invitées via SSH
• Tirez parti des balises pour le ciblage — elles offrent un système de regroupement flexible et multidimensionnel
• Implémentez l’idempotence — concevez des playbooks pouvant être relancés sans danger et sans effets de bord

Vous venez de VMware ?

Le vergeio.vergeos la collection suit le modèle Ansible standard que vous connaissez déjà : des modules pilotés par l’API pour les opérations sur les ressources, plus un plugin d’inventaire dynamique pour la découverte des hôtes. Une seule configuration d’inventaire peut interroger plusieurs sites VergeOS à la fois — sans jonglage de connexions par site.

Vous venez de Nutanix ?

Le vergeio.vergeos la collection suit le modèle Ansible standard : des modules pilotés par l’API plus un plugin d’inventaire dynamique. Une configuration d’inventaire peut cibler plusieurs sites VergeOS simultanément, sans plane de gestion central requis.

Lectures complémentaires

• Collection Ansible — GitHub
• Ansible Galaxy — vergeio.vergeos
• SDK Python pyvergeos — PyPI
• Documentation VergeOS — SDK Python
• Documentation Ansible