SDK Python (pyvergeos)

Automatisez l’infrastructure VergeOS avec le SDK Python pyvergeos — cycle de vie des VM, réseau, multi-locataire, stockage et reprise après sinistre depuis des scripts Python.

Le pyvergeos Le SDK fournit une interface typée, de style Python, pour l’ensemble de l’API REST VergeOS. Plutôt que de créer des requêtes HTTP brutes, vous travaillez avec des gestionnaires de ressources — client.vms, client.networks, client.tenants — qui correspondent directement aux objets VergeOS. Le SDK gère l’authentification, la pagination, les nouvelles tentatives et le sondage des tâches asynchrones afin que vos scripts d’automatisation restent propres et centrés sur la logique métier.

Prérequis et installation

Prérequis :

• Python 3.9 ou version ultérieure
• VergeOS 26.0 ou version ultérieure
• Fonctionne sur Windows, macOS et Linux

Installer depuis PyPI (recommandé) :

pip install pyvergeos

Ou avec uv (alternative plus rapide) :

uv add pyvergeos

Depuis les sources (développement) :

git clone https://github.com/verge-io/pyvergeos.git
cd pyvergeos
pip install .

Authentification

Le SDK prend en charge trois méthodes d’authentification, chacune adaptée à des environnements différents.

Nom d’utilisateur et mot de passe

L’approche la plus simple pour les scripts interactifs et le développement :

from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # Uniquement pour les certificats auto-signés
)

Jeton API

Pour l’automatisation en production, lorsque vous disposez d’une clé API pré-générée :

client = VergeClient(
    host="192.168.1.100",
    token="your-api-token"
)

Variables d’environnement

L’approche recommandée pour la production — elle garde les identifiants hors du code स्रोत :

export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret
export VERGE_VERIFY_SSL=false      # Facultatif
export VERGE_TIMEOUT=30            # Facultatif
export VERGE_RETRY_TOTAL=3         # Facultatif
export VERGE_RETRY_BACKOFF=1       # Facultatif

client = VergeClient.from_env()

Gestionnaire de contexte

Utilisez toujours le gestionnaire de contexte dans le code de production afin de garantir que les connexions sont correctement fermées, même lorsque des exceptions se produisent :

with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()
    for vm in vms:
        print(f"{vm.name}: {vm.ram}MB RAM")
# Connexion automatiquement fermée ici

Gestionnaires de ressources

Chaque type de ressource VergeOS est exposé via un gestionnaire de ressources sur l’objet client. Chaque gestionnaire fournit des méthodes cohérentes list(), get(), create(), et des méthodes d’action.

Machines virtuelles

client.vms — Crée, configure, contrôle l’alimentation, clone, prend des instantanés et gère les disques/cartes réseau des VM.

Réseaux

client.networks — Réseaux virtuels, règles de pare-feu, DHCP, DNS et gestion de l’alimentation du réseau.

Locataires

client.tenants — Provisioning multi-locataire, isolement des ressources, instantanés, blocs de stockage et blocs réseau.

NAS et stockage

client.nas — Services NAS, volumes, partages CIFS/NFS et synchronisation des volumes.

Récupération après sinistre

client.dr — Instantanés cloud, synchronisation des sites et workflows de récupération.

Utilisateurs et groupes

client.users — Comptes utilisateurs, groupes, permissions et gestion des clés API.

Tâches et supervision

client.tasks — Suivi asynchrone des tâches, attente, délais d’expiration. Aussi : alarmes et journaux.

Système et GPU

client.clusters, client.nodes, client.gpu — Informations sur les clusters/nœuds, niveaux de stockage, gestion des périphériques GPU.

Table complète des ressources

Catégorie	Ressources disponibles
Machines virtuelles	VM, disques, cartes réseau, instantanés
Réseau	Réseaux, règles de pare-feu, DNS, DHCP, alias, hôtes
VPN	Connexions IPSec, interfaces et pairs WireGuard
NAS/Stockage	Services NAS, volumes, partages CIFS/NFS, synchronisations de volumes
Locataires	Gestion des locataires, instantanés, blocs de stockage, blocs réseau
Utilisateurs et groupes	Utilisateurs, groupes, permissions, clés API
Système	Clusters, nœuds, niveaux de stockage, certificats
Surveillance	Alarmes, journaux, tâches
Sauvegarde et reprise après sinistre	Profils d’instantanés, instantanés cloud, sites, synchronisations de sites

