> 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/fr/automation-api/vm-configuration.md).

# API de configuration des VM

{% hint style="info" %}
**Points clés**

* Modifier les paramètres de la VM comme le CPU, la RAM, la console et la vidéo via l’API REST
* Gérer les disques avec des capacités de redimensionnement, d’ajout et de suppression
* Mettre à jour les interfaces réseau et leurs configurations
* Ajouter des notes de documentation aux VM pour le suivi opérationnel
  {% endhint %}

Ce guide couvre la modification des configurations des machines virtuelles dans VergeOS après leur création, y compris les mises à jour CPU/RAM, la gestion des disques, les changements d’interface réseau et l’ajout de notes opérationnelles.

**Étape**: Configuration de la VM (3 sur 4) **Entrée**: clé VM (42) + clé machine (54), modifications de configuration **Sortie**: Paramètres de VM mis à jour, matériel modifié **Précédent**: VM sous tension → [`Gestion de l'alimentation de la VM`](/knowledge-base/fr/automation-api/vm-power-management.md) **Étapes suivantes courantes**:

* Opérations avancées → [`Opérations avancées de la VM`](/knowledge-base/fr/automation-api/vm-advanced-operations.md)
* Cycle d’alimentation pour appliquer les changements → [`Gestion de l'alimentation de la VM`](/knowledge-base/fr/automation-api/vm-power-management.md)

## Ce document aide pour

* "Comment changer le CPU et la RAM d’une VM"
* "Ajout de disques de stockage aux VM existantes"
* "Redimensionnement des disques et du stockage des VM"
* "Gestion des interfaces réseau des VM"
* "Ajout de notes et de documentation aux VM"
* "Opérations à chaud et modifications en direct"
* "Optimisation des performances de la VM"
* "Flux de travail d’extension du stockage"
* "Reconfiguration réseau"

## Référence rapide

### Endpoints principaux

* **Paramètres de la VM**: `PUT /api/v4/vms/{id}`
* **Notes de la VM**: `POST /api/v4/note_actions`
* **Gestion des disques**: `POST/PUT/DELETE /api/v4/machine_drives`
* **Gestion des NIC**: `POST/PUT/DELETE /api/v4/machine_nics`

### Concepts clés

* **clé VM**: À utiliser pour les paramètres de VM (CPU, RAM, console)
* **clé machine**: À utiliser pour le matériel (disques, NIC, périphériques)
* **Branchement à chaud**: Certains changements nécessitent un redémarrage de la VM

### Authentification

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

### Prérequis

La VM doit d'abord être créée → Voir [`Création de VM`](/knowledge-base/fr/automation-api/vm-creation-api.md)

## Référence rapide de l'API

| Opération                | Méthode | Point de terminaison          | Type de clé   | Objectif                      |
| ------------------------ | ------- | ----------------------------- | ------------- | ----------------------------- |
| Mettre à jour la VM      | PUT     | `/api/v4/vms/{id}`            | clé VM        | Paramètres CPU, RAM, console  |
| Ajouter une note         | POST    | `/api/v4/note_actions`        | clé VM        | Documentation                 |
| Ajouter un disque        | POST    | `/api/v4/machine_drives`      | clé machine   | Extension du stockage         |
| Redimensionner le disque | PUT     | `/api/v4/machine_drives/{id}` | Clé du disque | Augmenter la taille du disque |
| Supprimer le disque      | DELETE  | `/api/v4/machine_drives/{id}` | Clé du disque | Suppression du stockage       |
| Ajouter une NIC          | POST    | `/api/v4/machine_nics`        | clé machine   | Interface réseau              |
| Mettre à jour la NIC     | PUT     | `/api/v4/machine_nics/{id}`   | Clé de la NIC | Modifications réseau          |
| Supprimer la NIC         | DELETE  | `/api/v4/machine_nics/{id}`   | Clé de la NIC | Suppression de l’interface    |

## Index de dépannage

* **400 Mauvaise requête**: Taille de RAM invalide, nombre de CPU invalide, JSON mal formé
* **409 Conflit**: La VM doit être arrêtée, le hotplug n’est pas pris en charge, ressource en cours d’utilisation
* **507 Stockage insuffisant**: Niveau plein, taille de disque trop grande, quota dépassé
* **403 Interdit**: autorisations de la clé API, accès à la VM refusé, restrictions du cluster
* **422 Entité non traitable**: Le disque ne peut pas être réduit, type d’interface invalide
* **404 Introuvable**: VM introuvable, disque introuvable, NIC introuvable, vnet invalide

## Mises à jour du CPU et de la RAM

### PUT /api/v4/vms/{id}

**Description**: Met à jour la configuration de la VM. Utilise la clé VM (et non la clé machine) pour les paramètres au niveau de la VM.

**Exemple du corps de la requête**:

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

**Appel API complet**:

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

### Paramètres de configuration courants

