API für VM-Konfiguration

Vollständige Anleitung zum Ändern von VM-Konfigurationen in VergeOS, einschließlich CPU-/RAM-Updates, Notizen, Laufwerksverwaltung und Verwaltung von Netzwerkschnittstellen

Wichtige Punkte

• VM-Einstellungen wie CPU, RAM, Konsole und Video über die REST-API ändern

• Laufwerke mit Größenänderung, Hinzufügen und Entfernen verwalten

• Netzwerkschnittstellen und ihre Konfigurationen aktualisieren

• Dokumentationshinweise zu VMs für die Betriebsverfolgung hinzufügen

Dieser Leitfaden behandelt das Ändern von Virtual-Machine-Konfigurationen in VergeOS nach der Erstellung, einschließlich CPU/RAM-Updates, Laufwerksverwaltung, Änderungen an Netzwerkschnittstellen und das Hinzufügen von Betriebsnotizen.

Stufe: VM-Konfiguration (3 von 4) Eingabe: VM-Schlüssel (42) + Maschinen-Schlüssel (54), Konfigurationsänderungen Ausgabe: Aktualisierte VM-Einstellungen, geänderte Hardware Vorherige: VM eingeschaltet → VM-Energieverwaltung Häufige nächste Schritte:

• Erweiterte Vorgänge → Erweiterte VM-Vorgänge

• Neustart für Änderungen → VM-Energieverwaltung

Dieses Dokument hilft bei

• "Wie man VM-CPU und RAM ändert"

• "Speicherlaufwerke zu vorhandenen VMs hinzufügen"

• "VM-Laufwerke und Speichergrößen ändern"

• "VM-Netzwerkschnittstellen verwalten"

• "Notizen und Dokumentation zu VMs hinzufügen"

• "Hotplug-Operationen und Live-Änderungen"

• "VM-Leistungsoptimierung"

• "Arbeitsabläufe zur Speichererweiterung"

• "Netzwerkkonfiguration neu gestalten"

Kurzreferenz

Primäre Endpunkte

• VM-Einstellungen: PUT /api/v4/vms/{id}

• VM-Notizen: POST /api/v4/note_actions

• Laufwerksverwaltung: POST/PUT/DELETE /api/v4/machine_drives

• NIC-Verwaltung: POST/PUT/DELETE /api/v4/machine_nics

Wichtige Konzepte

• VM-Schlüssel: Für VM-Einstellungen verwenden (CPU, RAM, Konsole)

• Maschinen-Schlüssel: Für Hardware verwenden (Laufwerke, NICs, Geräte)

• Hotplug: Einige Änderungen erfordern einen Neustart der VM

Authentifizierung

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

Voraussetzungen

Die VM muss zuerst erstellt werden → Siehe VM-Erstellung

API-Kurzreferenz

Vorgang	Methode	Endpunkt	Schlüsseltyp	Zweck
VM aktualisieren	PUT	/api/v4/vms/{id}	VM-Schlüssel	CPU-, RAM- und Konsoleneinstellungen
Notiz hinzufügen	POST	/api/v4/note_actions	VM-Schlüssel	Dokumentation
Laufwerk hinzufügen	POST	/api/v4/machine_drives	Maschinen-Schlüssel	Speichererweiterung
Laufwerk vergrößern	PUT	/api/v4/machine_drives/{id}	Laufwerksschlüssel	Festplattengröße erhöhen
Laufwerk entfernen	DELETE	/api/v4/machine_drives/{id}	Laufwerksschlüssel	Speicherentfernung
NIC hinzufügen	POST	/api/v4/machine_nics	Maschinen-Schlüssel	Netzwerkschnittstelle
NIC aktualisieren	PUT	/api/v4/machine_nics/{id}	NIC-Schlüssel	Netzwerkänderungen
NIC entfernen	DELETE	/api/v4/machine_nics/{id}	NIC-Schlüssel	Schnittstellenentfernung

Index zur Fehlerbehebung

• 400 Ungültige Anfrage: Ungültige RAM-Größe, ungültige CPU-Anzahl, fehlerhaftes JSON

