Recetas y el Marketplace

Aprovisionamiento estandarizado de VM con plantillas de imagen dorada, el catálogo del Marketplace, integración con cloud-init/Cloudbase-init y creación de recetas personalizadas en VergeOS.

Resumen

Configurar manualmente cada máquina virtual desde cero requiere mucho tiempo y es propenso a errores. VergeOS recetas resuelve esto proporcionando plantillas de imagen dorada personalizables que estandarizan el aprovisionamiento de VMs y, al mismo tiempo, permiten la personalización por instancia. Combinado con el catálogo de Marketplace, las recetas te permiten desplegar VMs listas para producción en minutos -- desde servidores Ubuntu hasta entornos de evaluación de Windows -- con configuraciones coherentes en todo momento.

Una receta consta de tres componentes:

1. VM base -- Una máquina virtual generalizada que sirve como imagen dorada (plantilla)
2. Preguntas -- Campos de entrada organizados en secciones que recopilan valores de personalización por instancia (núcleos, RAM, nombre de host, configuración de red, credenciales)
3. Automatización -- Operaciones de base de datos en segundo plano y scripts cloud-init/Cloudbase-init que configuran la VM durante el primer arranque

El catálogo de Marketplace

Cada sistema VergeOS incluye de serie el Marketplace -- un repositorio remoto, proporcionado por VergeOS, de recetas de VM preconstruidas listas para su uso inmediato. Marketplace está disponible automáticamente en el momento de la instalación y sus catálogos están configurados con scope=global, lo que también los hace accesibles a todos los inquilinos.

Acceder al Marketplace

1. Vaya a Máquinas > Máquinas virtuales desde el menú de la izquierda.
2. Haga clic en Nuevo.
3. En el Seleccionar tipo panel de la izquierda, elige Marketplace (o un catálogo específico como "Sistemas operativos (Marketplace)" o "Aplicaciones (Marketplace)").
4. Selecciona una receta de la lista y haz clic en Siguiente para comenzar a responder preguntas.

Recetas de sistemas operativos disponibles

El Marketplace incluye recetas para una amplia gama de sistemas operativos:

Categoría	Recetas disponibles
Ubuntu	Server 18.04 (Bionic), 20.04 (Focal), 22.04 (Jammy), 24.04 (Noble) -- versiones LTS
Compatible con RHEL	Rocky Linux 8 y 9, AlmaLinux 8 y 9, CentOS 7, CentOS Stream 8
Debian	Debian 10 (Buster), 11 (Bullseye), 12 (Bookworm), 13 (Trixie)
Fedora	Fedora 35, 36, 37, 38
Amazon	Amazon Linux 2 LTS
Windows	Windows Server 2019 Evaluation, 2022 Evaluation, 2025 Evaluation

Las recetas Linux usan cloud-init con imágenes en la nube preconstruidas descargadas durante el aprovisionamiento. Las recetas de Windows usan Cloudbase-init con ISOs de evaluación y una instalación desatendida automatizada. Ambos enfoques producen una VM completamente configurada y arrancable sin instalación manual del sistema operativo.

Uso de una receta de Marketplace

Desplegar una VM desde una receta de Marketplace sigue un flujo guiado de preguntas y respuestas. Aquí tienes un recorrido típico usando una receta de Ubuntu Server:

Recorrido paso a paso

1. Navega a Máquinas > Máquinas virtuales > Nuevo.
2. Selecciona hasta la receta (por ejemplo, "Ubuntu Server 24.04 (Noble Numbat)") desde el catálogo de Marketplace.
3. Responde las preguntas presentadas en cada sección:

Configuración de la instancia de VM

Variable	Nombre para mostrar	Descripción
YB_CPU_CORES	Núcleos	Número de núcleos de CPU virtuales
YB_RAM	RAM	Asignación de memoria (MB)
YB_HOSTNAME	Nombre de host	Nombre de host del sistema operativo invitado
SELECT_CREATE_UEFI	Habilitar UEFI	Modo de arranque UEFI (recomendado)
YB_DISABLE_CLOUDINIT	Deshabilitar Cloud-init después del primer arranque	Opciones: true, false, o purge

