API zur VM-Erstellung

Vollständige Anleitung zum Erstellen virtueller Maschinen in VergeOS, einschließlich grundlegender Erstellung, rezeptbasierter Konfigurationen, Laufwerke, Geräte und Netzwerkschnittstellen

Wichtige Punkte

VMs mit wesentlichen Konfigurationsparametern über die REST-API erstellen
Unterstützung für rezeptbasierte VM-Erstellung mit komplexen Konfigurationen
Laufwerke, Geräte und Netzwerkschnittstellen nach der VM-Erstellung hinzufügen
Unterschiede zwischen VM-Schlüssel und Maschinen-Schlüssel für verschiedene Vorgänge verstehen

Dieser Leitfaden behandelt das Erstellen virtueller Maschinen in VergeOS, von der grundlegenden VM-Erstellung bis zum Hinzufügen von Laufwerken, Geräten und Netzwerkschnittstellen. Die VergeOS-API bietet umfassende Endpunkte für VM-Erstellung und Hardwarekonfiguration.

Stufe: VM-Erstellung (1 von 4) Eingabe: API-Zugangsdaten, Cluster-Infos, VM-Spezifikationen Ausgabe: VM-Schlüssel (42) + Maschinen-Schlüssel (54) Weiter: Verwenden Sie die Schlüssel für die Energieverwaltung Häufige nächste Schritte:

VM einschalten → VM-Energieverwaltung
Einstellungen konfigurieren → VM-Konfiguration
Erweiterte Vorgänge → Erweiterte VM-Vorgänge

Dieses Dokument hilft bei

"Wie man eine VM über die API erstellt"
"Laufwerke während der VM-Einrichtung hinzufügen"
"GPU-/PCI-Geräte an VMs anhängen"
"VM-Erstellung mit Cloud-Init"
"VM- und Maschinen-Schlüssel verstehen"
"Netzwerkschnittstellen für neue VMs einrichten"
"Rezeptbasierte VM-Bereitstellung"
"Automatisierung der massenhaften VM-Erstellung"
"VM-Bereitstellung als Code"

Kurzreferenz

Primäre Endpunkte

VM erstellen: POST /api/v4/vms
Laufwerk hinzufügen: POST /api/v4/machine_drives
Gerät hinzufügen: POST /api/v4/machine_devices
NIC hinzufügen: POST /api/v4/machine_nics

Wichtige Parameter

name: VM-Kennung (erforderlich)
cluster: Ziel-Cluster-ID
machine: Maschinen-ID aus der VM-Erstellung (für Hardware-Ergänzungen)
resource_group: UUID für Geräte-Passthrough

Authentifizierung

-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"

Nächste Schritte

Nach der VM-Erstellung → Energieverwaltung (VM-Energieverwaltung)

API-Kurzreferenz

Vorgang

Methode

Endpunkt

Schlüsseltyp

Zweck

VM erstellen

POST

/api/v4/vms

Gibt beide zurück

Erste Erstellung

Laufwerk hinzufügen

POST

/api/v4/machine_drives

Maschinen-Schlüssel

Hardware

Gerät hinzufügen

POST

/api/v4/machine_devices

Maschinen-Schlüssel

GPU-/PCI-Passthrough

NIC hinzufügen

POST

/api/v4/machine_nics

Maschinen-Schlüssel

Netzwerkschnittstelle

Einschalten

POST

/api/v4/vm_actions

VM-Schlüssel

Steuerung

Status prüfen

GET

/api/v4/machine_status/{id}

Maschinen-Schlüssel

Überwachen

Index zur Fehlerbehebung

409 Konflikt: VM-Name existiert, läuft bereits, Berechtigung verweigert
400 Ungültige Anfrage: Ungültige Parameter, fehlende Pflichtfelder, ungültiges JSON
507 Unzureichender Speicher: Tier voll, Größe reduzieren, anderen Tier wählen
403 Verboten: API-Schlüssel-Berechtigungen, Clusterzugriff verweigert
404 Nicht gefunden: Ungültige Cluster-ID, fehlende Medienquelle, ungültige Ressourcengruppe
422 Nicht verarbeitbare Entität: Ungültige Laufwerkschnittstelle, nicht unterstützter Medientyp

