> 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/learn-the-platform/fr/module-8-developpement-et-devops/04-terraform-packer.md).

# Terraform et Packer

Infrastructure déclarative en tant que code pour VergeOS avec le fournisseur Terraform, OpenTofu et le plugin Packer pour la création automatisée d’images de référence.

L’Infrastructure as Code (IaC) apporte le même contrôle de version, la même relecture par les pairs et la même reproductibilité sur le provisionnement de l’infrastructure que celles sur lesquelles les équipes logiciel s’appuient. Le **fournisseur Terraform VergeOS** vous permet de déclarer des VM, des réseaux et des utilisateurs dans des fichiers de configuration HCL, tandis que le **plugin Packer** automatise la création d’images dorées. Ensemble, ils forment un pipeline déclaratif : Packer construit les images, Terraform déploie l’infrastructure.

## Fournisseur Terraform

Le fournisseur Terraform VergeOS est publié sur le Terraform Registry et est entièrement compatible avec **OpenTofu** (le fork open source de Terraform). Il vous permet de gérer les ressources VergeOS via des workflows standards de `terraform plan` / `terraform apply` .

### Configuration du fournisseur

```hcl
terraform {
  required_providers {
    vergeio = {
      source  = "verge-io/vergeio"
      version = "~> 2.7"
    }
  }
}

provider "vergeio" {
  host     = "https://vergeos.example.com"
  username = "admin"
  password = var.vergeos_password
  insecure = true  # Définir à true pour les certificats SSL auto-signés
}
```

| Paramètre    | Requis | Description                                                       |
| ------------ | ------ | ----------------------------------------------------------------- |
| **host**     | Oui    | URL ou adresse IP du système ou du locataire VergeOS              |
| **username** | Oui    | Nom d’utilisateur VergeOS disposant des autorisations appropriées |
| **password** | Oui    | Mot de passe de l’utilisateur spécifié (marquer comme `sensible`) |
| **insecure** | Non    | Définir `true` pour accepter les certificats SSL auto-signés      |

{% hint style="success" %}
**Compatible OpenTofu**

La configuration du fournisseur est identique pour OpenTofu. Remplacez simplement `terraform` les commandes par `tofu` — aucun changement de code n’est requis.
{% endhint %}

### Ressources

Le fournisseur prend actuellement en charge cinq types de ressources gérées pour créer et mettre à jour des objets VergeOS :

| Ressource                | Objectif                               | Attributs clés                                                                                                                                                                                  |
| ------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`vergeio_vm`**         | Créer et gérer des machines virtuelles | `cpu_cores`, `ram`, `os_family`, `machine_type`, `ha_group`, `cluster`, `guest_agent`, `uefi`, `secure_boot`, `snapshot_profile`, `powerstate`, en ligne `vergeio_drive` et `vergeio_nic` blocs |
| **`vergeio_network`**    | Configurer des réseaux virtuels        | `network` (CIDR), `dhcp_enabled`, `dhcp_start`, `dhcp_stop`, `vnet_default_gateway`, `powerstate`                                                                                               |
| **`vergeio_user`**       | Provisionner des utilisateurs          | Gestion des comptes utilisateurs dans VergeOS                                                                                                                                                   |
| **`vergeio_member`**     | Gérer l’appartenance aux groupes       | Associer des utilisateurs à des groupes pour le RBAC                                                                                                                                            |
| **`vergeio_tag_member`** | Attribuer des étiquettes aux objets    | Attacher des étiquettes aux VM, aux réseaux et à d’autres objets VergeOS (VergeOS v26+)                                                                                                         |

### Sources de données

Dix sources de données en lecture seule vous permettent d’interroger des objets VergeOS existants à utiliser dans vos configurations :

