API REST et outils CLI

Maîtrisez l’API REST VergeOS, le script d’assistance yb-api et l’outil vrg CLI pour la gestion programmatique de l’infrastructure et l’automatisation.

Chaque opération que vous effectuez dans l’interface VergeOS correspond directement à un appel à l’API REST. Cette Conception axée sur l’API signifie que tout ce sur quoi vous pouvez cliquer dans le tableau de bord — créer des VM, configurer des réseaux, gérer des locataires — peut être automatisé via des points de terminaison HTTP. Cette section couvre les trois interfaces principales pour l’accès programmatique : la API REST elle-même, le script utilitaire yb-api pour l’automatisation sur la machine, et le CLI vrg pour la gestion à distance.

Vue d’ensemble de l’API REST

L’API VergeOS suit les conventions REST standard avec des charges utiles JSON, prenant en charge l’intégralité du cycle de vie de chaque ressource de la plateforme.

Méthodes HTTP

Méthode

Rôle

Exemple

GET

Récupérer des ressources

GET /api/v4/vms?fields=most

POST

Créer des ressources ou déclencher des actions

POST /api/v4/vms

PUT

Mettre à jour des ressources existantes

PUT /api/v4/vms/36

DELETE

Supprimer des ressources

DELETE /api/v4/vms/36

Paramètres de requête

Chaque requête GET prend en charge le filtrage de style OData et la sélection de champs :

champs — Spécifiez les champs à renvoyer (par ex., fields=name,$key,ram ou fields=most pour tous les champs courants)
filter — Expressions de filtre de style OData (par ex., filter=is_snapshot eq false)
sort — Triez les résultats par champ (par ex., sort=name)
limit / offset — Contrôles de pagination pour les ensembles de résultats volumineux

Formats de données

Toutes les réponses de l’API sont renvoyées au format JSON. Les corps des requêtes pour les opérations POST et PUT doivent également être en JSON avec l’ en-tête Content-Type: application/json .

Limites de débit

L’API prend en charge un maximum de 1 000 requêtes par heure par clé API. Pour les automatisations à fort volume, regroupez les opérations lorsque c’est possible et implémentez une logique de réessai avec backoff exponentiel.

Authentification

VergeOS prend en charge deux méthodes d’authentification — l’authentification HTTP Basic et l’authentification par jeton — chacune adaptée à différents cas d’utilisation. Les clés API à longue durée de vie sont une variante de la méthode par jeton, présentées comme un jeton Bearer plutôt que comme un jeton de session :

1. Authentification HTTP Basic

La méthode la plus simple — transmettez les identifiants directement avec chaque requête. Tout le trafic API nécessite HTTPS.

curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \\
  --basic --user "admin:password" \\
  -H "Accept: application/json"

2. Authentification par jeton (jetons de session)

Demandez un jeton de session en envoyant par POST les identifiants à /sys/tokens. Utilisez le jeton renvoyé dans les requêtes suivantes via l’ x-yottabyte-token en-tête :

# Étape 1 : Obtenir un jeton
curl --basic \\
  --data-ascii '{"login": "admin", "password": "secret"}' \\
  --request "POST" \\
  --header "Content-Type: application/json" \\
  "https://vergeos.example.com/api/sys/tokens"

# La réponse inclut la clé du jeton :
# {"location":"/sys/tokens/3a334...","$key":"3a334..."}

# Étape 2 : Utiliser le jeton dans les requêtes suivantes
curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \\
  -H "x-yottabyte-token: 3a334..." \\
  -H "Accept: application/json"

# Étape 3 : Se déconnecter une fois terminé
curl -X DELETE "https://vergeos.example.com/api/sys/tokens/3a334..."

Variante du jeton Bearer : clés API à longue durée de vie

Pour l’automatisation en production, créez des clés API persistantes via Système → Utilisateurs → [Utilisateur] → Clés API. Ces clés sont une variante Bearer de l’authentification par jeton — elles fonctionnent comme des jetons Bearer et restent valides jusqu’à expiration ou suppression :

curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \\
  -H "Authorization: Bearer your-api-key-string" \\
  -H "Content-Type: application/json"

Les clés API prennent en charge des listes d’autorisation/interdiction d’IP pour la sécurité et des dates d’expiration. Stockez-les dans des variables d’environnement plutôt que de les coder en dur :

export VERGEOS_API_KEY="your-api-key-string"
curl -X GET "https://vergeos.example.com/api/v4/system" \\
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"

Les clés API ne sont affichées qu’une seule fois lors de la création. Si vous les perdez, vous devez supprimer la clé et en créer une nouvelle.

Explorateur d’API (Swagger)

VergeOS inclut une page de documentation Swagger intégrée, générée dynamiquement à partir du système en cours d’exécution, affichant chaque table et opération disponible.

Pour y accéder :

Connectez-vous à l’interface VergeOS
Accédez à Système → Documentation de l’API
Parcourez les points de terminaison disponibles, consultez les schémas et testez directement les appels API