Filtrage des ressources

Le SDK propose trois approches pour filtrer les ressources, des simples arguments de mot-clé à un constructeur de filtres OData complet.

Arguments de mots-clés

L’approche la plus simple pour les filtres de base — passez directement les noms de champs :

# Trouver toutes les VM Linux en cours d’exécution
vms = client.vms.list(status="running", os_family="linux")

# Correspondance avec jokers
vms = client.vms.list(name="prod-*")

Chaînes de filtre OData

Pour les requêtes complexes, passez des expressions de filtre OData brutes :

# Combiner des conditions avec des opérateurs
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")

Constructeur de filtres (API fluide)

Construisez des filtres par programme avec sécurité de type et auto-complétion :

from pyvergeos import Filter

# Enchaînement fluide avec des méthodes d’opérateur
f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))

Opérateurs de filtre disponibles :

Méthode	Opérateur OData	Exemple
.eq()	eq	Filter().eq("status", "running")
.ne()	ne	Filter().ne("os_family", "windows")
.gt()	gt	Filter().gt("ram", 4096)
.lt()	lt	Filter().lt("cpu_cores", 8)
.ge()	ge	Filter().ge("ram", 2048)
.le()	le	Filter().le("ram", 8192)
.and_()	et	Enchaîner plusieurs conditions
.or_()	ou	Combiner des conditions alternatives

Gestion des tâches asynchrones

De nombreuses opérations VergeOS — instantanés, clones, migrations — s’exécutent de manière asynchrone et renvoient immédiatement un ID de tâche. Le SDK fournit un gestionnaire de tâches pour interroger l’achèvement :

# L’instantané renvoie une référence de tâche
result = vm.snapshot(retention=86400, quiesce=True)

# Attendre la fin de l’instantané (bloque jusqu’à 300 secondes)
task = client.tasks.wait(result["task"], timeout=300)
print(f"Instantané terminé : {task}")

Si la tâche ne se termine pas avant l’expiration du délai, une TaskTimeoutError est levée avec la task_id propriété afin que vous puissiez vérifier l’état plus tard :

from pyvergeos import TaskTimeoutError

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"La tâche {e.task_id} est toujours en cours — revenez plus tard")

Gestion des erreurs

Le SDK fournit une hiérarchie structurée d’exceptions afin que vous puissiez intercepter des modes d’échec spécifiques :

Exception	Description
VergeError	Exception de base pour toutes les erreurs du SDK
AuthenticationError	Identifiants invalides ou jeton expiré
NotFoundError	La ressource demandée n’existe pas
ConflictError	Conflit d’état de la ressource (par ex., VM déjà en cours d’exécution)
ValidationError	Valeurs de paramètres invalides
TaskTimeoutError	La tâche ne s’est pas terminée avant l’expiration du délai
TaskError	La tâche a échoué pendant l’exécution

from pyvergeos import NotFoundError, AuthenticationError

try:
    vm = client.vms.get(name="nonexistent-vm")
except NotFoundError:
    print("VM introuvable — vérifiez le nom")
except AuthenticationError:
    print("Échec de l’authentification — vérifiez les identifiants")

Configuration des nouvelles tentatives

Le SDK réessaie automatiquement les erreurs transitoires (HTTP 429, 500, 502, 503, 504) avec une temporisation exponentielle :

client = VergeClient(
    host="192.168.1.100",
    token="api-token",
    retry_total=5,            # Nombre maximal de tentatives (par défaut : 3)
    retry_backoff_factor=2,   # Multiplicateur de temporisation (par défaut : 1)
)

Définissez retry_total=0 pour désactiver complètement les nouvelles tentatives pour les opérations sensibles au temps.

Changement de contexte de locataire

pyvergeos peut se connecter dans des contextes de locataire depuis le système hôte, ce qui permet des scripts d’automatisation centralisés qui gèrent des ressources sur plusieurs locataires :

