SDK Python VergeOS (pyvergeos)

pyvergeos est un SDK Python pour gérer VergeOS via l’API REST, offrant une interface typée, de style Python, pour automatiser les VM, le réseau, le stockage, les locataires et la reprise après sinistre.

Vue d'ensemble

pyvergeos est un SDK Python pour gérer l'infrastructure VergeOS via l'API REST. Il fournit une interface Pythonique, annotée avec des types, pour automatiser le cycle de vie des VM, le réseau, le stockage, les opérations multi-locataires et les flux de reprise après sinistre, ce qui le rend idéal pour les scripts d'automatisation, le développement d'outils et les intégrations.

Fonctionnalités clés

• Gestion des VM: Création, configuration, contrôle d'alimentation, clonage et instantanés
• Réseautage avancé: Réseaux virtuels, règles de pare-feu, DHCP, DNS, VPN IPSec et WireGuard
• NAS et stockage: Gestion des volumes, partages CIFS/NFS et synchronisation
• Multi-location: Provisionnement des locataires avec isolation des ressources
• Reprise après sinistre: Instantanés cloud, synchronisation des sites et flux de récupération
• Filtrage: Prise en charge du filtrage OData avec une API de génération de filtres fluide
• Annotations de type: Indications de type complètes pour l'autocomplétion de l'IDE et l'analyse statique
• Multiplateforme: Prise en charge de Windows, macOS et Linux

Prérequis

• Python 3.9 ou version ultérieure
• VergeOS 26.0 ou version ultérieure

Installation

Depuis PyPI (recommandé)

pip install pyvergeos

Avec uv

uv add pyvergeos

Depuis les sources

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

Authentification

Le SDK prend en charge plusieurs méthodes d'authentification :

Nom d'utilisateur/mot de passe

from pyvergeos import VergeClient

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

Vérification du certificat SSL

Définissez verify_ssl=False uniquement pour les environnements avec des certificats auto-signés. Pour les environnements de production avec des certificats valides, omettez ce paramètre ou définissez-le sur True.

Jeton d'API

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

Variables d'environnement

export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret

client = VergeClient.from_env()

Recommandé pour la production

L'utilisation de variables d'environnement permet de garder les identifiants hors de votre code source et facilite l'utilisation d'identifiants différents selon les environnements.

Gestionnaire de contexte

with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()

Nettoyage automatique

L'utilisation du gestionnaire de contexte (with instruction) garantit que la connexion est correctement fermée, même si une exception se produit.

Ressources disponibles

Le SDK donne accès aux ressources VergeOS suivantes :

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

Exemples d'utilisation

Gestion des machines virtuelles

from pyvergeos import VergeClient

client = VergeClient(host="192.168.1.100", username="admin", password="secret")

# Lister toutes les VM
for vm in client.vms.list():
    print(f"{vm.name}: {vm.ram} Mo de RAM, {vm.cpu_cores} cœurs")

# Obtenir une VM spécifique
vm = client.vms.get(name="web-server")

# Créer une VM
new_vm = client.vms.create(
    name="test-vm",
    ram=2048,
    cpu_cores=2,
    os_family="linux"
)

# Opérations d'alimentation
vm.power_on()
vm.power_off()
vm.reset()

# Instantanés
vm.snapshot(retention=86400, quiesce=True)

# Cloner une VM
clone = vm.clone(name="test-clone")

# Ajouter des disques et des NIC
vm.drives.add(name="data", size=50*1024*1024*1024)
vm.nics.add(network=network.key)

client.disconnect()

Création et gestion des réseaux

# Créer un réseau virtuel
network = client.networks.create(
    name="app-network",
    network_address="10.10.1.0/24",
    ip_address="10.10.1.1",
    dhcp_enabled=True
)

network.power_on()
network.apply_rules()

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

Filtrage des ressources

Le SDK prend en charge plusieurs approches de filtrage :

Arguments nommés

# Simple et lisible pour les filtres de base
vms = client.vms.list(status="running", name="prod-*")

Chaîne de filtre OData

# Syntaxe complète de filtre OData pour les requêtes complexes
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")

Générateur de filtres

# API fluide pour construire des filtres par programmation
from pyvergeos import Filter

f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))

Attente des tâches

De nombreuses opérations dans VergeOS s'exécutent de manière asynchrone. Utilisez le gestionnaire de tâches pour attendre la fin :

result = vm.snapshot()
task = client.tasks.wait(result["task"], timeout=300)

Opérations asynchrones

Les opérations comme les instantanés, les clones et les migrations renvoient immédiatement un identifiant de tâche. Utilisez client.tasks.wait() pour bloquer jusqu'à ce que l'opération soit terminée.

Gestion des erreurs

Le SDK fournit des types d'exceptions spécifiques pour différents cas d'erreur :

from pyvergeos import NotFoundError, AuthenticationError, TaskTimeoutError

try:
    vm = client.vms.get(name="nonexistent")
except NotFoundError:
    print("VM introuvable")

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"La tâche {e.task_id} a expiré")

Types d'exceptions disponibles

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ètre invalides
TaskTimeoutError	La tâche n'a pas été terminée dans le délai imparti
TaskError	La tâche a échoué pendant l'exécution

Cas d'utilisation courants

• Automatisation de l'infrastructure: Provisionner des VM, des réseaux et du stockage par programmation
• Intégration CI/CD: Créer et détruire des environnements de test dans les pipelines
• Surveillance et reporting: Interroger l'état des ressources et générer des rapports d'inventaire
• Automatisation des sauvegardes: Planifier et gérer les instantanés et les sauvegardes cloud
• Provisionnement multi-locataire: Automatiser la création des locataires et l'allocation des ressources

Documentation et ressources

Pour une documentation complète, y compris toutes les méthodes disponibles et des exemples d'utilisation détaillés, visitez le dépôt officiel :

• Dépôt GitHub
• Package PyPI

Support

Si vous rencontrez des problèmes ou avez des demandes de fonctionnalités, veuillez ouvrir un ticket sur le dépôt GitHub :

https://github.com/verge-io/pyvergeos/issues

Ressources supplémentaires

• Documentation Python
• Documentation de l'API VergeOS
• Module PowerShell PSVergeOS - alternative PowerShell
• Fournisseur Terraform - Infrastructure as code