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

# Collection Ansible

Ansible apporte une automatisation sans agent et à base de push pour la gestion de l’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 balises, d’importer des images de VM et de découvrir dynamiquement l’infrastructure sur plusieurs sites — le tout via des playbooks YAML familiers.

## Présentation de la collection

La collection Ansible VergeOS est publiée sur Ansible Galaxy et s’intègre directement à l’API REST de VergeOS via **pyvergeos** le 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, ce qui permet 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, la gestion des balises 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` le 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 changement et les workflows 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 invité
```

### Modules de gestion des balises

Les balises fournissent un système de classification flexible pour organiser les ressources VergeOS. La collection inclut deux modules pour la gestion des balises :

| Module                             | Rôle                                                                                   |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| **`vergeio.vergeos.tag_category`** | Créer et gérer des catégories de balises (par exemple, "Environnement", "Département") |
| **`vergeio.vergeos.tag`**          | Appliquer et gérer des balises individuelles au sein des catégories                    |

```yaml
- name: Créer une catégorie de balises 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` le module référence un OVA existant par nom ou 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 — supprimant 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 **pas** définit `ansible_host` et ne prend pas en charge les connexions SSH directes nativement. Vous devez configurer `ansible_host` via les variables d’hôte, les règles de composition ou une stratégie de connexion distincte pour l’exécution des playbooks basée sur SSH.
{% endhint %}

### Configuration de l’inventaire

Créez un fichier d’inventaire (par exemple, `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
```

### Regroupement 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 balises"]
    B --> F["Par tenant"]
    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 | Exemples de groupes                      | Cas d’utilisation                                      |
| ------------------- | ---------------------------------------- | ------------------------------------------------------ |
| **Site**            | `datacenter_east`, `datacenter_west`     | Cibler les playbooks vers des emplacements spécifiques |
| **Statut**          | `status_running`, `status_stopped`       | Exécuter les tâches uniquement sur les VM actives      |
| **Balises**         | `tag_Production`, `tag_Development`      | Configuration spécifique à l’environnement             |
| **Tenant**          | `tenant_acme`, `tenant_globex`           | Automatisation multi-locataire                         |
| **Famille d’OS**    | `os_linux`, `os_windows`                 | Playbooks spécifiques au système d’exploitation        |
| **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, ses cœurs CPU, sa RAM, sa famille d’OS, son état d’alimentation, son affectation au cluster, son emplacement sur le nœud, sa configuration réseau, ses balises et l’ensemble du dictionnaire de 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 par balises avec l’inventaire dynamique pour orchestrer des instantanés sur plusieurs sites :

```yaml
---
- name: Prendre un instantané de toutes les bases de données de production sur 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 # Rétention de 48 heures
        quiesce: true
      delegate_to: localhost
```

### Mise en place du marquage des infrastructures

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

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

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

    - name: Appliquer des balises 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 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 vers 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 schéma courant combine Terraform pour le provisionnement et Ansible pour la configuration : Terraform déclare l’infrastructure, Ansible configure ce qui s’y exécute.

```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, réseaux, utilisateurs, disques                                    |
| **Découverte**      | Inventaire | Interroger l’API VergeOS pour les nouvelles VM créées                           |
| **Configuration**   | Ansible    | Installer les paquets, configurer les services, appliquer les bases 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 workflows 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éclencher des playbooks Ansible depuis `.gitlab-ci.yml` des é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 `ansible-playbook` pour les changements d’infrastructure déclenchés par les pull requests.

### AWX / Tower

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

## Bonnes pratiques

### Gestion des identifiants

* **Ne codez 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’IP autorisées 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 les exécutions de playbooks
* **Utilisez des filtres** pour limiter l’inventaire aux VM pertinentes — évitez de récupérer l’ensemble de l’environnement
* **Inventaires séparés** par environnement (dev, staging, 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
* **Tirez parti des balises** pour le ciblage — elles offrent un système de regroupement flexible et multidimensionnel
* **Implémentez l’idempotence** — concevez des playbooks pouvant être relancés sans danger et sans effets de bord

{% 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 l’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 jonglage de 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 l’API plus un plugin d’inventaire dynamique. Une configuration d’inventaire peut cibler plusieurs sites VergeOS simultanément, sans plane de gestion central requis.
{% endhint %}

## Lectures complémentaires

* [Collection Ansible — 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/product-guide/tools-integrations/python-sdk/)
* [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 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/learn-the-platform/fr/module-8-developpeur-et-devops/05-ansible.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.