> 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/automate-protect-and-extend/es/integraciones-y-api/rancher-integration.md). # Integración con Rancher ## Descripción general VergeOS se integra con [Rancher](https://www.rancher.com/) 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](#docker-machine-driver) | Aprovisiona máquinas virtuales de VergeOS como nodos de Kubernetes | | [Extensión de la interfaz de usuario](#ui-extension) | 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](/automate-protect-and-extend/es/integraciones-y-api/kubernetes-integration.md) 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. ```mermaid graph TD subgraph rancher["Servidor Rancher"] ui["Extensión de UI para VergeOS"] creds["Credenciales en la nube"] --> driver["Controlador Docker Machine"] end driver --> vms["Máquinas virtuales de VergeOS"] subgraph cluster["Clúster RKE2/K3s (máquinas virtuales de VergeOS)"] ccm["Administrador del controlador de nube"] csi["Controlador CSI"] ccm_features["Metadatos del nodo · Ciclo de vida del nodo · Balanceadores de carga"] csi_features["NAS ReadWriteMany · Bloque ReadWriteOnce"] ccm --- ccm_features csi --- csi_features end vms --> cluster ``` ### 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 {% hint style="success" %} **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 {% endhint %} {% hint style="warning" %} **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. {% endhint %} 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. {% hint style="warning" %} **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. {% endhint %} {% hint style="info" %} **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](https://docs.rke2.io/install/requirements#networking) . {% endhint %} | 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:** ```bash helm repo add verge-io https://verge-io.github.io/helm-charts helm repo update helm install vergeos-node-driver verge-io/vergeos-node-driver \\ -n cattle-system \\ --set "vergeosHosts={vergeos.example.com}" ``` 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. {% hint style="info" %} **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. {% endhint %} ### Uso independiente El controlador también funciona fuera de Rancher con Docker Machine directamente: ```bash docker-machine create \\ --driver vergeos \\ --vergeos-host vergeos.example.com \\ --vergeos-api-key your-api-key \\ --vergeos-insecure \\ --vergeos-template-vm ubuntu-2404 \\ --vergeos-network your-network-name \\ --vergeos-ssh-user ubuntu \\ --vergeos-cpu-cores 2 \\ --vergeos-ram 4096 \\ --vergeos-disk-size 30 \\ my-docker-host ``` {% hint style="info" %} **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. {% endhint %} Para ver la lista completa de flags del controlador y variables de entorno, consulte el repositorio del controlador en [Documentación y recursos](#documentation-and-resources) a continuación. {% hint style="info" %} **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. {% endhint %} *** ## 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 {% hint style="info" %} **Compatibilidad** La extensión de UI requiere Rancher v2.10+ y el framework de extensiones de Rancher v3.x. {% endhint %} {% hint style="info" %} **Instalación** La extensión de UI se instala automáticamente como parte de [el chart de Helm combinado](#installing-in-rancher). No hay un paso de instalación aparte. {% endhint %} *** ## 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](/automate-protect-and-extend/es/integraciones-y-api/kubernetes-integration.md) 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](#installing-in-rancher) 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](/automate-protect-and-extend/es/integraciones-y-api/kubernetes-integration.md) 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](https://github.com/verge-io/docker-machine-driver-vergeos) | Controlador de nodos Docker Machine / Rancher | | [ui-extension-vergeos](https://github.com/verge-io/ui-extension-vergeos) | Extensión de UI de Rancher | | [helm-charts](https://github.com/verge-io/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: --- # 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/automate-protect-and-extend/es/integraciones-y-api/rancher-integration.md?ask=&goal= ``` `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.