Voraussetzungen

Gültige VergeOS-API-Zugangsdaten mit Berechtigungen zur VM-Verwaltung
Verständnis der VergeOS-Konzepte: Cluster, Vnets, Medienquellen und Ressourcengruppen
Grundkenntnisse der REST-API-Prinzipien und JSON-Formatierung

Authentifizierung

Alle VM-Erstellungsvorgänge erfordern eine Authentifizierung entweder über:

API-Schlüssel: In den Authorization Header als Bearer YOUR_API_KEY
Basisauthentifizierung: Benutzername und Passwort für interaktive Sitzungen
Sitzungstoken: Für webbasierte Integrationen

# Verwendung des API-Schlüssels
curl -H "Authorization: Bearer YOUR_API_KEY" \\
     -H "Content-Type: application/json" \\
     https://your-vergeos.example.com/api/v4/vms

Grundlegende VM-Erstellung

POST /api/v4/vms

Beschreibung: Erstellt eine neue virtuelle Maschine mit der angegebenen Konfiguration.

Anfrageparameter:

Name

Typ

Erforderlich

Beschreibung

name

string

Eindeutiger VM-Name

description

string

Nein

VM-Beschreibung

cluster

string

Nein

Ziel-Cluster-ID (numerische Zeichenkette)

ram

ganze Zahl

Nein

RAM in MB (Standard: 1024)

cpu_cores

ganze Zahl

Nein

Anzahl der CPU-Kerne (Standard: 1)

guest_agent

string

Nein

Gast-Agent aktivieren ("true"/"false")

console_pass_hash

string

Nein

Konsolen-Passwort-Hash (leere Zeichenkette, falls nicht verwendet)

video

string

Nein

Videoadaptertyp (virtio, std, cirrus usw.)

rtc_base

string

Nein

RTC-Basiseinstellung (utc, localtime)

uefi

string

Nein

UEFI-Start aktivieren ("true"/"false")

Beispiel für den Anfragekörper:

{
  "name": "web-server-01",
  "description": "Produktions-Webserver",
  "cluster": "1",
  "ram": 8192,
  "cpu_cores": 4,
  "guest_agent": "true",
  "console_pass_hash": "",
  "video": "virtio",
  "rtc_base": "utc",
  "uefi": "true"
}

Beispiel für die Antwort:

{
  "location": "/v4/vms/42",
  "dbpath": "vms/42",
  "$row": 42,
  "$key": "42",
  "response": {
    "machine": "54"
  }
}

Antwortfelder:

Feld

Typ

Beschreibung

location

string

API-Endpunkt für die erstellte VM

dbpath

string

Datenbankpfad für den VM-Datensatz

$row

ganze Zahl

Datenbankzeilennummer

$key

string

VM-ID (für nachfolgende API-Aufrufe verwendet)

response.machine

string

Maschinen-ID (für Laufwerke, NICs, Geräte verwendet)

Fehlerantworten:

400 Ungültige Anfrage: Ungültige Konfigurationsparameter
409 Konflikt: VM-Name existiert bereits
403 Verboten: Unzureichende Berechtigungen

VM-Schlüssel vs. Maschinen-Schlüssel

VM-Schlüssel (z. B. "42"): Für VM-Einstellungen wie CPU, RAM, Konsole verwenden
Maschinen-Schlüssel (z. B. "54"): Für Hardware wie Laufwerke, NICs, Geräte verwenden
Sie erhalten beide Schlüssel in der Antwort zur VM-Erstellung

Rezeptbasierte VM-Erstellung

VergeOS unterstützt die komplexe VM-Erstellung mithilfe von Rezepten, die Laufwerke, Netzwerkschnittstellen und Geräte enthalten.

Vollständige VM mit Rezeptkonfiguration