• 409 Konflikt: VM muss gestoppt sein, Hotplug wird nicht unterstützt, Ressource wird bereits verwendet

• 507 Unzureichender Speicher: Tier voll, Festplattengröße zu groß, Kontingent überschritten

• 403 Verboten: API-Schlüssel-Berechtigungen, Zugriff auf VM verweigert, Cluster-Einschränkungen

• 422 Nicht verarbeitbare Entität: Laufwerk kann nicht verkleinert werden, ungültiger Schnittstellentyp

• 404 Nicht gefunden: VM nicht gefunden, Laufwerk nicht gefunden, NIC nicht gefunden, ungültiges vnet

CPU- und RAM-Updates

PUT /api/v4/vms/{id}

Beschreibung: Aktualisiert die VM-Konfiguration. Verwendet den VM-Schlüssel (nicht den Maschinenschlüssel) für Einstellungen auf VM-Ebene.

Beispiel für den Anfragekörper:

{
  "ram": 16384,
  "cpu_cores": 3,
  "console": "spice",
  "video": "qxl",
  "show_advanced": "true",
  "nested_virtualization": "true",
  "disable_hypervisor": "true"
}

Vollständiger API-Aufruf:

curl -X PUT "https://your-vergeos.example.com/api/v4/vms/42" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "ram": 16384,
    "cpu_cores": 3,
    "console": "spice",
    "video": "qxl",
    "show_advanced": "true",
    "nested_virtualization": "true",
    "disable_hypervisor": "true"
  }'

Allgemeine Konfigurationsparameter

Parameter	Typ	Beschreibung	Neustart erforderlich
ram	ganze Zahl	RAM in MB	Meistens ja
cpu_cores	ganze Zahl	Anzahl der CPU-Kerne	Meistens ja
Konsole	string	Konsolentyp (spice, vnc, none)	Beim nächsten Start
video	string	Video-Adapter (qxl, virtio, std, cirrus)	Beim nächsten Start
nested_virtualization	string	Verschachtelte Virtualisierung aktivieren ("true"/"false")	Ja
disable_hypervisor	string	Hypervisor deaktivieren ("true"/"false")	Ja
guest_agent	string	Gast-Agent aktivieren ("true"/"false")	Beim nächsten Start
uefi	string	UEFI-Start aktivieren ("true"/"false")	Ja
secure_boot	string	Secure Boot aktivieren ("true"/"false")	Ja

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

• VM-Einstellungen (CPU, RAM, Konsole, Video): VM-Schlüssel verwenden (z. B. 42) mit /api/v4/vms/{vm_key}

• Hardwareänderungen (Laufwerke, NICs, Geräte): Maschinenschlüssel verwenden (z. B. 54) mit /api/v4/machine_* Endpunkte

Konfigurationsänderungen

• CPU- und RAM-Änderungen erfordern normalerweise einen Neustart der VM

• Änderungen an Konsole und Video werden beim nächsten VM-Start wirksam

• Einstellungen für verschachtelte Virtualisierung und Hypervisor erfordern einen Neustart der VM

• Immer prüfen allow_hotplug Einstellung für Hot-Add-Funktionen

Notizen zu VMs hinzufügen

POST /api/v4/note_actions

Beschreibung: Fügt Notizen für eine VM in der VergeOS-Benutzeroberfläche für Dokumentationszwecke hinzu oder aktualisiert sie.

Anfragetext:

{
  "owner": "vms/42",
  "action": "update",
  "params": {
    "text": "Dies ist eine Test-VM"
  }
}

Vollständiger API-Aufruf:

curl -X POST "https://your-vergeos.example.com/api/v4/note_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "owner": "vms/42",
    "action": "update",
    "params": {
      "text": "Produktions-Webserver - Aktualisiert am 2025-08-24"
    }
  }'

Parameter:

Name	Typ	Erforderlich	Beschreibung
owner	string	Ja	Ressourcenkennung (Format: "vms/{vm_key}")
action	string	Ja	Auszuführende Aktion ("update")
params.text	string	Ja	Textinhalt der Notiz

VM-Notizen

