> 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/es/modulo-8-desarrollador-y-devops/05-ansible.md).

# Colección de Ansible

Ansible aporta automatización sin agentes y basada en push para la gestión de infraestructuras. La **vergeio.vergeos** La colección de Ansible amplía Ansible con módulos diseñados específicamente y un complemento de inventario para VergeOS, lo que te permite gestionar instantáneas de VM, organizar recursos con etiquetas, importar imágenes de VM y descubrir dinámicamente la infraestructura en varios sitios, todo ello mediante playbooks YAML conocidos.

## Resumen de la colección

La colección VergeOS para Ansible se publica en Ansible Galaxy y se integra directamente con la API REST de VergeOS a través de **pyvergeos** SDK de Python.

| Detalle                 | Valor                                                            |
| ----------------------- | ---------------------------------------------------------------- |
| **Espacio de nombres**  | `vergeio`                                                        |
| **Colección**           | `vergeos`                                                        |
| **Referencia completa** | `vergeio.vergeos`                                                |
| **Python**              | >= 3.9                                                           |
| **Ansible**             | >= 2.14.0                                                        |
| **Dependencia del SDK** | `pyvergeos` >= 1.0.1                                             |
| **Fuente**              | [GitHub](https://github.com/verge-io/ansible-collection-vergeos) |

### Instalación

Instala la colección desde Ansible Galaxy:

```bash
# Instalar desde Galaxy (recomendado)
ansible-galaxy collection install vergeio.vergeos

# Instalar el SDK de Python requerido
pip install pyvergeos
```

Para entornos de desarrollo o sin conexión, compila e instala desde el código fuente:

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

### Autenticación

La colección utiliza variables de entorno para la autenticación de la API, manteniendo las credenciales fuera de tus playbooks y archivos de inventario:

```bash
export VERGEOS_HOST="https://vergeos.example.com"
export VERGEOS_USERNAME="admin"
export VERGEOS_PASSWORD="tu-contraseña"
export VERGEOS_INSECURE="true"   # Establece true para certificados SSL autofirmados
```

Como alternativa, puedes usar autenticación con clave API para escenarios no interactivos como canalizaciones de CI/CD. Las claves API se crean en **Sistema > Usuarios > \[seleccionar usuario] > Claves API** dentro de la interfaz de VergeOS y proporcionan autenticación mediante token Bearer sin requerir credenciales de usuario/contraseña.

## Módulos

La colección proporciona módulos para operaciones del ciclo de vida de las VM, etiquetado y gestión de imágenes. Cada módulo se comunica con la API de VergeOS a través del SDK pyvergeos.

### Módulo de instantáneas de VM

La `vergeio.vergeos.vm_snapshot` el módulo crea y administra instantáneas de VM de forma programática, útil para la automatización de copias de seguridad, puntos de control previos a cambios y flujos de trabajo de recuperación ante desastres.

```yaml
- name: Crear una instantánea del servidor de base de datos
  vergeio.vergeos.vm_snapshot:
    vm_name: "db-server-01"
    description: "Instantánea previa a la actualización"
    retention: 86400 # Conservar durante 24 horas (segundos)
    quiesce: true # Congelar el sistema de archivos del invitado
```

### Módulos de gestión de etiquetas

Las etiquetas proporcionan un sistema de clasificación flexible para organizar los recursos de VergeOS. La colección incluye dos módulos para la gestión de etiquetas:

| Módulo                             | Propósito                                                                            |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| **`vergeio.vergeos.tag_category`** | Crear y administrar categorías de etiquetas (por ejemplo, "Entorno", "Departamento") |
| **`vergeio.vergeos.tag`**          | Aplicar y administrar etiquetas individuales dentro de las categorías                |

```yaml
- name: Crear categoría de etiqueta de entorno
  vergeio.vergeos.tag_category:
    name: "Entorno"
    description: "Clasificación del entorno de implementación"

- name: Etiquetar la VM como producción
  vergeio.vergeos.tag:
    category: "Entorno"
    name: "Producción"
    resource_type: "vm"
    resource_name: "web-server-01"
```

### Capacidades de importación de VM

La colección despliega VMs desde plantillas OVA que ya se han cargado en VergeOS, la `vm_import` el módulo referencia una OVA existente por nombre o ID, y la CPU y la RAM se toman de la propia OVA. Carga primero la OVA (interfaz o API) y luego ejecuta el playbook para crear la VM.

## Complemento de inventario dinámico

La `vergeos_vms` el complemento de inventario consulta la API de VergeOS para descubrir dinámicamente las VMs y construir el inventario de Ansible, eliminando la necesidad de mantener archivos de hosts estáticos.

{% hint style="warning" %}
**Inventario solo API**

El complemento de inventario recupera metadatos de VM desde la API de VergeOS. No **no** configura `ansible_host` y no admite conexiones SSH directas de forma nativa. Debes configurar `ansible_host` mediante variables de host, reglas compose o una estrategia de conexión separada para la ejecución de playbooks basada en SSH.
{% endhint %}

### Configuración del inventario

Crea un archivo de inventario (por ejemplo, `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

# Filtros opcionales
filters:
  status: "running"
  name_pattern: "prod-*"

# Habilitar caché para entornos grandes
cache: true
cache_plugin: jsonfile
cache_connection: /tmp/vergeos_inventory_cache
cache_timeout: 300
```

### Agrupación automática

El complemento organiza automáticamente las VMs descubiertas en grupos según múltiples dimensiones:

```mermaid
flowchart TD
    A["API de VergeOS"] --> B["Complemento vergeos_vms"]
    B --> C["Por sitio"]
    B --> D["Por estado"]
    B --> E["Por etiquetas"]
    B --> F["Por inquilino"]
    B --> G["Por familia de SO"]
    B --> H["Por clúster"]
    B --> I["Por nodo"]

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

| Dimensión del grupo | Grupos de ejemplo                        | Caso de uso                                 |
| ------------------- | ---------------------------------------- | ------------------------------------------- |
| **Sitio**           | `datacenter_east`, `datacenter_west`     | Dirige playbooks a ubicaciones específicas  |
| **Estado**          | `status_running`, `status_stopped`       | Ejecuta tareas solo en VMs activas          |
| **Etiquetas**       | `tag_Production`, `tag_Development`      | Configuración específica del entorno        |
| **Inquilino**       | `tenant_acme`, `tenant_globex`           | Automatización multiinquilino               |
| **Familia de SO**   | `os_linux`, `os_windows`                 | Playbooks específicos del sistema operativo |
| **Clúster**         | `cluster_compute01`, `cluster_compute02` | Mantenimiento consciente del clúster        |
| **Nodo**            | `node_node1`, `node_node2`               | Operaciones a nivel de nodo                 |

### Variables de host

Cada VM descubierta expone más de 20 variables de host, incluidos el ID de la VM, el nombre, los núcleos de CPU, la RAM, la familia de SO, el estado de energía, la asignación de clúster, la ubicación del nodo, la configuración de red, las etiquetas y todo el diccionario de datos de la VM para casos de uso avanzados.

## Patrones de playbook

### Orquestación de instantáneas en varios sitios

Usa el filtrado basado en etiquetas con el inventario dinámico para orquestar instantáneas entre sitios:

```yaml
---
- name: Crear instantánea de todas las bases de datos de producción en todos los sitios
  hosts: tag_Production:&os_linux
  gather_facts: false

  tasks:
    - name: Crear instantánea previa al mantenimiento
      vergeio.vergeos.vm_snapshot:
        vm_name: "{{ inventory_hostname }}"
        description: "Instantánea de mantenimiento programado - {{ ansible_date_time.date }}"
        retention: 172800 # Retención de 48 horas
        quiesce: true
      delegate_to: localhost
```

### Configuración de la infraestructura de etiquetas

Establece una taxonomía de etiquetado coherente en todo tu entorno VergeOS:

```yaml
---
- name: Configurar la infraestructura de etiquetas
  hosts: localhost
  connection: local

  tasks:
    - name: Crear categorías de etiquetas
      vergeio.vergeos.tag_category:
        name: "{{ item.name }}"
        description: "{{ item.description }}"
      loop:
        - { name: "Entorno", description: "Entorno de implementación" }
        - { name: "Departamento", description: "Propietario de la unidad de negocio" }
        - { name: "Cumplimiento", description: "Marco regulatorio" }
        - { name: "Copia de seguridad", description: "Nivel de política de copias de seguridad" }

    - name: Aplicar etiquetas de entorno a las VMs
      vergeio.vergeos.tag:
        category: "Entorno"
        name: "Producción"
        resource_type: "vm"
        resource_name: "{{ item }}"
      loop:
        - "db-server-01"
        - "web-server-01"
        - "app-server-01"
```

### Flujo de trabajo de importación de VM de Windows

Automatiza la importación de plantillas de VM de Windows desde archivos OVA:

```yaml
---
- name: Importar plantilla de Windows Server
  hosts: localhost
  connection: local

  tasks:
    # Carga primero win2022-standard.ova en VergeOS (interfaz o API);
    # vm_import hace referencia a la OVA existente por nombre de archivo o ID.
    - name: Importar Windows Server 2022 desde 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: Etiquetar la plantilla importada
      vergeio.vergeos.tag:
        category: "Entorno"
        name: "Plantilla"
        resource_type: "vm"
        resource_name: "win2022-template"
```

## Patrones de integración

### Canalización de Terraform + Ansible

Un patrón común combina Terraform para el aprovisionamiento con Ansible para la configuración: Terraform declara la infraestructura, Ansible configura lo que se ejecuta dentro de ella.

```mermaid
flowchart LR
    A["Terraform"] --> B["Aprovisionar VMs<br/>y redes"]
    B --> C["Inventario dinámico"]
    C --> D["Ansible"]
    D --> E["Configurar SO<br/>Instalar software<br/>Aplicar políticas"]

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

| Fase                  | Herramienta | Responsabilidad                                                           |
| --------------------- | ----------- | ------------------------------------------------------------------------- |
| **Aprovisionamiento** | Terraform   | Crear VMs, redes, usuarios, discos                                        |
| **Descubrimiento**    | Inventario  | Consultar la API de VergeOS para las VMs recién creadas                   |
| **Configuración**     | Ansible     | Instalar paquetes, configurar servicios, aplicar líneas base de seguridad |
| **Validación**        | Ansible     | Ejecutar pruebas de humo, verificar conectividad, comprobar cumplimiento  |

### SDK de Python + Ansible

Para flujos de trabajo complejos que necesitan lógica programática más allá de lo que ofrecen los playbooks YAML, combina el **pyvergeos** SDK de Python con Ansible:

```yaml
- name: Automatización personalizada de VergeOS con Python
  hosts: localhost
  tasks:
    - name: Ejecutar operaciones avanzadas de VM mediante pyvergeos
      ansible.builtin.script:
        cmd: scripts/bulk_snapshot.py
      environment:
        VERGEOS_HOST: "{{ vergeos_host }}"
        VERGEOS_USERNAME: "{{ vergeos_user }}"
        VERGEOS_PASSWORD: "{{ vergeos_password }}"
```

### Integración CI/CD

Los playbooks de Ansible se integran de forma natural en canalizaciones CI/CD para la automatización de infraestructuras:

### GitLab CI

Activa playbooks de Ansible desde `.gitlab-ci.yml` etapas para el aprovisionamiento y la configuración automatizados de VMs al fusionar en main.

### Jenkins

Usa el complemento de Ansible para Jenkins para ejecutar playbooks como pasos de compilación, con credenciales gestionadas a través del almacén de credenciales de Jenkins.

### GitHub Actions

Ejecuta playbooks de Ansible en flujos de trabajo de GitHub Actions usando la `ansible-playbook` acción para cambios de infraestructura impulsados por solicitudes de extracción.

### AWX / Tower

Despliega Ansible AWX para una interfaz web, RBAC y ejecución programada de playbooks contra entornos VergeOS.

## Prácticas recomendadas

### Gestión de credenciales

* **Nunca codifiques credenciales** en playbooks o archivos de inventario; usa variables de entorno o Ansible Vault
* **Usa claves API** para cuentas de servicio en producción; admiten listas de अनुमति IP y fechas de caducidad
* **Rota las credenciales** con regularidad y audita el uso de claves API a través de la interfaz de VergeOS

### Estrategia de inventario

* **Habilita la caché** para entornos grandes a fin de reducir las llamadas a la API y acelerar las ejecuciones de playbooks
* **Usa filtros** para acotar el inventario a las VMs relevantes; evita cargar todo el entorno
* **Inventarios separados** por entorno (desarrollo, preproducción, producción) por seguridad

### Diseño de playbook

* **Usa `delegate_to: localhost`** para llamadas a la API de VergeOS; los módulos hablan con la API, no con las VMs invitadas mediante SSH
* **Aprovecha las etiquetas** para la selección; proporcionan un sistema de agrupación flexible y multidimensional
* **Implementa idempotencia** — diseña playbooks que puedan ejecutarse de nuevo con seguridad sin efectos secundarios

{% hint style="info" %}
**¿Vienes de VMware?**

La `vergeio.vergeos` la colección sigue el patrón estándar de Ansible que ya conoces: módulos impulsados por API para operaciones de recursos, más un complemento de inventario dinámico para el descubrimiento de hosts. Una sola configuración de inventario puede consultar varios sitios de VergeOS a la vez, sin necesidad de gestionar conexiones por sitio.
{% endhint %}

{% hint style="info" %}
**¿Vienes de Nutanix?**

La `vergeio.vergeos` la colección sigue el patrón estándar de Ansible: módulos impulsados por API más un complemento de inventario dinámico. Una configuración de inventario puede dirigirse a varios sitios de VergeOS simultáneamente, sin necesidad de una plataforma de gestión central.
{% endhint %}

## Lecturas adicionales

* [Colección de Ansible — GitHub](https://github.com/verge-io/ansible-collection-vergeos)
* [Ansible Galaxy — vergeio.vergeos](https://galaxy.ansible.com/vergeio/vergeos)
* [SDK de Python pyvergeos — PyPI](https://pypi.org/project/pyvergeos/)
* [Documentación de VergeOS — SDK de Python](https://docs.verge.io/product-guide/tools-integrations/python-sdk/)
* [Documentación de 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/es/modulo-8-desarrollador-y-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.