{
  "name": "enterprise-vm",
  "description": "Enterprise-Anwendungsserver",
  "cluster": "1",
  "cpu_cores": 8,
  "ram": 16384,
  "guest_agent": "true",
  "video": "virtio",
  "rtc_base": "utc",
  "uefi": "true",
  "secure_boot": "true",
  "console_pass_hash": "",
  "cloudinit_datasource": "nocloud",
  "cloudinit_files": [
    {
      "name": "user-data",
      "contents": "#cloud-config\nusers:\n  - name: admin\n    sudo: ALL=(ALL) NOPASSWD:ALL\n    ssh_authorized_keys:\n      - ssh-rsa AAAAB3NzaC1yc2E..."
    },
    {
      "name": "meta-data",
      "contents": "instance-id: enterprise-vm-001\nlocal-hostname: enterprise-vm"
    }
  ]
}

Laufwerke hinzufügen

Laufwerke müssen nach der VM-Erstellung separat über den Endpunkt für Maschinenlaufwerke erstellt werden.

POST /api/v4/machine_drives

Anfrageparameter:

Name

Typ

Erforderlich

Beschreibung

machine

string

Maschinen-ID aus der VM-Erstellung

name

string

Nein

Laufwerksname

media

string

Nein

Medientyp (disk, cdrom, import, clone, efidisk)

interface

string

Nein

Laufwerkschnittstelle (virtio-scsi, ide, ahci usw.)

disksize

ganze Zahl

Nein

Datenträgergröße in Bytes (für neue Datenträger)

preferred_tier

string

Nein

Speicher-Tier (1–5)

media_source

string

Nein

Quellmedien-ID (für Import/Clone/CDROM)

show_pt

string

Nein

Bevorzugtes Tier überschreiben ("true"/"false") – überschreibt das Standard-Tier der Medienquelle

Ein Boot-Laufwerk erstellen

{
  "machine": "54",
  "name": "OS-Laufwerk",
  "media": "disk",
  "interface": "virtio-scsi",
  "disksize": 2199023255552,
  "preferred_tier": "1"
}

Beispiel für die Antwort:

{
  "location": "/v4/machine_drives/54",
  "dbpath": "machine_drives/54",
  "$row": 54,
  "$key": "54"
}

CDROM/ISO anhängen

{
  "machine": "54",
  "media": "cdrom",
  "interface": "ahci",
  "media_source": "7"
}

Beispiel für die Antwort:

{
  "location": "/v4/machine_drives/55",
  "dbpath": "machine_drives/55",
  "$row": 55,
  "$key": "55"
}

Importieren aus Medienquelle

{
  "machine": "54",
  "name": "Ubuntu Server",
  "description": "Ubuntu 22.04 LTS",
  "interface": "virtio-scsi",
  "media": "import",
  "media_source": 123,
  "preferred_tier": "3"
}

Geräte hinzufügen (GPU, PCI-Passthrough usw.)

POST /api/v4/machine_devices

Beschreibung: Bindet Hardwaregeräte wie GPUs, PCI-Geräte, USB-Geräte oder TPM an eine virtuelle Maschine an.

Anfrageparameter:

Name

Typ

Erforderlich

Beschreibung

machine

string

Maschinen-ID

resource_group

string

UUID der Ressourcengruppe für das Gerät

settings_args

Objekt

Nein

Gerätespezifische Einstellungen (leeres Objekt für grundlegenden Passthrough)

PCI-Passthrough-GPU

{
  "machine": "54",
  "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1",
  "settings_args": {}
}

Beispiel für die Antwort:

{
  "location": "/v4/machine_devices/2",
  "dbpath": "machine_devices/2",
  "$row": 2,
  "$key": "2",
  "response": {
    "uuid": "934e250b-a13c-bd8f-104d-a31995b06eba"
  }
}

Ressourcengruppen finden

Der resource_group Parameter identifiziert das spezifische Hardwaregerät, das angehängt werden soll. Verwenden Sie diese Endpunkte, um verfügbare UUIDs von Ressourcengruppen zu finden:

GET /api/v4/resource_groups - Allgemeine Hardwaregeräte (GPUs, PCI-Geräte, USB usw.)
GET /api/v4/node_nvidia_vgpu_devices - Spezifisch NVIDIA-vGPU-Geräte

Verfügbare Geräte finden

# Allgemeine Hardwaregeräte
curl "https://your-vergeos.example.com/api/v4/resource_groups" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# NVIDIA-vGPU-Geräte
curl "https://your-vergeos.example.com/api/v4/node_nvidia_vgpu_devices" \\
  -H "Authorization: Bearer YOUR_API_KEY"

Netzwerkschnittstellen hinzufügen

POST /api/v4/machine_nics

Anfrageparameter:

Name

Typ

Erforderlich

Beschreibung

machine

string

Maschinen-ID

vnet

string

Virtuelle Netzwerk-ID (Schlüssel des Zielnetzwerks)

name

string

Nein

NIC-Name

interface

string

Nein

NIC-Schnittstellentyp (virtio, e1000 usw.)

aktiviert

boolesch

Nein

Aktivierter Zustand der NIC

Beispiel:

{
  "machine": "54",
  "vnet": "3"
}

Beispiel für die Antwort:

{
  "location": "/v4/machine_nics/78",
  "dbpath": "machine_nics/78",
  "$row": 78,
  "$key": "78"
}

Schlüssel virtueller Netzwerke

Der vnet Der Parameter verwendet den Schlüssel/die ID des Netzwerks. Zum Beispiel könnte vnet "3" Ihr externes Netzwerk sein. Sie können Netzwerkschlüssel finden, indem Sie verfügbare Netzwerke über den Netzwerke-API-Endpunkt auflisten.

Vollständiges Beispiel für die VM-Erstellung

Hier ist ein vollständiger Ablauf zum Erstellen einer VM mit Laufwerken, Geräten und Netzwerkschnittstellen:

# Schritt 1: Die VM erstellen
curl -X POST "https://your-vergeos.example.com/api/v4/vms" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "production-server",
    "description": "Produktionsanwendungsserver",
    "cluster": "1",
    "ram": 16384,
    "cpu_cores": 8,
    "guest_agent": "true",
    "video": "virtio",
    "uefi": "true"
  }'

# Antwort: VM-Schlüssel = 42, Maschinen-Schlüssel = 54

# Schritt 2: Boot-Laufwerk hinzufügen
curl -X POST "https://your-vergeos.example.com/api/v4/machine_drives" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "name": "Boot-Laufwerk",
    "media": "disk",
    "interface": "virtio-scsi",
    "disksize": 107374182400,
    "preferred_tier": "1"
  }'

# Schritt 3: Netzwerkschnittstelle hinzufügen
curl -X POST "https://your-vergeos.example.com/api/v4/machine_nics" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "vnet": "3"
  }'

# Schritt 4: GPU hinzufügen (optional)
curl -X POST "https://your-vergeos.example.com/api/v4/machine_devices" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1",
    "settings_args": {}
  }'

Verwandte Vorgänge

Energieverwaltung: Siehe VM-Energieverwaltung zum Starten/Stoppen von VMs
Konfiguration: Siehe VM-Konfiguration für CPU-/RAM-Änderungen
Erweiterte Vorgänge: Siehe Erweiterte VM-Vorgänge für Klonen und Snapshots

Brauchen Sie Hilfe?

Für zusätzliche Unterstützung bei der VM-Erstellung:

Prüfen Sie das VergeOS-Dokumentationsportal
Wenden Sie sich mit konkreten Fehlermeldungen an den VergeOS-Support
Prüfen Sie die Systemprotokolle auf detaillierte Fehlerinformationen
Konsultieren Sie die VergeOS-Community-Foren

VorherigeAPI für VM-Konfiguration

NächsteÜberblick über die API für VM-Lifecycle-Management

Zuletzt aktualisiert vor 3 Monaten

War das hilfreich?