L’interface Swagger vous permet d’exécuter des appels API dans le navigateur et de voir la curl commande générée, le corps de la réponse et les en-têtes — ce qui en fait un excellent outil pour prototyper des scripts d’automatisation.

Principaux points de terminaison de l’API

L’API organise les ressources en tables. Voici les points de terminaison les plus utilisés :

Point de terminaison

Rôle

/api/v4/vms

Opérations CRUD des machines virtuelles

/api/v4/vm_actions

Opérations d’alimentation de la VM, clonage, instantané

/api/v4/machine_drives

Attacher/gérer les disques de stockage de la VM

/api/v4/machine_nics

Configurer les interfaces réseau de la VM

/api/v4/machine_devices

Passage de périphériques GPU/PCI

/api/v4/machine_status/{id}

État d’alimentation et statut à l’exécution

/api/v4/vnets

Gestion du réseau virtuel

/api/v4/vnet_rules

Règles de pare-feu et de NAT

/api/v4/tenants

Gestion des locataires (VDC)

/api/v4/nodes

Informations sur les nœuds physiques

/api/v4/clusters

Configuration du cluster

/api/sys/tokens

Gestion des jetons de session

Introspection du schéma

Ajoutez /$table à n’importe quel point de terminaison pour récupérer son schéma complet de base de données, y compris tous les champs et types disponibles :

# Obtenir le schéma de la table des VM
curl -X GET "https://vergeos.example.com/api/v4/vms/\$table" \\
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"

Guide pas à pas de l’API du cycle de vie des VM

Le flux d’automatisation le plus courant consiste à provisionner une VM complète via l’API. Ce processus en quatre étapes reproduit ce que fait l’interface utilisateur en coulisses :

Étape 1 : Créer la VM

curl -X POST "https://vergeos.example.com/api/v4/vms" \\
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "web-server-01",
    "description": "Serveur web de production",
    "machine_type": "pc-q35-9.0",
    "cpu_cores": 4,
    "cpu_type": "Cascadelake-Server",
    "ram": 8192,
    "os_family": "linux",
    "boot_order": "cd",
    "uefi": true,
    "allow_hotplug": true
  }'

# Réponse : {"location":"/v4/vms/42","$key":"42"}

Étape 2 : Ajouter un disque de stockage

curl -X POST "https://vergeos.example.com/api/v4/machine_drives" \\
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": 42,
    "name": "boot-disk",
    "media": "disk",
    "interface": "virtio-scsi",
    "disksize": 107374182400,
    "preferred_tier": "1"
  }'

Étape 3 : Ajouter une interface réseau

curl -X POST "https://vergeos.example.com/api/v4/machine_nics" \\
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": 42,
    "vnet": 6,
    "interface": "virtio"
  }'

Étape 4 : Mettre sous tension

curl -X POST "https://vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "vm": 42,
    "action": "poweron"
  }'

Actions supplémentaires

Une fois la VM créée, vous pouvez déclencher des opérations avancées via le même vm_actions point de terminaison :

# Cloner une VM
curl -X POST ".../api/v4/vm_actions" \\
  -d '{"vm": 42, "action": "clone", "params": {"name": "web-server-clone", "quiesce": "true"}}'

# Prendre un instantané
curl -X POST ".../api/v4/vm_actions" \\
  -d '{"vm": 42, "action": "snapshot", "params": {"name": "pre-upgrade"}}'

# Arrêter proprement
curl -X POST ".../api/v4/vm_actions" \\
  -d '{"vm": 42, "action": "poweroff"}'

Script utilitaire yb-api

Le yb-api script est un wrapper en ligne de commande intégré disponible sur chaque nœud VergeOS via SSH. Il simplifie les appels API en gérant l’authentification, les en-têtes, la construction des URL, l’encodage des requêtes et le traitement des envois pour vous.

Syntaxe de base

yb-api --get|--post|--put|--delete [options] /v4/<endpoint>

Options courantes

Option

Rôle

--get

Récupérer des ressources

--post='JSON'

Créer une ressource avec une charge utile JSON

--put='JSON'

Mettre à jour une ressource avec une charge utile JSON

--delete

Supprimer une ressource

--server=IP

Cibler un système VergeOS spécifique

--user=NAME

S’authentifier en tant qu’utilisateur spécifique

--fields='...'

Sélectionner les champs à renvoyer

--filter='...'

Expression de filtre OData

Exemples d’utilisation

# Lister toutes les VM (à l’exception des instantanés) avec leur statut
yb-api --get --user=admin --server=10.0.0.100 \\
  --fields='name,$key,ram,machine#status#status as machine_status' \\
  --filter='is_snapshot eq false' /v4/vms

# Obtenir des informations détaillées sur la VM, y compris les disques et les NIC
yb-api --get --fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1