Configuración de red

Variable	Nombre para mostrar	Descripción
YB_IP_ADDR_TYPE	Tipo de dirección IP	dhcp o static
YB_NIC_ETH0_EXTERNAL_GATEWAY	Red	Red de destino para la NIC principal
YB_NIC_ETH0_IP_ADDR	Dirección IP	IP estática (si se seleccionó static)
YB_NIC_ETH0_CIDR	CIDR de máscara de subred	p. ej., /24
YB_NIC_ETH0_GW	Puerta de enlace predeterminada	Dirección IP de la puerta de enlace
YB_NIC_ETH0_NS	Servidores de nombres	Servidores DNS separados por comas

Configuración de almacenamiento

Variable	Nombre para mostrar	Descripción
YB_DRIVE_OS_SIZE	Tamaño de la unidad del sistema operativo	Tamaño del disco en GB
SELECT_OS_TIER	Nivel de la unidad del sistema operativo	Nivel de almacenamiento vSAN preferido

Cuenta de usuario

Variable	Nombre para mostrar	Descripción
YB_USER	Nombre de usuario	Nombre de usuario del administrador inicial
YB_PASSWORD	Contraseña	Contraseña del administrador inicial

1. Haz clic en Enviar para crear la VM.
2. La automatización de la receta se ejecuta -- creando unidades, descargando imágenes en la nube, configurando archivos cloud-init y estableciendo el tipo de máquina.
3. Enciende la VM. Cloud-init se ejecuta en el primer arranque para aplicar tu configuración (nombre de host, usuarios, red, paquetes).

Preguntas y variables de la receta

Las preguntas de la receta son los bloques de construcción que hacen que las recetas sean personalizables. Cada pregunta captura un valor que se almacena como una variable y puede ser referenciado en scripts cloud-init, operaciones de base de datos o configuración de la VM.

Campos de pregunta

Campo	Propósito
Sección	Agrupa preguntas relacionadas en el formulario de entrada (por ejemplo, "Configuración de la instancia", "Red")
Nombre	Nombre de variable referenciado en scripts (solo alfanumérico, sin espacios)
Tipo	Cómo se recopilan los datos; los tipos comunes incluyen String, Number, Password, Boolean, List, Hidden, RAM, Disk Size, Network, Cluster, Database Create/Edit/Find, Hostname, Script, Textarea, Virtual IP, Timestamp, Row, Field y Seconds
Orden	Orden de visualización dentro de la sección
Mostrar	Etiqueta mostrada al usuario en el formulario de entrada
Valor predeterminado	Respuesta precargada
Validación mediante regex	Expresión regular para validar la entrada
Texto de marcador de posición	Texto de ayuda atenuado que muestra el formato esperado
Texto de ayuda emergente	Ayuda emergente al pasar el cursor
Texto de nota	Texto de ayuda mostrado debajo del campo de entrada
Al cambiar	JavaScript para mostrar/ocultar otras preguntas de forma dinámica

Preguntas generadas automáticamente

Cuando creas una receta a partir de una VM base, VergeOS genera automáticamente preguntas para cada una de las unidades de la VM (por ejemplo, YB_DRIVE_1_SIZE, YB_DRIVE_2_SERIAL, YB_DRIVE_3_NONPERSISTENT). Algunas preguntas generadas automáticamente están deshabilitadas de forma predeterminada -- actívalas desde la lista de Preguntas si es necesario.

Automatización de bases de datos

Detrás de cada receta de Marketplace, un conjunto de preguntas de tipo Base de datos (Database Create, Database Edit y Database Find) realiza operaciones automatizadas durante el aprovisionamiento de la VM. Estas preguntas interactúan directamente con la API de base de datos de VergeOS para crear recursos, descargar imágenes y configurar hardware -- sin requerir ninguna intervención manual del usuario.

Operaciones de base de datos comunes

