> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/knowledge-base/de/automation-api/vm-creation-api.md). # VM-Erstellungs-API {% hint style="info" %} **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 {% endhint %} 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`](/knowledge-base/de/automation-api/vm-power-management.md) * Einstellungen konfigurieren → [`VM-Konfiguration`](/knowledge-base/de/automation-api/vm-configuration.md) * Erweiterte Vorgänge → [`Erweiterte VM-Vorgänge`](/knowledge-base/de/automation-api/vm-advanced-operations.md) ## 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 ```bash -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" ``` ### Nächste Schritte Nach der VM-Erstellung → Energieverwaltung ([`VM-Energieverwaltung`](/knowledge-base/de/automation-api/vm-power-management.md)) ## 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 ```bash # 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 | Ja | 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**: ```json { "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**: ```json { "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 {% hint style="success" %} **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 {% endhint %} ## 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 ```json { "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 | Ja | 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 ```json { "machine": "54", "name": "OS-Laufwerk", "media": "disk", "interface": "virtio-scsi", "disksize": 2199023255552, "preferred_tier": "1" } ``` **Beispiel für die Antwort**: ```json { "location": "/v4/machine_drives/54", "dbpath": "machine_drives/54", "$row": 54, "$key": "54" } ``` ### CDROM/ISO anhängen ```json { "machine": "54", "media": "cdrom", "interface": "ahci", "media_source": "7" } ``` **Beispiel für die Antwort**: ```json { "location": "/v4/machine_drives/55", "dbpath": "machine_drives/55", "$row": 55, "$key": "55" } ``` ### Importieren aus Medienquelle ```json { "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 | Ja | Maschinen-ID | | resource\_group | string | Ja | UUID der Ressourcengruppe für das Gerät | | settings\_args | Objekt | Nein | Gerätespezifische Einstellungen (leeres Objekt für grundlegenden Passthrough) | ### PCI-Passthrough-GPU ```json { "machine": "54", "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1", "settings_args": {} } ``` **Beispiel für die Antwort**: ```json { "location": "/v4/machine_devices/2", "dbpath": "machine_devices/2", "$row": 2, "$key": "2", "response": { "uuid": "934e250b-a13c-bd8f-104d-a31995b06eba" } } ``` {% hint style="success" %} **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 {% endhint %} ### Verfügbare Geräte finden ```bash # 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 | Ja | Maschinen-ID | | vnet | string | Ja | 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**: ```json { "machine": "54", "vnet": "3" } ``` **Beispiel für die Antwort**: ```json { "location": "/v4/machine_nics/78", "dbpath": "machine_nics/78", "$row": 78, "$key": "78" } ``` {% hint style="info" %} **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. {% endhint %} ## Vollständiges Beispiel für die VM-Erstellung Hier ist ein vollständiger Ablauf zum Erstellen einer VM mit Laufwerken, Geräten und Netzwerkschnittstellen: ```bash # 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": {} }' ``` {% hint style="info" %} **Verwandte Vorgänge** * **Energieverwaltung**: Siehe [`VM-Energieverwaltung`](/knowledge-base/de/automation-api/vm-power-management.md) zum Starten/Stoppen von VMs * **Konfiguration**: Siehe [`VM-Konfiguration`](/knowledge-base/de/automation-api/vm-configuration.md) für CPU-/RAM-Änderungen * **Erweiterte Vorgänge**: Siehe [`Erweiterte VM-Vorgänge`](/knowledge-base/de/automation-api/vm-advanced-operations.md) für Klonen und Snapshots {% endhint %} {% hint style="info" %} **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 {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/knowledge-base/de/automation-api/vm-creation-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.