> 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-configuration.md).

# VM-Konfigurations-API

{% hint style="info" %}
**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
  {% endhint %}

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`](/knowledge-base/de/automation-api/vm-power-management.md) **Häufige nächste Schritte**:

* Erweiterte Vorgänge → [`Erweiterte VM-Vorgänge`](/knowledge-base/de/automation-api/vm-advanced-operations.md)
* Neustart für Änderungen → [`VM-Energieverwaltung`](/knowledge-base/de/automation-api/vm-power-management.md)

## 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

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

### Voraussetzungen

Die VM muss zuerst erstellt werden → Siehe [`VM-Erstellung`](/knowledge-base/de/automation-api/vm-creation-api.md)

## 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**:

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

**Vollständiger API-Aufruf**:

```bash
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                    |

{% hint style="success" %}
**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
  {% endhint %}

{% hint style="warning" %}
**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
  {% endhint %}

## 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**:

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

**Vollständiger API-Aufruf**:

```bash
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                        |

{% hint style="success" %}
**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).
{% endhint %}

## 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

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

**Vollständiger API-Aufruf**:

```bash
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.

```json
{
  "disksize": 1073741824000
}
```

**Vollständiger API-Aufruf**:

```bash
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
  }'
```

{% hint style="warning" %}
**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
  {% endhint %}

### 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)

```bash
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}

```bash
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

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

#### Hinzufügen eines Importlaufwerks

```json
{
  "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

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

**Vollständiger API-Aufruf**:

```bash
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}

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

**Vollständiger API-Aufruf**:

```bash
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}

```bash
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                    |

{% hint style="info" %}
**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.
{% endhint %}

## Vollständiger Konfigurations-Workflow

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

```bash
# 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

```bash
# 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"
```

{% hint style="success" %}
**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](/knowledge-base/de/tenants/vm-hotplug-capabilities.md) für vollständige Details.
{% endhint %}

## Fehlerbehandlung

### Häufige Konfigurationsfehler

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

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

**Fehler**: `409 Conflict - VM muss gestoppt sein`

```json
{
  "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`

```json
{
  "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.

{% hint style="info" %}
**Verwandte Vorgänge**

* **VM-Erstellung**: Siehe [`VM-Erstellung`](/knowledge-base/de/automation-api/vm-creation-api.md) für die anfängliche VM-Einrichtung
* **Energieverwaltung**: Siehe [`VM-Energieverwaltung`](/knowledge-base/de/automation-api/vm-power-management.md) für Start-/Stopp-Operationen
* **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-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
  {% 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-configuration.md?ask=<question>&goal=<endgoal>
```

`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.