Variable	Operación
CREATE_OS_DRIVE	Crea el disco virtual del sistema operativo con el tamaño y nivel especificados
YB_DOWNLOAD_WINDOWS_ISO	Descarga la ISO de Windows desde una URL especificada
YB_DOWNLOAD_VIRTIO	Descarga la ISO del controlador VirtIO para invitados Windows
YB_CREATE_VIRTIO_CD_DL	Crea un CD-ROM virtual y adjunta la ISO de VirtIO
GET_CLUSTER_CPU	Consulta el clúster para obtener información disponible sobre el modelo de CPU
CHANGE_CLUSTER_CPU	Establece el tipo de CPU de la VM para que coincida con el clúster
EDIT_MACHINE_TYPE	Ajusta el tipo de máquina de la VM (por ejemplo, Q35) después de la creación

Estas operaciones usan la misma API REST que está disponible para administradores y herramientas de automatización. Los autores de recetas pueden añadir preguntas de Base de datos personalizadas para automatizar cualquier operación expuesta por la API de VergeOS -- creando redes, registrando entradas DNS, estableciendo reglas de firewall y mucho más.

¿Vienes de VMware o Nutanix?

Una receta de VergeOS agrupa la plantilla, el formulario de personalización por instancia y la automatización de aprovisionamiento -- cloud-init/Cloudbase-init, creación de unidades, operaciones de API -- en un solo paquete autocontenido, por lo que no necesitas ensamblar por separado herramientas de plantillas, personalización, gestión de imágenes y orquestación para aprovisionar una VM.

Integración con Cloud-Init (Linux)

VergeOS se integra con cloud-init, la herramienta estándar de la industria para personalizar VMs Linux durante el primer arranque. Las recetas aprovechan cloud-init para aplicar el nombre de host, las cuentas de usuario, la configuración de red, la instalación de paquetes y scripts personalizados -- todo impulsado por las variables de preguntas de la receta.

Cómo funciona

1. El campo Fuente de datos de Cloud-init de la VM se establece en Config Drive v2.
2. VergeOS crea una unidad virtual que contiene dos archivos:

   • user_data -- Scripts e instrucciones de configuración ejecutados en el primer arranque
   • meta_data.json -- Metadatos de la instancia (nombre de host, UUID, zona de disponibilidad)
3. Las variables de las preguntas de la receta se sustituyen en estos archivos mediante sintaxis de plantilla.
4. En el primer arranque, cloud-init lee el Config Drive y aplica la configuración.

La campo Fuente de datos de Cloud-init campo ofrece más de una opción. Las recetas de Marketplace usan Config Drive v2 (la fuente de datos estándar de cloud-init), pero VergeOS también admite:

• Ninguna — Cloud-init deshabilitado para la VM.
• NoCloud — una fuente de datos estándar de cloud-init pensada para configurar una VM sin conexión de red.

Ambos Config Drive v2 y NoCloud proporcionan los mismos user_data / meta_data archivos al invitado; elige NoCloud cuando el invitado no tiene red durante el primer arranque.

Variables de plantilla

Las variables de la receta se inyectan en los archivos cloud-init usando la ${VARIABLE_NAME} sintaxis:

{
  "availability_zone": "${YB_CLUSTER_NAME}",
  "name": "${YB_NAME}",
  "uuid": "${YB_UUID}",
  "hostname": "${YB_NAME}",
  "yb": ${$ALL_VARIABLES}
}

La ${$ALL_VARIABLES} se expande para incluir cada variable de pregunta como un objeto JSON, haciendo que todas las respuestas de la receta estén disponibles para los scripts cloud-init. El ${$...} formulario no es un error tipográfico: el motor de sustitución busca la ${...} sintaxis estándar, y $ALL_VARIABLES es un nombre de variable especial (con un $$ inicial literal) que el renderizador reconoce y reemplaza con el conjunto completo de variables.

Formatos de datos de usuario

La user_data archivo admite múltiples formatos de script, determinados por la primera línea:

Formato	Primera línea	Caso de uso
Cloud-config (YAML)	#cloud-config	Configuración declarativa (usuarios, paquetes, archivos, runcmd)
Script de shell	#!/bin/bash	Comandos de shell arbitrarios
PowerShell	#ps1	Scripts de PowerShell (principalmente para Cloudbase-init en Windows)
Batch	rem cmd	Scripts por lotes de Windows (Cloudbase-init)

El despachador de primera línea anterior es un comportamiento estándar de cloud-init/Cloudbase-init, no una convención específica de VergeOS -- VergeOS solo entrega el user_data archivo a través de Config Drive v2 y deja que el agente dentro del invitado lo interprete.

Ejemplo: Cloud-Config YAML

#cloud-config
hostname: ${YB_HOSTNAME}
users:
  - name: ${YB_USER}
    sudo: ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash
    lock_passwd: false
    passwd: ${YB_PASSWORD_HASH}
packages:
  - qemu-guest-agent
  - curl
runcmd:
  - systemctl enable --now qemu-guest-agent

Imágenes en la nube en línea

Las recetas Linux pueden descargar imágenes en la nube preconstruidas directamente desde los espejos de distribución. Esto se configura mediante preguntas ocultas de la receta:

• OS_DL_URL (tipo: Hidden) -- Descarga y almacena la imagen en caché localmente (por ejemplo, https://cloud-images.ubuntu.com/releases/noble/release/ubuntu-24.04-server-cloudimg-amd64-disk-kvm.img)
• OS_URL (tipo: Hidden) -- Transmite la imagen por la web sin almacenamiento en caché local

Estas imágenes en la nube vienen con cloud-init preinstalado, por lo que la receta solo necesita proporcionar los user_data y meta_data.json archivos para la personalización.

Cloudbase-Init (Windows)

Para las VMs de Windows, VergeOS usa Cloudbase-init -- el equivalente de cloud-init en Windows. Cloudbase-init lee la misma fuente de datos Config Drive v2 y ejecuta scripts de PowerShell o por lotes durante el primer arranque.

Proceso de configuración

1. Instala el cliente Cloudbase-init en la VM plantilla de Windows.
2. Ejecuta Sysprep en la VM usando las opciones unattended de Cloudbase-init.
3. Establece el campo Fuente de datos de Cloud-init a Config Drive v2.
4. de la VM. Crea preguntas de receta para opciones específicas de Windows (clave de licencia, RDP, controladores VirtIO).

Automatización de recetas de Windows

Las recetas de Marketplace para Windows automatizan toda la cadena de aprovisionamiento:

1. Descargar la ISO de evaluación de Windows mediante una pregunta de Base de datos
2. Descargar la ISO del controlador VirtIO
3. Crear unidades de CD-ROM virtuales y adjuntar ambas ISOs
4. Configurar el tipo de máquina y los ajustes de UEFI
5. En el primer arranque, Cloudbase-init aplica el nombre de host, las credenciales de administrador, la configuración de RDP y la configuración de red

Después de que cloud-init o Cloudbase-init hayan completado su trabajo, elimina los archivos de cloud-init de la VM -- especialmente si algún script contenía contraseñas u otra información sensible.

Crear recetas personalizadas

Cuando las recetas de Marketplace no satisfacen tus necesidades, puedes crear recetas personalizadas a partir de cualquier VM existente.

Flujo de trabajo

1. Construye una VM base -- Instala el sistema operativo, las aplicaciones y la configuración que quieras como tu imagen dorada. Generaliza la VM (elimina datos específicos de la máquina, instala cloud-init o Cloudbase-init).
2. Crea la receta -- Navega a Máquinas virtuales > Nueva receta de VM.

   • Si no existe un catálogo local, se te pedirá que crees uno primero.
3. Configura los campos de la receta:

Campo	Descripción
Nombre	Nombre descriptivo para la receta
Descripción	Documentación y directrices
Icono	Icono de Font Awesome para identificación visual
Catálogo	Contenedor organizativo para la receta
Máquina virtual	La VM plantilla base
Versión	Comienza en 1.0.0, se incrementa automáticamente con los cambios (1.0.0-1, 1.0.0-2, etc.)
Usar activo para los nombres de las preguntas	Nombra las preguntas de unidad/NIC por número de activo en lugar de por orden
Dependencias de versión	Funciones de VergeOS requeridas para que la receta funcione

1. Definir preguntas -- Añade secciones y preguntas para recopilar la entrada por instancia. Configura validación, valores predeterminados, información sobre herramientas y lógica condicional de mostrar/ocultar.
2. Configurar archivos cloud-init -- Escribe user_data y meta_data.json plantillas que hagan referencia a las variables de tus preguntas.
3. Simula la receta -- Haz clic en Simular receta desde el panel de la receta para probar el formulario de entrada, validar los campos y previsualizar los archivos de respuesta generados.
4. Publicar -- La receta se vuelve disponible en su catálogo para crear nuevas VM.

Modificación y republicación

Cuando cambias una receta, debe ser republicada para que los cambios surtan efecto. El panel de la receta muestra una notificación con un Republicar enlace. Después de republicarla, se notifica a los sistemas remotos y a los inquilinos que hay una actualización disponible.

Instancias de receta

Una VM creada a partir de una receta es una instancia de esa receta hasta que se elimine o se desconecte. Puedes ver todas las instancias desde el panel de la receta. Una receta no se puede eliminar mientras tenga instancias asociadas.

Límites documentados

Un sistema VergeOS admite hasta 1.000 recetas y 50.000 instancias de receta en total, con hasta 10.000 registros de receta por receta (se depuran automáticamente al llegar a 100 y caducan después de 7 días). Estos límites están muy por encima del uso típico, pero conviene conocerlos si planeas un aprovisionamiento a gran escala impulsado por recetas.

Intercambio de recetas

VergeOS admite compartir recetas entre sistemas y inquilinos mediante una arquitectura de repositorio y catálogo.

Compartir con inquilinos

1. Configura el ámbito de publicación a Inquilino (o Global para acceso externo).
2. En la interfaz de usuario del inquilino, navega hasta el proveedor de servicios repositorio y haz clic en Actualizar.
3. Haz doble clic en el catálogo para explorar las recetas.
4. Selecciona las recetas y haz clic en Descargar/Actualizar para ponerlas disponibles localmente.

Compartir con sistemas remotos

1. Crea un usuario de API en el sistema compartido con permisos de Listar y Leer sobre el catálogo.
2. En el sistema receptor, crea un Repositorio remoto que apunte a la URL del sistema compartido con las credenciales del usuario de API.
3. Haga clic en Actualizar para obtener los listados del catálogo. Descarga las recetas para uso local.

Ámbitos de publicación

Ámbito	Visibilidad
Privado	Solo la nube local de VergeOS
Ninguna	Deshabilitado -- no disponible en ningún lugar
Inquilino	La nube local y sus inquilinos directos
Global	La nube local, los inquilinos y los sistemas remotos (con credenciales)

Prácticas recomendadas

Comienza con Marketplace

Usa las recetas de Marketplace como punto de partida. Clónalas en un catálogo local y personalízalas en lugar de crear desde cero -- esto ahorra tiempo y garantiza que heredes configuraciones probadas.

Simula antes de publicar

Simula siempre una receta antes de ponerla a disposición de los usuarios. Verifica que la validación de campos funcione, que la lógica condicional se comporte correctamente y que los archivos cloud-init generados contengan los valores esperados.

Versiona tus recetas

Usa números de versión significativos y actualízalos al hacer cambios importantes. Los sistemas remotos y los inquilinos reciben notificaciones de las actualizaciones, así que una versionación clara ayuda a seguir qué ha cambiado.

Limpia los datos sensibles

Elimina los archivos cloud-init después del primer arranque, especialmente si contienen contraseñas o credenciales. Considera usar la YB_DISABLE_CLOUDINIT opción para purgar los datos de cloud-init después de la configuración inicial.