Notizen sind in der VergeOS-Benutzeroberfläche sichtbar und helfen bei der VM-Dokumentation, Wartungsplänen oder Konfigurationsdetails. Verwenden Sie im Feld owner den VM-Schlüssel (nicht den Maschinenschlüssel).

Laufwerksverwaltung

Neue Laufwerke hinzufügen

Verwenden Sie den Endpunkt für Maschinenlaufwerke, um nach der VM-Erstellung Speicher hinzuzufügen:

POST /api/v4/machine_drives

{
  "machine": "54",
  "name": "Datenlaufwerk",
  "interface": "virtio-scsi",
  "media": "disk",
  "disksize": 536870912000,
  "preferred_tier": "2"
}

Vollständiger API-Aufruf:

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": "Datenlaufwerk",
    "interface": "virtio-scsi",
    "media": "disk",
    "disksize": 536870912000,
    "preferred_tier": "2"
  }'

Laufwerke vergrößern

PUT /api/v4/machine_drives/{drive_id}

Beschreibung: Vergrößert die Größe eines vorhandenen Laufwerks. Beachten Sie, dass Laufwerke nur erweitert, nicht verkleinert werden können.

{
  "disksize": 1073741824000
}

Vollständiger API-Aufruf:

curl -X PUT "https://your-vergeos.example.com/api/v4/machine_drives/55" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "disksize": 1073741824000
  }'

Laufwerksvergrößerung

• Laufwerke können nur erweitert, niemals verkleinert werden

• Das Gastbetriebssystem muss möglicherweise so konfiguriert werden, dass es die neue Größe erkennt

• Einige Dateisysteme erfordern nach der Größenänderung des Laufwerks eine manuelle Erweiterung

Laufwerke entfernen

Vor dem Löschen müssen Laufwerke im laufenden Betrieb getrennt werden, wenn die VM läuft:

Schritt 1: Laufwerk im laufenden Betrieb trennen (wenn die VM läuft)

curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "vm": "42",
    "action": "hotplugdrive",
    "params": {
      "device": "drive-id-here",
      "unplug": true
    }
  }'

Schritt 2: Laufwerk löschen

DELETE /api/v4/machine_drives/{drive_id}

curl -X DELETE "https://your-vergeos.example.com/api/v4/machine_drives/55" \
  -H "Authorization: Bearer YOUR_API_KEY"

Beispiele zur Laufwerksverwaltung

Hinzufügen eines CDROM/ISO

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

Hinzufügen eines Importlaufwerks

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

Verwaltung von Netzwerkschnittstellen

NICs hinzufügen

POST /api/v4/machine_nics

{
  "machine": "54",
  "name": "Sekundäres Netzwerk",
  "interface": "virtio",
  "vnet": "8",
  "enabled": true
}

Vollständiger API-Aufruf:

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",
    "name": "Sekundäres Netzwerk",
    "interface": "virtio",
    "vnet": "8",
    "enabled": true
  }'

NIC-Konfiguration aktualisieren

PUT /api/v4/machine_nics/{nic_id}

{
  "vnet": "10",
  "enabled": true
}

Vollständiger API-Aufruf:

curl -X PUT "https://your-vergeos.example.com/api/v4/machine_nics/78" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "vnet": "10",
    "enabled": true
  }'

NICs entfernen

DELETE /api/v4/machine_nics/{nic_id}

curl -X DELETE "https://your-vergeos.example.com/api/v4/machine_nics/78" \
  -H "Authorization: Bearer YOUR_API_KEY"

NIC-Konfigurationsparameter

Parameter	Typ	Erforderlich	Beschreibung
machine	string	Ja	Maschinen-ID
vnet	string	Ja	ID des virtuellen Netzwerks
name	string	Nein	NIC-Name
interface	string	Nein	NIC-Schnittstellentyp (virtio, e1000, rtl8139)
aktiviert	boolesch	Nein	Aktivierter Zustand der NIC

Schlüssel virtueller Netzwerke

Der vnet Der Parameter verwendet den Schlüssel/die ID des Netzwerks. Sie können Netzwerkschlüssel finden, indem Sie die verfügbaren Netzwerke über den API-Endpunkt für Netzwerke auflisten.

