Colección de Ansible

Automatiza la infraestructura de VergeOS con la colección Ansible vergeio.vergeos: módulos para instantáneas de VM, etiquetado e importaciones, además de un complemento de inventario dinámico para entornos multisitio.

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

Instalación

Instala la colección desde Ansible Galaxy:

# 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:

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:

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.

- 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

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

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.

Configuración del inventario

Crea un archivo de inventario (por ejemplo, vergeos_inventory.yml):

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:

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:

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

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

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

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:

- 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

¿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.

¿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.

Lecturas adicionales

• Colección de Ansible — GitHub
• Ansible Galaxy — vergeio.vergeos
• SDK de Python pyvergeos — PyPI
• Documentación de VergeOS — SDK de Python
• Documentación de Ansible