| Source de données             | Retourne                                                   |
| ----------------------------- | ---------------------------------------------------------- |
| **`vergeio_version`**         | Informations sur la version actuelle de VergeOS            |
| **`vergeio_clusters`**        | Clusters de calcul/stockage disponibles                    |
| **`vergeio_nodes`**           | Nœuds dans l’environnement                                 |
| **`vergeio_networks`**        | Réseaux virtuels existants                                 |
| **`vergeio_vms`**             | Machines virtuelles (filtrables par nom, état de snapshot) |
| **`vergeio_groups`**          | Groupes d’utilisateurs pour le RBAC                        |
| **`vergeio_mediasources`**    | ISO et fichiers multimédias téléversés                     |
| **`vergeio_cloudinitfiles`**  | Fichiers de configuration cloud-init disponibles           |
| **`vergeio_resource_groups`** | Groupes de ressources matérielles (pools PCI, USB, vGPU)   |
| **`vergeio_tags`**            | Étiquettes configurées dans VergeOS                        |

### Exemples HCL

#### VM avec disque et NIC

Cet exemple crée un serveur web Linux avec un disque virtio-scsi de 10 Go et une NIC attachée à un réseau interne :

```hcl
resource "vergeio_vm" "web_server" {
  name                 = "my-web-server"
  description          = "Serveur web"
  enabled              = true
  os_family            = "linux"
  cpu_cores            = 2
  machine_type         = "q35"
  ram                  = 2048
  powerstate           = false
  guest_agent          = true
  cloudinit_datasource = "nocloud"
  ha_group             = "web"

  # Stockage
  vergeio_drive {
    name           = "Disque système du serveur web"
    description    = "Disque du système d’exploitation"
    disksize       = 10
    interface      = "virtio-scsi"
    preferred_tier = 3
    orderid        = 0
  }

  # Réseau
  vergeio_nic {
    name        = "Réseau du serveur web"
    description = "NIC pour le serveur web"
    interface   = "virtio"
    enabled     = true
    vnet        = vergeio_network.web_network.id
  }
}
```

#### Réseau interne avec DHCP

```hcl
resource "vergeio_network" "web_network" {
  name         = "web-internal-network"
  network      = "192.168.10.0/24"
  dhcp_enabled = true
  dhcp_start   = "192.168.10.100"
  dhcp_stop    = "192.168.10.200"
}
```

#### Interrogation des VM existantes

Utilisez des sources de données pour référencer une infrastructure existante sans la gérer :

```hcl
data "vergeio_vms" "production" {
  filter_name = "prod-db"
  is_snapshot  = false
}

output "production_vms" {
  value = data.vergeio_vms.production.vms
}
```

#### Intégration Cloud-Init

La `vergeio_vm` ressource prend en charge cloud-init pour l’automatisation du premier démarrage. Le schéma du fournisseur expose un `cloudinit_datasource` attribut sur la VM et une `vergeio_cloudinitfiles` source de données pour référencer des fichiers cloud-init déjà présents dans VergeOS :

```hcl
resource "vergeio_vm" "app_server" {
  name                 = "app-server-01"
  os_family            = "linux"
  cpu_cores            = 4
  machine_type         = "q35"
  ram                  = 8192
  guest_agent          = true
  cloudinit_datasource = "nocloud"

  vergeio_drive {
    name           = "Disque du système d’exploitation"
    disksize       = 20
    interface      = "virtio-scsi"
    preferred_tier = 2
  }

  vergeio_nic {
    interface = "virtio"
    vnet      = vergeio_network.web_network.id
  }
}
```