Vollständiger Konfigurations-Workflow

Hier ist ein Beispiel für das Aktualisieren einer vollständigen VM-Konfiguration:

# Schritt 1: VM-Einstellungen aktualisieren (CPU, RAM, Konsole)
curl -X PUT "https://your-vergeos.example.com/api/v4/vms/42" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "ram": 32768,
    "cpu_cores": 8,
    "console": "spice",
    "video": "virtio"
  }'

# Schritt 2: Betriebsnotiz hinzufügen
curl -X POST "https://your-vergeos.example.com/api/v4/note_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "owner": "vms/42",
    "action": "update",
    "params": {
      "text": "Auf 32 GB RAM und 8 Kerne für erhöhte Arbeitslast aufgerüstet - 2025-08-24"
    }
  }'

# Schritt 3: Zusätzlichen Speicher 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": "Anwendungsdaten",
    "interface": "virtio-scsi",
    "media": "disk",
    "disksize": 1073741824000,
    "preferred_tier": "2"
  }'

# Schritt 4: Sekundäre 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",
    "name": "Verwaltungsnetzwerk",
    "interface": "virtio",
    "vnet": "5",
    "enabled": true
  }'

Best Practices für die Konfiguration

Vor dem Vornehmen von Änderungen

1. VM-Status prüfen: Sicherstellen, dass sich die VM für Änderungen in einem geeigneten Zustand befindet

2. Wichtige Daten sichern: Vor größeren Änderungen Snapshots erstellen

3. Abhängigkeiten überprüfen: Auswirkungen auf laufende Anwendungen berücksichtigen

4. Ausfallzeit einplanen: Einige Änderungen erfordern einen Neustart der VM

Nach dem Vornehmen von Änderungen

1. Konfiguration überprüfen: Prüfen, ob die Änderungen korrekt übernommen wurden

2. Funktionalität testen: Sicherstellen, dass die VM wie erwartet funktioniert

3. Dokumentation aktualisieren: Notizen zu Konfigurationsänderungen hinzufügen

4. Leistung überwachen: Auf mögliche Leistungseinbußen achten

Überlegungen zu Hotplug

# Prüfen, ob die VM Hotplug unterstützt
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=allow_hotplug" \
  -H "Authorization: Bearer YOUR_API_KEY"

Hotplug-Unterstützung

Der allow_hotplug Die Einstellung ermöglicht das Hinzufügen und Entfernen im laufenden Betrieb von Laufwerken und NICs während die VM läuft:

• Laufwerke: Kann im laufenden Betrieb hinzugefügt/entfernt werden (Gastbetriebssystem muss dies unterstützen; Virtio-SCSI empfohlen)

• Netzwerkkarten: Kann im laufenden Betrieb hinzugefügt/entfernt werden (von vielen Gastbetriebssystemen weithin unterstützt)

• CPU/RAM: Änderungen erfordern immer einen Neustart der VM

Siehe Hot-Plug-Funktionen der VM für vollständige Details.

Fehlerbehandlung

Häufige Konfigurationsfehler

Fehler: 400 Bad Request - Ungültige RAM-Größe

{
  "error": "RAM-Größe muss mindestens 512 MB und höchstens 1048576 MB betragen"
}

Fehler: 409 Conflict - VM muss gestoppt sein

{
  "error": "CPU-Kerne können nicht geändert werden, während die VM ohne Hotplug-Unterstützung läuft"
}

Lösung: Stoppen Sie die VM oder prüfen Sie die Hotplug-Funktionen, bevor Sie Änderungen vornehmen.

Fehler: 507 Unzureichender Speicher

{
  "error": "Nicht genügend Speicherplatz in Tier 2 für die angeforderte Festplattengröße"
}

Lösung: Wählen Sie einen anderen Speichertier oder reduzieren Sie die Festplattengröße.

Verwandte Vorgänge

• VM-Erstellung: Siehe VM-Erstellung für die anfängliche VM-Einrichtung

• Energieverwaltung: Siehe VM-Energieverwaltung für Start-/Stopp-Operationen

• 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-Konfiguration:

• 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