| Paramètre              | Type   | Description                                          | Redémarrage requis    |
| ---------------------- | ------ | ---------------------------------------------------- | --------------------- |
| ram                    | entier | RAM en Mo                                            | Généralement oui      |
| cpu\_cores             | entier | Nombre de cœurs CPU                                  | Généralement oui      |
| console                | chaîne | Type de console (spice, vnc, none)                   | Au prochain démarrage |
| video                  | chaîne | Adaptateur vidéo (qxl, virtio, std, cirrus)          | Au prochain démarrage |
| nested\_virtualization | chaîne | Activer la virtualisation imbriquée ("true"/"false") | Oui                   |
| disable\_hypervisor    | chaîne | Désactiver l’hyperviseur ("true"/"false")            | Oui                   |
| guest\_agent           | chaîne | Activer l'agent invité ("true"/"false")              | Au prochain démarrage |
| uefi                   | chaîne | Activer le démarrage UEFI ("true"/"false")           | Oui                   |
| secure\_boot           | chaîne | Activer le démarrage sécurisé ("true"/"false")       | Oui                   |

{% hint style="success" %}
**Clé VM vs clé machine**

* **Paramètres de la VM** (CPU, RAM, console, vidéo) : utiliser la clé VM (par ex., `42`) avec `/api/v4/vms/{vm_key}`
* **Modifications matérielles** (disques, NIC, périphériques) : utiliser la clé machine (par ex., `54`) avec `/api/v4/machine_*` points de terminaison
  {% endhint %}

{% hint style="warning" %}
**Modifications de configuration**

* Les changements de CPU et de RAM nécessitent généralement un redémarrage de la VM
* Les changements de console et de vidéo prennent effet au prochain démarrage de la VM
* Les paramètres de virtualisation imbriquée et d’hyperviseur nécessitent un redémarrage de la VM
* Vérifiez toujours `allow_hotplug` paramètre pour les capacités d’ajout à chaud
  {% endhint %}

## Ajout de notes aux VM

### POST /api/v4/note\_actions

**Description**: Ajoute ou met à jour les notes d’une VM dans l’interface VergeOS à des fins de documentation.

**Corps de la requête**:

```json
{
  "owner": "vms/42",
  "action": "update",
  "params": {
    "text": "Ceci est une VM de test"
  }
}
```

**Appel API complet**:

```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": "Serveur web de production - Mis à jour le 2025-08-24"
    }
  }'
```

**Paramètres**:

| Nom         | Type   | Obligatoire | Description                                         |
| ----------- | ------ | ----------- | --------------------------------------------------- |
| owner       | chaîne | Oui         | Identifiant de ressource (format : "vms/{vm\_key}") |
| action      | chaîne | Oui         | Action à effectuer ("update")                       |
| params.text | chaîne | Oui         | Contenu du texte de la note                         |

{% hint style="success" %}
**Notes de la VM**

Les notes sont visibles dans l’interface VergeOS et aident à la documentation des VM, aux plannings de maintenance ou aux détails de configuration. Utilisez la clé VM (et non la clé machine) dans le champ owner.
{% endhint %}

## Gestion des disques

### Ajout de nouveaux disques

Utilisez le point de terminaison des disques machine pour ajouter du stockage après la création de la VM :

#### POST /api/v4/machine\_drives

```json
{
  "machine": "54",
  "name": "Disque de données",
  "interface": "virtio-scsi",
  "media": "disk",
  "disksize": 536870912000,
  "preferred_tier": "2"
}
```

**Appel API complet**:

```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": "Disque de données",
    "interface": "virtio-scsi",
    "media": "disk",
    "disksize": 536870912000,
    "preferred_tier": "2"
  }'
```

### Redimensionnement des disques

#### PUT /api/v4/machine\_drives/{drive\_id}

**Description**: Augmente la taille d’un disque existant. Notez que les disques peuvent seulement être agrandis, pas réduits.

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

**Appel API complet**:

```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" %}
**Redimensionnement du disque**

* Les disques peuvent seulement être agrandis, jamais réduits
* Le système d’exploitation invité peut devoir être configuré pour reconnaître la nouvelle taille
* Certains systèmes de fichiers nécessitent une विस्तारion manuelle après le redimensionnement du disque
  {% endhint %}

### Suppression des disques

Avant la suppression, les disques doivent être désattachés à chaud si la VM est en cours d’exécution :

#### Étape 1 : désattacher le disque à chaud (si la VM est en cours d’exécution)

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

#### Étape 2 : supprimer le disque

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

### Exemples de gestion des disques

#### Ajout d’un CDROM/ISO

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

#### Ajout d’un disque d’importation

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

## Gestion des interfaces réseau

### Ajout de NIC

#### POST /api/v4/machine\_nics

```json
{
  "machine": "54",
  "name": "Réseau secondaire",
  "interface": "virtio",
  "vnet": "8",
  "enabled": true
}
```

**Appel API complet**:

```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": "Réseau secondaire",
    "interface": "virtio",
    "vnet": "8",
    "enabled": true
  }'