# Récupérer un locataire depuis le système hôte
tenant = client.tenants.get(name="customer-a")

# Se connecter dans le contexte du locataire
tenant_client = tenant.connect()

# Gérer maintenant des ressources À L’INTÉRIEUR du locataire
tenant_vms = tenant_client.vms.list()
for vm in tenant_vms:
    print(f"VM du locataire : {vm.name}")

# Créer un réseau à l’intérieur du locataire
tenant_client.networks.create(
    name="tenant-app-net",
    network_address="10.50.1.0/24",
    ip_address="10.50.1.1",
    dhcp_enabled=True
)

C’est particulièrement utile pour Les MSP et les fournisseurs de services qui doivent automatiser le provisioning sur des dizaines ou des centaines d’environnements locataires à partir d’un seul script.

Exemples pratiques

Gestion du cycle de vie des VM

with VergeClient.from_env() as client:
    # Créer une nouvelle VM
    vm = client.vms.create(
        name="web-server-01",
        ram=4096,
        cpu_cores=2,
        os_family="linux"
    )

    # Ajouter un disque de données de 50 Go
    vm.drives.add(name="data", size=50 * 1024 * 1024 * 1024)

    # Rattacher à un réseau
    network = client.networks.get(name="app-network")
    vm.nics.add(network=network.key)

    # Mise sous tension
    vm.power_on()
    print(f"La VM {vm.name} est en cours d’exécution")

Réseau avec règles de pare-feu

with VergeClient.from_env() as client:
    # Créer un réseau
    network = client.networks.create(
        name="web-tier",
        network_address="10.20.1.0/24",
        ip_address="10.20.1.1",
        dhcp_enabled=True
    )
    network.power_on()

    # Ajouter des règles de pare-feu
    network.rules.create(
        name="Autoriser HTTPS",
        action="accept",
        protocol="tcp",
        dest_port=443
    )
    network.rules.create(
        name="Autoriser SSH",
        action="accept",
        protocol="tcp",
        dest_port=22
    )
    network.apply_rules()

Opérations en masse avec filtrage

with VergeClient.from_env() as client:
    # Créer un instantané de toutes les VM de production en cours d’exécution
    prod_vms = client.vms.list(name="prod-*", status="running")

    for vm in prod_vms:
        result = vm.snapshot(retention=86400, quiesce=True)
        task = client.tasks.wait(result["task"], timeout=300)
        print(f"Instantané créé pour {vm.name}")

Rapport d’inventaire multi-locataire

with VergeClient.from_env() as client:
    for tenant in client.tenants.list():
        tenant_client = tenant.connect()
        vms = tenant_client.vms.list()
        print(f"\n--- {tenant.name} ---")
        for vm in vms:
            print(f"  {vm.name}: {vm.ram}MB RAM, {vm.cpu_cores} cœurs")

Remarques importantes

Sécurité des threads

Le client pyvergeos n’est pas sûr pour les threads. Si vous avez besoin d’opérations concurrentes, créez des VergeClient instances séparées pour chaque thread. Pour de véritables charges de travail parallèles, envisagez le SDK Go govergeos qui est conçu pour une utilisation concurrente avec des goroutines.

Vous venez de VMware ou de Nutanix ?

pyvergeos expose trois modèles qu’il vaut la peine de connaître dès le départ :

• Filtrage — un Filter() constructeur fluide produit des expressions de style OData (.eq(), .gt(), .and_(), .or_()), ou vous pouvez transmettre une chaîne OData brute à list(filter=...).
• Interrogation des tâches — les opérations asynchrones renvoient une référence de tâche ; client.tasks.wait(task_id, timeout=...) bloque jusqu’à l’achèvement et lève TaskTimeoutError en cas d’expiration du délai.
• Contexte du locataire — tenant.connect() renvoie un client limité au locataire, de sorte que le même script peut piloter le système hôte et n’importe quel locataire enfant sans se reconnecter à un autre point de terminaison.

Ressources supplémentaires

• Dépôt GitHub — code source, problèmes et contributions
• Paquet PyPI — dernière version publiée et historique des versions
• Documentation de l’API VergeOS