> 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/05-ansible.md).

# Collection Ansible

Automatisez l’infrastructure VergeOS avec la collection Ansible vergeio.vergeos — modules pour les instantanés de VM, le tagging et les imports, plus un plugin d’inventaire dynamique pour les environnements multi-sites.

Ansible apporte une automatisation sans agent et basée sur le push à la gestion d’infrastructure. Le **vergeio.vergeos** La collection Ansible étend Ansible avec des modules conçus à cet effet et un plugin d’inventaire pour VergeOS, vous permettant de gérer les instantanés de VM, d’organiser les ressources avec des tags, d’importer des images de VM et de découvrir dynamiquement l’infrastructure sur plusieurs sites — le tout via des playbooks YAML familiers.

## Vue d’ensemble de la collection

La collection Ansible VergeOS est publiée sur Ansible Galaxy et s’intègre directement à l’API REST de VergeOS via le **pyvergeos** SDK Python.

| Détail                 | Valeur                                                           |
| ---------------------- | ---------------------------------------------------------------- |
| **Espace de noms**     | `vergeio`                                                        |
| **Collection**         | `vergeos`                                                        |
| **Référence complète** | `vergeio.vergeos`                                                |
| **Python**             | >= 3.9                                                           |
| **Ansible**            | >= 2.14.0                                                        |
| **Dépendance du SDK**  | `pyvergeos` >= 1.0.1                                             |
| **Source**             | [GitHub](https://github.com/verge-io/ansible-collection-vergeos) |

### Installation

Installez la collection depuis Ansible Galaxy :

```bash
# Installer depuis Galaxy (recommandé)
ansible-galaxy collection install vergeio.vergeos

# Installer le SDK Python requis
pip install pyvergeos
```

Pour les environnements de développement ou hors ligne, construisez et installez depuis les sources :

```bash
git clone https://github.com/verge-io/ansible-collection-vergeos.git
cd ansible-collection-vergeos
ansible-galaxy collection build
ansible-galaxy collection install vergeio-vergeos-*.tar.gz --force
```

### Authentification

La collection utilise des variables d’environnement pour l’authentification à l’API, afin de garder les identifiants hors de vos playbooks et fichiers d’inventaire :

```bash
export VERGEOS_HOST="https://vergeos.example.com"
export VERGEOS_USERNAME="admin"
export VERGEOS_PASSWORD="your-password"
export VERGEOS_INSECURE="true"   # Définir à true pour les certificats SSL auto-signés
```

Vous pouvez également utiliser l’authentification par clé API pour les scénarios non interactifs comme les pipelines CI/CD. Les clés API sont créées dans **Système > Utilisateurs > \[sélectionner l’utilisateur] > Clés API** dans l’interface VergeOS et fournissent une authentification par jeton Bearer sans nécessiter d’identifiants nom d’utilisateur/mot de passe.

## Modules

La collection fournit des modules pour les opérations du cycle de vie des VM, le balisage et la gestion des images. Chaque module communique avec l’API VergeOS via le SDK pyvergeos.

### Module d’instantané de VM

Le `vergeio.vergeos.vm_snapshot` module crée et gère des instantanés de VM par programmation — utile pour l’automatisation des sauvegardes, les points de contrôle avant modification et les flux de travail de reprise après sinistre.

```yaml
- name: Créer un instantané du serveur de base de données
  vergeio.vergeos.vm_snapshot:
    vm_name: "db-server-01"
    description: "Instantané avant mise à niveau"
    retention: 86400 # Conserver pendant 24 heures (secondes)
    quiesce: true # Quiescer le système de fichiers de l’invité
```

### Modules de gestion des tags

Les tags offrent un système de classification flexible pour organiser les ressources VergeOS. La collection comprend deux modules pour la gestion des tags :

| Module                             | Objectif                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------ |
| **`vergeio.vergeos.tag_category`** | Créer et gérer des catégories de tags (par ex. « Environnement », « Service ») |
| **`vergeio.vergeos.tag`**          | Appliquer et gérer des tags individuels au sein des catégories                 |

```yaml
- name: Créer une catégorie de tags d’environnement
  vergeio.vergeos.tag_category:
    name: "Environment"
    description: "Classification de l’environnement de déploiement"

- name: Marquer la VM comme production
  vergeio.vergeos.tag:
    category: "Environment"
    name: "Production"
    resource_type: "vm"
    resource_name: "web-server-01"
```

### Capacités d’importation de VM

La collection déploie des VM à partir de modèles OVA déjà téléversés dans VergeOS — le `vm_import` module référence un OVA existant par son nom ou son ID, et le CPU ainsi que la RAM sont repris depuis l’OVA lui-même. Téléversez d’abord l’OVA (interface ou API), puis exécutez le playbook pour créer la VM.

## Plugin d’inventaire dynamique

Le `vergeos_vms` le plugin d’inventaire interroge l’API VergeOS pour découvrir dynamiquement les VM et construire l’inventaire Ansible — éliminant ainsi le besoin de maintenir des fichiers d’hôtes statiques.

{% hint style="warning" %}
**Inventaire API uniquement**

Le plugin d’inventaire récupère les métadonnées des VM depuis l’API VergeOS. Il ne **ne** renseigne pas `ansible_host` et ne prend pas en charge les connexions SSH directes nativement. Vous devez configurer `ansible_host` via des variables d’hôte, des règles de composition ou une stratégie de connexion distincte pour une exécution de playbook basée sur SSH.
{% endhint %}

### Configuration de l’inventaire

Créez un fichier d’inventaire (par ex.  `vergeos_inventory.yml`):

```yaml
plugin: vergeio.vergeos.vergeos_vms
sites :
  - name: "datacenter-east"
    host: "https://east.vergeos.example.com"
    username: "ansible-svc"
    password: "{{ lookup('env', 'VERGEOS_PASSWORD') }}"
    verify_ssl: false

  - name: "datacenter-west"
    host: "https://west.vergeos.example.com"
    username: "ansible-svc"
    password: "{{ lookup('env', 'VERGEOS_PASSWORD') }}"
    verify_ssl: false

# Filtres facultatifs
filters:
  status: "running"
  name_pattern: "prod-*"

# Activer la mise en cache pour les grands environnements
cache: true
cache_plugin: jsonfile
cache_connection: /tmp/vergeos_inventory_cache
cache_timeout: 300
```

### Groupement automatique

Le plugin organise automatiquement les VM découvertes en groupes selon plusieurs dimensions :

```mermaid
flowchart TD
    A["API VergeOS"] --> B["Plugin vergeos_vms"]
    B --> C["Par site"]
    B --> D["Par statut"]
    B --> E["Par tags"]
    B --> F["Par locataire"]
    B --> G["Par famille d’OS"]
    B --> H["Par cluster"]
    B --> I["Par nœud"]

    C --> J["datacenter_east<br/>datacenter_west"]
    D --> K["status_running<br/>status_stopped"]
    E --> L["tag_Production<br/>tag_Development"]
    F --> M["tenant_acme<br/>tenant_globex"]

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

| Dimension du groupe | Groupes d’exemple                        | Cas d’usage                                            |
| ------------------- | ---------------------------------------- | ------------------------------------------------------ |
| **Site**            | `datacenter_east`, `datacenter_west`     | Cibler des playbooks vers des emplacements spécifiques |
| **Statut**          | `status_running`, `status_stopped`       | Exécuter les tâches uniquement sur les VM actives      |
| **Tags**            | `tag_Production`, `tag_Development`      | Configuration spécifique à l’environnement             |
| **Locataire**       | `tenant_acme`, `tenant_globex`           | Automatisation multi-locataires                        |
| **Famille d’OS**    | `os_linux`, `os_windows`                 | Playbooks spécifiques à l’OS                           |
| **Cluster**         | `cluster_compute01`, `cluster_compute02` | Maintenance consciente du cluster                      |
| **Nœud**            | `node_node1`, `node_node2`               | Opérations au niveau du nœud                           |

### Variables d’hôte

Chaque VM découverte expose plus de 20 variables d’hôte, notamment l’ID de la VM, son nom, le nombre de cœurs CPU, la RAM, la famille d’OS, l’état d’alimentation, l’affectation au cluster, le placement sur le nœud, la configuration réseau, les tags et le dictionnaire complet des données de la VM pour les cas d’usage avancés.

## Modèles de playbooks

### Orchestration d’instantanés multi-sites

Utilisez le filtrage basé sur les tags avec l’inventaire dynamique pour orchestrer les instantanés sur plusieurs sites :

```yaml
---
- name: Créer un instantané de toutes les bases de données de production sur tous les sites
  hosts: tag_Production:&os_linux
  gather_facts: false

  tasks:
    - name: Créer un instantané avant maintenance
      vergeio.vergeos.vm_snapshot:
        vm_name: "{{ inventory_hostname }}"
        description: "Instantané de maintenance planifiée - {{ ansible_date_time.date }}"
        retention: 172800 # Conservation de 48 heures
        quiesce: true
      delegate_to: localhost
```

### Mise en place de l’infrastructure de tags

Établissez une taxonomie de tags cohérente dans tout votre environnement VergeOS :

```yaml
---
- name: Configurer l’infrastructure de tags
  hosts: localhost
  connection: local

  tasks:
    - name: Créer des catégories de tags
      vergeio.vergeos.tag_category:
        name: "{{ item.name }}"
        description: "{{ item.description }}"
      loop:
        - { name: "Environment", description: "Environnement de déploiement" }
        - { name: "Department", description: "Propriétaire de l’unité commerciale" }
        - { name: "Compliance", description: "Cadre réglementaire" }
        - { name: "Backup", description: "Niveau de politique de sauvegarde" }

    - name: Appliquer des tags d’environnement aux VM
      vergeio.vergeos.tag:
        category: "Environment"
        name: "Production"
        resource_type: "vm"
        resource_name: "{{ item }}"
      loop:
        - "db-server-01"
        - "web-server-01"
        - "app-server-01"
```

### Flux de travail d’importation de VM Windows

Automatisez l’importation de modèles de VM Windows à partir de fichiers OVA :

```yaml
---
- name: Importer un modèle Windows Server
  hosts: localhost
  connection: local

  tasks:
    # Téléversez d’abord win2022-standard.ova dans VergeOS (interface ou API) ;
    # vm_import référence l’OVA existant par nom de fichier ou ID.
    - name: Importer Windows Server 2022 depuis OVA
      vergeio.vergeos.vm_import:
        name: "win2022-template"
        ova_file_name: "win2022-standard.ova"
        preferred_tier: "4"
        override_drive_interface: virtio
        override_nic_interface: virtio

    - name: Marquer le modèle importé
      vergeio.vergeos.tag:
        category: "Environment"
        name: "Template"
        resource_type: "vm"
        resource_name: "win2022-template"
```

## Modèles d’intégration

### Pipeline Terraform + Ansible

Un modèle courant combine Terraform pour le provisionnement et Ansible pour la configuration : Terraform déclare l’infrastructure, Ansible configure ce qui s’exécute à l’intérieur.

```mermaid
flowchart LR
    A["Terraform"] --> B["Provisionner les VM<br/>& les réseaux"]
    B --> C["Inventaire dynamique"]
    C --> D["Ansible"]
    D --> E["Configurer l’OS<br/>Installer les logiciels<br/>Appliquer les politiques"]

    style A fill:#7b42f5,color:#fff
    style D fill:#ee4444,color:#fff
    style C fill:#4a9eff,color:#fff
```

| Phase               | Outil      | Responsabilité                                                                           |
| ------------------- | ---------- | ---------------------------------------------------------------------------------------- |
| **Provisionnement** | Terraform  | Créer des VM, des réseaux, des utilisateurs, des disques                                 |
| **Découverte**      | Inventaire | Interroger l’API VergeOS pour les VM nouvellement créées                                 |
| **Configuration**   | Ansible    | Installer les paquets, configurer les services, appliquer les lignes de base de sécurité |
| **Validation**      | Ansible    | Exécuter des tests de fumée, vérifier la connectivité, contrôler la conformité           |

### SDK Python + Ansible

Pour les flux de travail complexes qui nécessitent une logique programmatique au-delà de ce que proposent les playbooks YAML, combinez le **pyvergeos** SDK Python avec Ansible :

```yaml
- name: Automatisation VergeOS personnalisée avec Python
  hosts: localhost
  tasks:
    - name: Exécuter des opérations avancées sur les VM via pyvergeos
      ansible.builtin.script:
        cmd: scripts/bulk_snapshot.py
      environment:
        VERGEOS_HOST: "{{ vergeos_host }}"
        VERGEOS_USERNAME: "{{ vergeos_user }}"
        VERGEOS_PASSWORD: "{{ vergeos_password }}"
```

### Intégration CI/CD

Les playbooks Ansible s’intègrent naturellement dans les pipelines CI/CD pour l’automatisation de l’infrastructure :

### GitLab CI

Déclenchez des playbooks Ansible depuis `.gitlab-ci.yml` les étapes pour le provisionnement et la configuration automatisés des VM lors d’une fusion vers main.

### Jenkins

Utilisez le plugin Ansible pour Jenkins afin d’exécuter des playbooks comme étapes de build, avec des identifiants gérés via le Jenkins Credential Store.

### GitHub Actions

Exécutez des playbooks Ansible dans les workflows GitHub Actions à l’aide de l’action `ansible-playbook` pour les changements d’infrastructure pilotés par les pull requests.

### AWX / Tower

Déployez Ansible AWX pour une interface web, le RBAC et l’exécution planifiée de playbooks sur les environnements VergeOS.

## Bonnes pratiques

### Gestion des identifiants

* **Ne codifiez jamais en dur les identifiants** dans les playbooks ou les fichiers d’inventaire — utilisez des variables d’environnement ou Ansible Vault
* **Utilisez des clés API** pour les comptes de service en production — elles prennent en charge les listes d’autorisation IP et les dates d’expiration
* **Faites tourner les identifiants** régulièrement et auditez l’utilisation des clés API via l’interface VergeOS

### Stratégie d’inventaire

* **Activez la mise en cache** pour les grands environnements afin de réduire les appels API et d’accélérer l’exécution des playbooks
* **Utilisez des filtres** pour restreindre l’inventaire aux VM pertinentes — évitez de récupérer tout l’environnement
* **Inventaires séparés** par environnement (dev, préproduction, production) pour plus de sécurité

### Conception des playbooks

* **Utilisez `delegate_to: localhost`** pour les appels à l’API VergeOS — les modules communiquent avec l’API, pas avec les VM invitées via SSH
* **Exploitez les tags** pour le ciblage — ils fournissent un système de regroupement flexible et multidimensionnel
* **Implémentez l’idempotence** — concevez des playbooks pouvant être réexécutés en toute sécurité sans effets secondaires

{% hint style="info" %}
**Vous venez de VMware ?**

Le `vergeio.vergeos` La collection suit le modèle Ansible standard que vous connaissez déjà : des modules pilotés par API pour les opérations sur les ressources, plus un plugin d’inventaire dynamique pour la découverte des hôtes. Une seule configuration d’inventaire peut interroger plusieurs sites VergeOS à la fois — sans jongler avec des connexions par site.
{% endhint %}

{% hint style="info" %}
**Vous venez de Nutanix ?**

Le `vergeio.vergeos` La collection suit le modèle Ansible standard : des modules pilotés par API, plus un plugin d’inventaire dynamique. Une seule configuration d’inventaire peut cibler simultanément plusieurs sites VergeOS, sans nécessiter de plan de gestion central.
{% endhint %}

## Lectures complémentaires

* [Ansible Collection — GitHub](https://github.com/verge-io/ansible-collection-vergeos)
* [Ansible Galaxy — vergeio.vergeos](https://galaxy.ansible.com/vergeio/vergeos)
* [SDK Python pyvergeos — PyPI](https://pypi.org/project/pyvergeos/)
* [Documentation VergeOS — SDK Python](https://docs.verge.io/automate-protect-and-extend/fr/integrations-et-api/python-sdk.md)
* [Documentation Ansible](https://docs.ansible.com/)


---

# 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/05-ansible.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.