# Créer une nouvelle VM
yb-api --post='{"name":"api-vm","enabled":true,"os_family":"linux",
  "cpu_cores":4,"ram":"8192"}' --user=admin --server=10.0.0.100 /v4/vms

# Renommer une VM
yb-api --put='{"name":"new-name"}' --user=admin --server=10.0.0.100 /v4/vms/1

# Mettre une VM sous tension
yb-api --post='{"vm":1, "action": "poweron"}' /v4/vm_actions

# Obtenir le schéma de table des VM
yb-api --get '/v4/vms/$table'

Le yb-api script est idéal pour des requêtes ponctuelles rapides et du scripting directement sur les nœuds VergeOS. Pour l’automatisation à distance depuis des postes de travail, utilisez le CLI vrg ou les SDK Python/PowerShell.

CLI vrg

Le vrg outil en ligne de commande fournit une interface de gestion à distance complète pour VergeOS, développée en Python avec plus de 200 commandes couvrant les VM, les réseaux, le stockage, les locataires et l’administration système.

Installation

Le CLI vrg est distribué via plusieurs canaux — choisissez celui qui convient à votre environnement. Aucun n’est limité par le système d’exploitation ; pipx est la voie recommandée sur tous les OS pris en charge.

# pipx (recommandé — environnement Python isolé, tous les OS)
pipx install vrg

# pip (tous les OS)
pip install vrg

# uv (tous les OS)
uv tool install vrg

# Homebrew (tous les OS qui exécutent Homebrew)
brew install verge-io/tap/vrg

Un binaire autonome (sans Python requis) est également publié pour Linux x86_64, macOS ARM64, et Windows x86_64 — utile pour les hôtes Windows sans chaîne d’outils Python.

Principales fonctionnalités

Gestion des VM

Créez, listez, démarrez, arrêtez, prenez des instantanés, clonez et supprimez des machines virtuelles avec des commandes simples.

Opérations réseau

Gérez les réseaux virtuels, les règles de pare-feu, les paramètres DHCP et les configurations VPN.

Contrôle du stockage

Administrez les volumes NAS, les partages CIFS/NFS et surveillez les niveaux vSAN.

Gestion des locataires

Provisionnez des locataires, allouez des ressources et gérez des environnements multi-locataires.

Le CLI vrg encapsule la même API REST documentée ci-dessus, offrant l’autocomplétion, une sortie formatée et une interface plus ergonomique pour les opérations quotidiennes depuis votre poste de travail.

Gestion des erreurs de l’API

Lorsque les appels API échouent, VergeOS renvoie des codes d’état HTTP standard avec des corps d’erreur JSON descriptifs :

Code d’état

Signification

Cause fréquente

401

Non autorisé

Identifiants invalides ou jeton expiré

403

Interdit

Permissions insuffisantes pour l’opération

404

Introuvable

La ressource n’existe pas ou le point de terminaison est invalide

409

Conflit

Conflit d’état de la ressource (par ex., VM déjà en cours d’exécution)

422

Erreur de validation

Paramètres invalides ou champs requis manquants

429

Limitation de débit

Limite de 1 000 requêtes/heure dépassée

500

Erreur du serveur

Erreur interne — consultez les journaux système

Vous venez de VMware ou de Nutanix ?

VergeOS expose une unique /api/v4/ surface versionnée pour chaque opération — l’interface utilisateur elle-même n’est qu’un client de cette API. L’explorateur Swagger intégré est généré dynamiquement à partir du schéma en direct du système en cours d’exécution, de sorte que la documentation correspond toujours à ce que l’API accepte actuellement.

Bonnes pratiques pour l’automatisation via l’API

Utilisez des clés API pour l’automatisation en production au lieu des jetons de session — ils n’expirent pas en cas d’inactivité
Appliquez des restrictions IP sur les clés API pour limiter où elles peuvent être utilisées
Sélectionnez des champs spécifiques (fields=name,$key,ram) plutôt que fields=most pour réduire la taille de la charge utile
Mettez en place la pagination avec limit et offset pour les ensembles de résultats volumineux
Gérez les opérations asynchrones — des actions comme le clonage et l’instantané renvoient immédiatement ; interrogez machine_status pour l’achèvement
Stockez les identifiants dans des variables d’environnement — n’intégrez jamais les jetons en dur dans les scripts
Utilisez l’introspection du schéma (/$table) pour découvrir les champs disponibles avant d’écrire l’automatisation

Et ensuite

Maintenant que vous comprenez l’API brute, les pages suivantes couvrent des outils de plus haut niveau qui encapsulent cette API dans des interfaces natives au langage :

SDK Python (pyvergeos) — wrapper Pythonique, avec annotations de type, gestionnaires de ressources et générateur de filtres OData
Module PowerShell (PSVergeOS) — plus de 200 cmdlets avec prise en charge du pipeline pour l’automatisation native sous Windows

PrécédentAperçu

SuivantLab : automatisation de l’infrastructure

Mis à jour il y a 3 mois

Ce contenu vous a-t-il été utile ?