Welcome to the new VergeOS docs! The legacy docs remain available until they're retired later this year.
Legacy VergeOS Docs
Ctrlk
Verge.ioGitHub repoSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Integración con Rancher

VergeOS se integra con Rancher mediante un controlador de nodo Docker Machine y una extensión de la interfaz de usuario, lo que permite el aprovisionamiento y la administración de clústeres RKE2/K3s en VergeOS desde la interfaz de Rancher.

Descripción general

VergeOS se integra con Rancher a través de un controlador de nodo Docker Machine y una extensión de interfaz de usuario. Juntos, estos componentes nos permiten aprovisionar y administrar clústeres RKE2/K3s en la infraestructura de VergeOS directamente desde la interfaz de Rancher.

Componente
Propósito

Controlador Docker Machine

Aprovisiona máquinas virtuales de VergeOS como nodos de Kubernetes

Extensión de la interfaz de usuario

Añade a Rancher las credenciales en la nube y la configuración de máquina de VergeOS

Una vez que los clústeres están en ejecución, los Integración con Kubernetes componentes (controlador CSI y administrador del controlador de nube) proporcionan almacenamiento persistente y gestión del ciclo de vida de los nodos; estos funcionan con cualquier clúster de Kubernetes en VergeOS, no solo con los aprovisionados por Rancher.

Requisitos previos

  • Un entorno VergeOS con acceso a la API

  • Una instalación de Rancher Server (v2.10+)

  • Una máquina virtual plantilla con Ubuntu 24.04 y cloud-init instalado

  • Una clave de API de VergeOS (generada en Configuración de usuario)

  • kubectl y helm Herramientas de CLI

Controlador Docker Machine

El controlador Docker Machine es la base de la integración con Rancher. Gestiona todo el ciclo de vida de la VM mediante la API de VergeOS: clona máquinas virtuales plantilla, inyecta claves SSH mediante cloud-init y crea máquinas cuando se aprovisionan clústeres. Cuando se elimina un clúster, el controlador borra automáticamente las VMs que creó.

Cómo funciona

  1. Clona la máquina virtual plantilla con el nombre de máquina solicitado

  2. Configura núcleos de CPU, RAM y cloud-init (claves SSH + nombre de host + user-data opcional)

  3. Redimensiona el disco principal si se especifica un tamaño personalizado

  4. Conecta la VM a la red especificada

  5. Enciende y espera una dirección IP (se prefiere el agente invitado de QEMU, con respaldo a DHCP de la NIC)

Si falla algún paso, el controlador limpia automáticamente la VM creada parcialmente.

Preparación de la máquina virtual plantilla

Antes de aprovisionar clústeres, necesitamos una VM plantilla en VergeOS con lo siguiente:

Obligatorio:

  • Ubuntu 24.04 (Noble Numbat) — por ahora, el único sistema operativo de plantilla compatible

  • cloud-init instalado y habilitado — el controlador inyecta claves SSH y establece el nombre de host mediante una carga útil cloud-init MIME multiparte

Recomendado:

  • agente invitado de QEMU — permite una detección precisa de la IP; sin él, el controlador recurre a las IP de concesión DHCP de la NIC

Detalles específicos de Ubuntu 24.04

El controlador gestiona automáticamente varios aspectos específicos de Ubuntu 24.04 mediante cloud-init:

  • Configuración DHCP de Netplan — escribe una configuración de netplan que coincide con en* interfaces con dhcp4: true, manejando los cambios de nombre de ranura PCI entre clones

  • Regeneración del Machine-ID — regenera /etc/machine-id en cada clon para que cada VM obtenga un identificador de cliente DHCP único

  • Limpieza de concesiones DHCP almacenadas — elimina las concesiones DHCP obsoletas heredadas de la plantilla

Requisitos de memoria

Para uso con Rancher, asigne al menos 4 GB de RAM por nodo (se recomiendan 8 GB). Un clúster RKE2 de un solo nodo con Calico CNI se quedará sin memoria con 2 GB.

Docker no es necesario en la plantilla — Rancher instala su propio tiempo de ejecución de contenedores (containerd) mediante el agente del sistema. La plantilla solo necesita cloud-init y el agente invitado.

Requisitos de red

La red de VergeOS especificada en --vergeos-network debe cumplir los siguientes requisitos para que funcionen los clústeres aprovisionados por Rancher.

Se requiere DHCP

La red debe tener DHCP habilitado. El controlador descubre las IP de los nodos mediante el agente invitado de QEMU, y las VM clonadas no recibirán direcciones sin DHCP.

Conectividad con Rancher

Los nodos deben poder comunicarse con el servidor Rancher, y Rancher debe poder comunicarse con los nodos. Asegúrese de que los siguientes puertos estén abiertos entre ellos:

Para ver la matriz completa de puertos, incluidos los requisitos de nodo a nodo (que varían según el CNI), consulte los requisitos de puertos de Rancher RKE2 .

Dirección
Puerto
Protocolo
Propósito

Nodo → Rancher