```

### Mise à jour de la configuration de la NIC

#### PUT /api/v4/machine\_nics/{nic\_id}

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

**Appel API complet**:

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

### Suppression des NIC

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

### Paramètres de configuration de la NIC

| Paramètre | Type    | Obligatoire | Description                                   |
| --------- | ------- | ----------- | --------------------------------------------- |
| machine   | chaîne  | Oui         | ID de machine                                 |
| vnet      | chaîne  | Oui         | ID du réseau virtuel                          |
| name      | chaîne  | Non         | Nom de la NIC                                 |
| interface | chaîne  | Non         | Type d’interface NIC (virtio, e1000, rtl8139) |
| enabled   | booléen | Non         | État d'activation de la NIC                   |

{% hint style="info" %}
**Clés de réseau virtuel**

Le `vnet` ce paramètre utilise la clé/l’ID du réseau. Vous pouvez trouver les clés de réseau en listant les réseaux disponibles via le point de terminaison de l’API des réseaux.
{% endhint %}

## Flux de configuration complet

Voici un exemple de mise à jour de la configuration complète d’une VM :

```bash
# Étape 1 : mettre à jour les paramètres de la VM (CPU, RAM, console)
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"
  }'

# Étape 2 : ajouter une note opérationnelle
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": "Passé à 32 Go de RAM et 8 cœurs pour augmenter la charge de travail - 2025-08-24"
    }
  }'

# Étape 3 : ajouter un stockage supplémentaire
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": "Données de l’application",
    "interface": "virtio-scsi",
    "media": "disk",
    "disksize": 1073741824000,
    "preferred_tier": "2"
  }'

# Étape 4 : ajouter une interface réseau secondaire
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": "Réseau de gestion",
    "interface": "virtio",
    "vnet": "5",
    "enabled": true
  }'
```

## Bonnes pratiques de configuration

### Avant d’apporter des modifications

1. **Vérifier l’état de la VM**: S’assurer que la VM est dans un état approprié pour les modifications
2. **Sauvegarder les données importantes**: Créer des instantanés avant les changements majeurs
3. **Examiner les dépendances**: Prendre en compte l’impact sur les applications en cours d’exécution
4. **Planifier une interruption**: Certains changements nécessitent un redémarrage de la VM

### Après avoir apporté des modifications

1. **Vérifier la configuration**: Vérifier que les changements ont été appliqués correctement
2. **Tester le fonctionnement**: S’assurer que la VM fonctionne comme prévu
3. **Mettre à jour la documentation**: Ajouter des notes sur les changements de configuration
4. **Surveiller les performances**: Surveiller tout impact sur les performances

### Considérations sur le hotplug

```bash
# Vérifier si la VM prend en charge le hotplug
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=allow_hotplug" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

{% hint style="success" %}
**Prise en charge du hotplug**

Le `allow_hotplug` ce paramètre permet l’ajout et la suppression à chaud **des disques et des NIC** pendant que la VM est en cours d’exécution :

* **Lecteurs**: Peut être ajouté/supprimé à la volée (le système d’exploitation invité doit le prendre en charge ; Virtio-SCSI recommandé)
* **Cartes réseau**: Peut être ajouté/supprimé à la volée (largement pris en charge par les systèmes d’exploitation invités)
* **CPU/RAM**: Les changements nécessitent toujours un cycle d’alimentation de la VM

Voir [Capacités de hotplug de la VM](/knowledge-base/fr/tenants/vm-hotplug-capabilities.md) pour plus de détails.
{% endhint %}

## Gestion des erreurs

### Erreurs de configuration courantes

**Erreur**: `400 Bad Request - Taille de RAM invalide`

```json
{
  "error": "La taille de la RAM doit être d’au moins 512 Mo et d’au plus 1048576 Mo"
}
```

**Erreur**: `409 Conflict - La VM doit être arrêtée`

```json
{
  "error": "Impossible de modifier les cœurs CPU pendant l’exécution de la VM sans prise en charge du hotplug"
}
```

**Solution**: Arrêtez la VM ou vérifiez les capacités de hotplug avant d’apporter des modifications.

**Erreur**: `507 Stockage insuffisant`

```json
{
  "error": "Espace de stockage insuffisant dans le niveau 2 pour la taille de disque demandée"
}
```

**Solution**: Choisissez un autre niveau de stockage ou réduisez la taille du disque.

{% hint style="info" %}
**Opérations associées**

* **Création de VM**: Voir [`Création de VM`](/knowledge-base/fr/automation-api/vm-creation-api.md) pour la configuration initiale de la VM
* **Gestion de l'alimentation**: Voir [`Gestion de l'alimentation de la VM`](/knowledge-base/fr/automation-api/vm-power-management.md) pour les opérations de démarrage/arrêt
* **Opérations avancées**: Voir [`Opérations avancées de la VM`](/knowledge-base/fr/automation-api/vm-advanced-operations.md) pour le clonage et les instantanés
  {% endhint %}

{% hint style="info" %}
**Besoin d’aide ?**

Pour obtenir une सहायता supplémentaire avec la configuration de la VM :

* Consultez le portail de documentation VergeOS
* Contactez le support VergeOS avec des messages d'erreur spécifiques
* Consultez les journaux système pour obtenir des informations détaillées sur l'erreur
* Consultez les forums communautaires VergeOS
  {% 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/fr/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.