Pour la syntaxe exacte utilisée pour attacher des fichiers cloud-init en ligne sur la ressource VM (par opposition au référencement de fichiers pré-téléversés via la source de données), consultez le [dépôt du fournisseur](https://github.com/verge-io/terraform-provider-vergeio) — le formulaire au niveau des champs peut évoluer entre les versions.

### Maturité et feuille de route

{% hint style="warning" %}
**Vérifier la couverture actuelle des ressources**

Le fournisseur Terraform VergeOS est en développement actif, et tous les objets VergeOS ne sont pas encore exposés en tant que ressources gérées. Parmi les domaines qui peuvent ne pas avoir une couverture complète à un moment donné figurent le provisionnement de locataires, la gestion des profils de snapshot et la configuration des réseaux externes/WAN.

Vérifiez toujours le [dépôt GitHub](https://github.com/verge-io/terraform-provider-vergeio) et la liste du Terraform Registry pour connaître la couverture actuelle des ressources et les notes de version avant de concevoir une configuration autour d’elles.
{% endhint %}

## Plugin Packer

La **Plugin Packer pour VergeOS** (`github.com/verge-io/packer-plugin-vergeio`) automatise la création d’images de VM directement sur la plateforme VergeOS. Là où Terraform gère l’infrastructure en cours d’exécution, Packer se concentre sur la création des **images dorées** qui servent de fondation aux déploiements.

### Pourquoi Packer ?

```mermaid
flowchart LR
    A["ISO de base"] --> B["Génération Packer"]
    B --> C["Installer les paquets<br/>Durcir l’OS<br/>Configurer les services"]
    C --> D["Image dorée"]
    D --> E["Recette de VM"]
    D --> F["Déploiement Terraform"]
    D --> G["Provisionnement manuel"]

    style B fill:#4a9eff,color:#fff
    style D fill:#2ecc71,color:#fff
```

Les images dorées garantissent que chaque VM déployée démarre à partir d’une base connue, testée et durcie. Au lieu de provisionner un OS vierge et d’exécuter des scripts de configuration à chaque déploiement, Packer prépare l’image une seule fois :

* **Cohérence** — Chaque VM créée à partir de l’image est identique
* **Rapidité** — Aucun délai de provisionnement au premier démarrage ; les VM sont prêtes immédiatement
* **Conformité** — Les bases de sécurité et les correctifs sont intégrés au moment de la construction
* **Intégration au pipeline** — Déclencher des reconstructions d’images depuis la CI/CD lors des journées de correctifs du système d’exploitation

### Configuration du plugin

Le plugin Packer se déclare dans un `required_plugins` bloc aux côtés d’un `source` et `build` pour l’image cible. Les noms exacts des champs pour le `bloc source "vergeio"` (point de terminaison, identifiants, dimensionnement de VM, options de disque, etc.) doivent être repris du dépôt du plugin, car ils peuvent évoluer entre les versions :

* [`verge-io/packer-plugin-vergeio` sur GitHub](https://github.com/verge-io/packer-plugin-vergeio)

Une `required_plugins` déclaration typique ressemble à ceci :

```hcl
packer {
  required_plugins {
    vergeio = {
      source  = "github.com/verge-io/vergeio"
      version = ">= 0.1.1"
    }
  }
}
```

### Capacités

À haut niveau, le plugin orchestre l’ensemble du cycle de vie de build Packer via l’API VergeOS — création d’une VM temporaire, exécution des provisioners et capture de l’image résultante. Pour le schéma de configuration exact, les types de systèmes invités pris en charge et le comportement d’arrêt/nettoyage, consultez directement le dépôt du plugin :

* [`verge-io/packer-plugin-vergeio` sur GitHub](https://github.com/verge-io/packer-plugin-vergeio)

### Pipeline Packer → Recettes

Les images Packer s’intègrent naturellement au système de **recettes** de VergeOS. Flux de travail typique :

1. **Packer** construit et durcit l’image dorée selon un calendrier (par exemple, cycle mensuel de correctifs)
2. L’image est enregistrée comme **recette de VM** dans la Marketplace VergeOS
3. Les utilisateurs déploient des VM standardisées à partir de la recette — soit via l’interface utilisateur, soit via Terraform
4. Les mises à jour s’enchaînent automatiquement : reconstruisez l’image Packer, mettez à jour la recette, et tous les nouveaux déploiements obtiennent la dernière version

## Schémas de workflow IaC

### Workflow uniquement Terraform

Pour les équipes qui veulent une infrastructure déclarative sans pipeline d’images :

```mermaid
flowchart LR
    A["Configuration HCL"] --> B["terraform plan"]
    B --> C["terraform apply"]
    C --> D["API VergeOS"]
    D --> E["VM + réseaux<br/>créés"]

    style B fill:#7b42f5,color:#fff
    style C fill:#4a9eff,color:#fff
```

### Pipeline complet (Packer + Terraform)

Pour les environnements de production avec gestion d’images dorées :

```mermaid
flowchart LR
    A["ISO de base"] --> B["Génération Packer"]
    B --> C["Image dorée"]
    C --> D["Déploiement Terraform"]
    D --> E["VM de production"]
    F["Déclencheur CI/CD"] -.-> B

    style B fill:#2ecc71,color:#fff
    style D fill:#4a9eff,color:#fff
```

### Associé à d’autres outils

Terraform gère le provisionnement ; les outils de gestion de configuration gèrent le reste :

| Phase                | Outil                        | Objectif                                       |
| -------------------- | ---------------------------- | ---------------------------------------------- |
| **Création d’image** | Packer                       | Construire des images dorées durcies           |
| **Provisionnement**  | Terraform                    | Déployer des VM, des réseaux, des utilisateurs |
| **Configuration**    | Ansible / cloud-init         | Configuration logicielle post-déploiement      |
| **Supervision**      | Prometheus / alertes VergeOS | Observer l’infrastructure déployée             |

{% hint style="info" %}
**Pont VMware**

Sur VMware, le fournisseur vSphere de Terraform gère ESXi/vCenter/vSAN comme des composantes distinctes et Packer utilise le `vsphere-iso` builder via vCenter. Le seul fournisseur VergeOS `vergeio` gère les VM, les réseaux, les disques et les utilisateurs via un seul point de terminaison d’API, et le plugin Packer cible la même API.
{% endhint %}

{% hint style="info" %}
**Pont Nutanix**

Le fournisseur Terraform Nutanix (`nutanix/nutanix`) et le plugin Packer ciblent tous deux l’API v3 de Prism Central. Le fournisseur VergeOS parle à un seul point de terminaison (l’URL du système ou du locataire VergeOS), sans instance de gestion séparée, et expose la configuration cloud-init directement sur la `vergeio_vm` ressource via le `cloudinit_datasource` attribut et la `vergeio_cloudinitfiles` source de données.
{% endhint %}

## Bonnes pratiques

### Gestion de l’état

* **Utilisez des backends d’état distants** (S3, Consul, Terraform Cloud) pour la collaboration en équipe
* **Ne commitez jamais** `terraform.tfstate` dans le contrôle de version — il peut contenir des identifiants
* **Verrouillez les fichiers d’état** pour éviter les modifications simultanées dans les environnements multi-utilisateurs

### Sécurité

* **Utilisez des variables** pour les valeurs sensibles (`var.vergeos_password`) — ne codez jamais les identifiants en dur
* **Marquez les sorties sensibles** avec `sensitive = true` pour éviter toute exposition accidentelle dans les journaux
* **Limitez les permissions du fournisseur** — créez un utilisateur API VergeOS dédié avec le minimum d’accès requis

### Organisation des modules

* **Séparez les environnements** en espaces de travail ou répertoires (`dev/`, `préproduction/`, `prod/`)
* **Créer des modules réutilisables** pour des schémas courants (par ex., un module « web-server » avec VM + réseau + règles de pare-feu)
* **Figer les versions des providers** pour éviter des changements cassants imprévus lors des mises à niveau

## Pour aller plus loin

* [Provider Terraform — GitHub](https://github.com/verge-io/terraform-provider-vergeio)
* [Registre Terraform — Provider VergeIO](https://registry.terraform.io/providers/verge-io/vergeio/latest)
* [Plugin Packer — GitHub](https://github.com/verge-io/packer-plugin-vergeio)
* [Registre OpenTofu — Provider VergeIO](https://search.opentofu.org/provider/verge-io/vergeio/latest)
* [Documentation VergeOS — Provider Terraform](https://docs.verge.io/automate-protect-and-extend/fr/integrations-et-api/terraform-provider.md)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.verge.io/learn-the-platform/fr/module-8-developpement-et-devops/04-terraform-packer.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