443

TCP

Registro y comunicación del agente del sistema

Rancher → Nodo

9345

TCP

Registro del nodo RKE2

Rancher → Nodo

6443

TCP

Servidor de API de Kubernetes

Nodo → Internet

443

TCP

Descargar imágenes de contenedor desde los registros

Instalación en Rancher

El controlador de nodos y la extensión de UI se empaquetan juntos en un único chart de Helm. Esto instala el binario del controlador Docker Machine, registra el recurso NodeDriver e implementa la extensión de UI.

A través de la CLI de Helm:

La vergeosHosts es una lista blanca de nombres de host VergeOS a los que el proxy de Rancher puede acceder. Reemplace vergeos.example.com con el/los nombre(s) de host del/de los entorno(s) VergeOS.

A través de la interfaz de Rancher:

  1. Vaya a Extensiones y haga clic en el ⋮ menú > Administrar repositorios

  2. Agregue un nuevo repositorio con la URL https://verge-io.github.io/helm-charts

  3. Vuelva a Extensiones e instale la Extensión VergeOS Node Driver extensión

Una vez instalado, VergeOS aparecerá como una opción de controlador de nodos al crear clústeres.

Certificados autofirmados

Si el entorno VergeOS usa un certificado autofirmado, establezca inseguro en true al crear la credencial en la nube en Rancher. Esto indica al controlador que omita la verificación TLS al comunicarse con la API de VergeOS.

Uso independiente

El controlador también funciona fuera de Rancher con Docker Machine directamente:

Docker requerido para uso independiente

Cuando se usa como un controlador Docker Machine independiente (no a través de Rancher), la VM plantilla también necesita tener Docker instalado, o podemos usar --vergeos-cloudinit para instalarlo en el primer arranque.

Para ver la lista completa de flags del controlador y variables de entorno, consulte el repositorio del controlador en Documentación y recursos a continuación.

Usuario SSH predeterminado

El controlador usa por defecto root como usuario SSH, pero la extensión de UI de Rancher usa por defecto ubuntu. Cuando use la CLI directamente, establezca --vergeos-ssh-user ubuntu para plantillas Ubuntu.

Extensión de la interfaz de usuario

La extensión de UI agrega componentes específicos de VergeOS a la interfaz de Rancher, proporcionando una experiencia nativa al crear credenciales en la nube y configurar máquinas.

Lo que agrega

Formulario de credencial en la nube — solicita:

  • URL del host VergeOS

  • Clave de API (almacenada como un secreto de Rancher)

  • Conmutador de verificación TLS

Formulario de configuración de máquina — proporciona:

  • Nombre de la VM plantilla (nombre de la VM de VergeOS que se clonará)

  • Nombre de la red (VNet de VergeOS al que conectarse)

  • Entradas para núcleos de CPU, RAM y tamaño de disco

  • Campo de user-data de cloud-init

  • Configuración de usuario SSH y puerto

Compatibilidad

La extensión de UI requiere Rancher v2.10+ y el framework de extensiones de Rancher v3.x.

Instalación

La extensión de UI se instala automáticamente como parte de el chart de Helm combinado. No hay un paso de instalación aparte.

Resumen

La integración con Rancher consta de dos componentes empaquetados en un único chart de Helm:

  • Controlador Docker Machine — clona las VMs plantilla de VergeOS y administra su ciclo de vida para el aprovisionamiento de clústeres

  • Extensión de la interfaz de usuario — añade formularios de credenciales en la nube y de configuración de máquina de VergeOS a la interfaz de Rancher

Juntos, nos permiten aprovisionar clústeres RKE2/K3s en la infraestructura de VergeOS directamente desde la interfaz de Rancher. Una vez que los clústeres están en ejecución, los Integración con Kubernetes componentes gestionan el almacenamiento persistente y el ciclo de vida de los nodos.

Siguientes pasos

  • Prepare una VM plantilla (Ubuntu 24.04 + cloud-init + agente invitado de QEMU) en VergeOS

  • Instale el Extensión VergeOS Node Driver chart de Helm en el clúster de Rancher

  • Aprovisione un clúster descendente usando VergeOS como controlador de nodos

  • Instale el Controlador CSI y Administrador del Controlador de Nube en el clúster descendente para almacenamiento persistente y balanceadores de carga

Documentación y recursos

Para ver la configuración detallada, las banderas del controlador, los valores del chart y las notas de la versión, consulte los repositorios de GitHub:

Repositorio
Descripción

docker-machine-driver-vergeos

Controlador de nodos Docker Machine / Rancher

ui-extension-vergeos

Extensión de UI de Rancher

helm-charts

Repositorio de charts de Helm

Soporte

Si encuentra problemas o tiene solicitudes de funciones, abra un issue en el repositorio de GitHub correspondiente:

https://github.com/verge-io/docker-machine-driver-vergeos/issues

AnteriorSDK de VergeOS para Python (pyvergeos)
SiguienteIntegración de Storware con VergeOS

Última actualización

¿Te fue útil?