> 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/07-kubernetes-rancher.md). # Integración con Kubernetes y Rancher Ejecutar Kubernetes en VergeOS no es un complemento añadido — es una **integración de primera clase** construida a partir de cuatro componentes специально diseñados (Docker Machine Driver, Rancher UI Extension, Cloud Controller Manager y CSI Driver), más un Cluster Autoscaler opcional para clústeres aprovisionados por Rancher, que ofrecen a Rancher (y a cualquier implementación de RKE2/K3s) plena visibilidad de la computación, el almacenamiento y la red de VergeOS. En lugar de tratar VergeOS como un simple host de VMs, estos componentes permiten a Kubernetes aprovisionar nodos, adjuntar almacenamiento persistente y crear balanceadores de carga mediante las API nativas de VergeOS — las mismas API que alimentan el panel. ## Requisitos previos Antes de instalar la integración, asegúrese de que el entorno proporcione: * Un **Servidor Rancher** instalación (v2.10+) con `kubectl` y `helm` herramientas de CLI * Un **VM de plantilla** ejecutando Ubuntu 24.04 con cloud-init instalado (y se recomienda el agente invitado de QEMU) * Un **clave de API de VergeOS** generada en **Configuración de usuario** * Una red de VergeOS de destino con **DHCP habilitado** — el controlador descubre las IP de los nodos a través del agente invitado de QEMU y las VMs clonadas no obtendrán direcciones sin DHCP * Para almacenamiento persistente respaldado por bloques: una VM vacía de VergeOS llamada **`k8spool`** para alojar unidades de bloque inactivas (su ID de VM se pasa al chart Helm de CSI en el momento de la instalación; la VM nunca necesita arrancar) ## Resumen de la arquitectura La integración de Kubernetes de VergeOS se entrega como cuatro componentes distintos — el Docker Machine Driver, la Rancher UI Extension, el Cloud Controller Manager y el CSI Driver — cada uno responsable de una capa de la pila, con un Cluster Autoscaler opcional disponible para clústeres aprovisionados por Rancher: ```mermaid graph TB subgraph "Panel de Rancher" UI["Extensión de UI
(paneles de VergeOS)"] RC["Credencial de nube &
Configuración de máquina"] end subgraph "Aprovisionamiento de nodos" DMD["Docker Machine Driver
(docker-machine-driver-vergeos)"] end subgraph "Clúster de Kubernetes" CCM["Administrador de controladores de nube
(vergeos-cloud-controller-manager)"] CSI["Controlador CSI
(csi-vergeos)"] end subgraph "Plataforma VergeOS" API["API REST de VergeOS"] VM["VMs y plantillas"] VSAN["Almacenamiento vSAN / NAS"] NET["Redes virtuales"] end UI --> RC RC --> DMD DMD -->|"Clonar plantilla,
inyectar claves SSH"| API API --> VM CCM -->|"Ciclo de vida de nodos,
balanceadores de carga"| API API --> NET CSI -->|"Volúmenes persistentes"| API API --> VSAN ``` ### Docker Machine Driver Aprovisiona VMs de VergeOS como nodos de Kubernetes — clona plantillas, inyecta claves SSH, redimensiona discos y adjunta redes. ### Extensión de UI de Rancher Expone directamente en el panel de Rancher los paneles de Credencial de nube y Configuración de máquina específicos de VergeOS. ### Administrador de controladores de nube Sincroniza el estado de los nodos de Kubernetes con el ciclo de vida de las VMs de VergeOS y aprovisiona servicios de balanceador de carga bajo demanda. ### Controlador CSI Mapea el almacenamiento vSAN/NAS/bloques de VergeOS a PersistentVolumes de Kubernetes para cargas de trabajo con estado. Los cuatro componentes (DMD, Extensión de UI, CCM, controlador CSI) se distribuyen a través del **repositorio Helm de verge-io**, lo que garantiza un versionado coherente y una instalación simplificada. Un **Cluster Autoscaler** opcional está disponible para clústeres aprovisionados por Rancher. ## Docker Machine Driver La `docker-machine-driver-vergeos` es la base de la integración. Enseña a Docker Machine (y, por extensión, a Rancher) cómo crear VMs en VergeOS — convirtiendo VergeOS en un aprovisionador de nodos de primera clase para clústeres RKE2 y K3s. ### Cómo funciona Cuando Rancher (o Docker Machine independiente) solicita un nuevo nodo, el controlador ejecuta esta secuencia: 1. **Clona la VM de plantilla** — Se clona una plantilla de VM de VergeOS previamente creada (por ejemplo, Ubuntu 24.04 con cloud-init) para crear el nuevo nodo 2. **Configura los recursos de cómputo** — Los núcleos de CPU y la RAM se establecen según la especificación del clúster 3. **Inyecta claves SSH mediante cloud-init** — El controlador genera un par de claves SSH e inyecta la clave pública mediante cloud-init para un acceso seguro sin contraseña 4. **Redimensiona el disco principal** — Si el clúster requiere más almacenamiento del que proporciona la plantilla, el controlador redimensiona el disco de arranque 5. **Se conecta a la red de destino** — La VM se conecta a la red virtual de VergeOS especificada 6. **Enciende y espera la IP** — El controlador supervisa la obtención de una dirección IP a través del agente invitado de QEMU (preferido) o de una concesión DHCP de respaldo Si cualquier paso falla, el controlador limpia automáticamente las VMs creadas parcialmente — no quedan recursos huérfanos. ### Autenticación El controlador usa **autenticación mediante clave de API** para comunicarse con la API REST de VergeOS. Genere una clave de API desde la UI de VergeOS en **Configuración de usuario**, luego proporciónela mediante el `--vergeos-api-key` interruptor o la `VERGEOS_API_KEY` variable de entorno. ### Banderas de configuración | Bandera | Variable de entorno | Predeterminado | Descripción | | ----------------------- | --------------------- | ---------------------------- | -------------------------------------------------------------- | | `--vergeos-host` | `VERGEOS_HOST` | *(requerido)* | URL del endpoint de VergeOS | | `--vergeos-api-key` | `VERGEOS_API_KEY` | *(requerido)* | Clave de API para autenticación | | `--vergeos-insecure` | `VERGEOS_INSECURE` | `false` | Omitir la verificación TLS | | `--vergeos-template-vm` | `VERGEOS_TEMPLATE_VM` | *(requerido)* | Nombre de la VM de plantilla a clonar | | `--vergeos-network` | `VERGEOS_NETWORK` | *(requerido)* | Red de destino para la conexión | | `--vergeos-cpu-cores` | `VERGEOS_CPU_CORES` | `2` | Núcleos de CPU por nodo | | `--vergeos-ram` | `VERGEOS_RAM` | `2048` | RAM en MB por nodo | | `--vergeos-disk-size` | `VERGEOS_DISK_SIZE` | `0` (tamaño de la plantilla) | Sobrescritura del tamaño del disco en MB | | `--vergeos-ssh-user` | `VERGEOS_SSH_USER` | `root` | Nombre de usuario SSH | | `--vergeos-ssh-port` | `VERGEOS_SSH_PORT` | `22` | Puerto SSH | | `--vergeos-cloudinit` | — | — | Configuración personalizada de cloud-init (archivo o en línea) | ### Requisitos de la plantilla Su plantilla de VM debe incluir: * **Cloud-init** instalado y habilitado — necesario para la inyección de claves SSH y la configuración del nombre de host * **agente invitado de QEMU** (recomendado) — proporciona una detección fiable de direcciones IP; recurre al arrendamiento DHCP de la NIC si no está disponible * **Docker** (solo para uso independiente) — las implementaciones de Rancher instalan el tiempo de ejecución de contenedores automáticamente ### Compatibilidad con Ubuntu 24.04 El controlador incluye un manejo automático de los aspectos específicos de Ubuntu 24.04: * **Configuración DHCP de Netplan** para dinámico `en*` nomenclatura de interfaces * **Regeneración del Machine-ID** para garantizar identificadores DHCP únicos por clon * **Limpieza de concesiones DHCP obsoletas** para evitar conflictos de IP por herencia de la plantilla {% hint style="success" %} **Dimensionamiento de nodos de Rancher** Las implementaciones de Rancher requieren un **mínimo de 4 GB de RAM** por nodo. Para estabilidad en producción, **8 GB de RAM** por nodo se recomienda. {% endhint %} ### Uso independiente Puede usar el controlador fuera de Rancher para aprovisionamiento ad hoc de Docker Machine: ```bash docker-machine create --driver vergeos \ --vergeos-host vergeos.example.com \ --vergeos-api-key your-api-key \ --vergeos-template-vm ubuntu-2404 \ --vergeos-network my-k8s-network \ --vergeos-ssh-user ubuntu \ --vergeos-cpu-cores 4 \ --vergeos-ram 8192 \ k8s-worker-01 ``` {% hint style="info" %} **Usuario SSH predeterminado** El controlador usa por defecto `root` para SSH, pero las imágenes cloud de Ubuntu no permiten inicio de sesión SSH como root. Cuando use la CLI directamente contra una plantilla Ubuntu, establezca `--vergeos-ssh-user ubuntu` (la extensión de UI de Rancher ya usa por defecto `ubuntu`). {% endhint %} ## Extensión de UI de Rancher La `ui-extension-vergeos` añade paneles específicos de VergeOS al **panel de Rancher**, proporcionando una experiencia de usuario nativa para gestionar clústeres de Kubernetes respaldados por VergeOS sin salir de la UI de Rancher. ### Panel de credencial de nube Al crear una nueva Credencial de nube en Rancher, la extensión añade una **VergeOS** opción de proveedor. Introduzca la URL de su host de VergeOS, la clave de API y la configuración TLS — Rancher los almacena de forma segura y los usa para todas las operaciones posteriores de aprovisionamiento de nodos. ### Panel de configuración de máquina Al definir pools de nodos para un nuevo clúster, la extensión expone campos de configuración específicos de VergeOS: * **VM de plantilla** — Seleccione entre las plantillas de VM de VergeOS disponibles * **Red** — Elija la red virtual de destino * **CPU / RAM / Disco** — Establezca los recursos de cómputo por nodo * **Cloud-init** — Proporcione scripts de inicialización personalizados La extensión se implementa como parte del `vergeos-node-driver` chart Helm, que agrupa juntos tanto el Docker Machine Driver como la UI Extension. ## Administrador de controladores de nube La `vergeos-cloud-controller-manager` (CCM) conecta las operaciones del clúster de Kubernetes con el plano de control de VergeOS, implementando la interfaz estándar de proveedor de nube de Kubernetes. ### Sincronización del ciclo de vida de nodos El CCM supervisa continuamente la lista de nodos de Kubernetes y la sincroniza con el estado de las VMs de VergeOS: * **Registro de nodos** — Cuando un nuevo nodo se une al clúster, el CCM lo anota con metadatos específicos de VergeOS (ID de VM, red, zona) * **Eliminación de nodos** — Cuando una VM de VergeOS se elimina o se apaga, el CCM marca el nodo de Kubernetes correspondiente como no disponible y desencadena la reprogramación de pods * **Monitoreo de estado** — Las comprobaciones periódicas garantizan que el estado del nodo de Kubernetes refleje el estado real de la VM ### Aprovisionamiento de balanceadores de carga Cuando se crea un Service de Kubernetes de tipo `LoadBalancer` el CCM aprovisiona un balanceador de carga a través de la capa de red de VergeOS: * Asigna una IP virtual del pool de direcciones configurado * Configura la distribución del tráfico entre los puertos de los nodos de backend * Actualiza el `status.loadBalancer.ingress` con la IP asignada VergeOS gestiona de forma nativa el aprovisionamiento de balanceadores de carga a través del CCM. {% hint style="info" %} **¿Vienes de VMware?** En VergeOS, el CCM combina la gestión del ciclo de vida de los nodos y `LoadBalancer` el aprovisionamiento de Services en un solo componente instalado con Helm — sin complementos separados de cloud-provider, CSI/CPI y balanceador de carga que ensamblar. {% endhint %} {% hint style="info" %} **¿Vienes de Nutanix?** VergeOS funciona con cualquier cadena de herramientas RKE2/K3s a través de Rancher en lugar de distribuir una versión propietaria de Kubernetes — usted elige la variante upstream de Kubernetes, y el CCM proporciona la integración nativa del proveedor de nube encima. {% endhint %} ## Controlador CSI La `csi-vergeos` (Container Storage Interface) expone el almacenamiento de VergeOS a las cargas de trabajo de Kubernetes mediante la especificación estándar de CSI. ### Backends de almacenamiento El controlador CSI admite dos backends, ambos servidos por un único binario Go: | Backend | Modo de acceso | Descripción | | ---------- | -------------- | ----------------------------------------------------------------------- | | **NAS** | ReadWriteMany | Volúmenes EXT4 en servicios NAS de VergeOS, expuestos mediante NFS | | **Bloque** | ReadWriteOnce | Unidades de VM conectadas en caliente a VMs de VergeOS a través de vSAN | ### Cómo funciona 1. Un desarrollador crea un `PersistentVolumeClaim` (PVC) en Kubernetes 2. El controlador CSI se comunica con la API de VergeOS para aprovisionar el almacenamiento solicitado 3. El almacenamiento se adjunta al nodo que ejecuta el pod y se monta en la ruta especificada 4. Al eliminar el pod, el controlador CSI gestiona el desmontaje y, opcionalmente, la eliminación según la política de reclamación ### Ejemplo de StorageClass ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: vergeos-block provisioner: csi.vergeos.com parameters: type: block reclaimPolicy: Delete volumeBindingMode: WaitForFirstConsumer ``` Los administradores de Kubernetes definen `StorageClass` recursos que se asignan a los backends de almacenamiento de VergeOS. Luego, los desarrolladores hacen referencia a estas clases en sus PVC sin necesidad de comprender la infraestructura subyacente. ## Charts de Helm La `helm-charts` el repositorio agrupa todos los componentes de Kubernetes de VergeOS para una implementación optimizada. Hay tres charts disponibles: ### Charts disponibles | Chart | Componentes | Propósito | | ---------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------- | | `vergeos-node-driver` | Controlador de Docker Machine + Extensión de UI | Aprovisionamiento de nodos e integración con el panel de Rancher | | `vergeos-cloud-controller-manager` | CCM | Sincronización del ciclo de vida de nodos y aprovisionamiento de balanceadores de carga | | `vergeos-csi` | Controlador CSI | Almacenamiento persistente (NAS + bloque) | ### Instalación Añada el repositorio Helm de VergeOS e instale los charts: ```bash # Añadir el repositorio Helm de VergeOS helm repo add verge-io https://verge-io.github.io/helm-charts helm repo update # Buscar charts disponibles helm search repo verge-io # Instalar el Administrador de controladores de nube helm install vergeos-ccm verge-io/vergeos-cloud-controller-manager \ --namespace kube-system # Instalar el controlador CSI helm install vergeos-csi verge-io/vergeos-csi \ --namespace kube-system # Instalar el controlador de nodos + la extensión de UI (para Rancher) helm install vergeos-node-driver verge-io/vergeos-node-driver \ --namespace cattle-system \ --set "vergeosHosts={vergeos.example.com}" ``` La `vergeosHosts` valor es una lista blanca obligatoria de nombres de host de VergeOS a los que el proxy de Rancher tiene अनुमति de acceder. Reemplace `vergeos.example.com` con el/los nombre(s) de host de su(s) entorno(s) VergeOS; sin ello, el controlador no puede الوصول a la API de VergeOS. ## Flujo de implementación de extremo a extremo Uniendo los cuatro componentes, este es el flujo completo para desplegar un clúster de Kubernetes en VergeOS con Rancher: ```mermaid flowchart LR A["1. Preparar
VM de plantilla"] --> B["2. Registrar
Controlador de nodos"] B --> C["3. Crear credencial
de nube"] C --> D["4. Aprovisionar
clúster"] D --> E["5. Implementar
CCM + CSI"] E --> F["6. Ejecutar
cargas de trabajo"] style A fill:#2563eb,color:#fff style B fill:#2563eb,color:#fff style C fill:#2563eb,color:#fff style D fill:#2563eb,color:#fff style E fill:#2563eb,color:#fff style F fill:#16a34a,color:#fff ``` ### Paso 1: Preparar una VM de plantilla Cree una VM de VergeOS con Ubuntu 24.04 (Noble Numbat) — actualmente el único sistema operativo de plantilla compatible — instale cloud-init y el agente invitado de QEMU, y luego guárdela como plantilla. Esta plantilla se clonará para cada nodo de Kubernetes. ### Paso 2: Registrar el controlador de nodos Aplique el manifiesto VergeOS NodeDriver a su clúster de gestión de Rancher usando `kubectl`. Esto informa a Rancher sobre el Docker Machine Driver de VergeOS y lo habilita como opción de aprovisionamiento. Reinicie Rancher después del registro para activar el esquema del controlador. ### Paso 3: Crear una credencial de nube En la UI de Rancher, cree una nueva **credencial de nube** usando el proveedor VergeOS (añadido por la Extensión de UI). Introduzca la URL de su host de VergeOS y la clave de API. ### Paso 4: Aprovisionar el clúster Cree un nuevo clúster RKE2 o K3s en Rancher, seleccionando VergeOS como proveedor de infraestructura. Defina sus pools de nodos (plano de control, etcd, workers) con los recursos de cómputo deseados. Rancher usa el Docker Machine Driver para clonar VMs, inyectar claves SSH y arrancar el clúster de Kubernetes. ### Paso 5: Implementar CCM y CSI Instale el Cloud Controller Manager y el CSI Driver mediante Helm en el nuevo clúster. El CCM comienza inmediatamente a sincronizar el estado de los nodos con VergeOS, y el controlador CSI pone el almacenamiento de VergeOS a disposición de PersistentVolumeClaims. ### Paso 6: Ejecutar cargas de trabajo Implemente sus aplicaciones con manifiestos estándar de Kubernetes. Los Services de tipo `LoadBalancer` son gestionados por el CCM, y los PersistentVolumeClaims son atendidos por el controlador CSI — todo respaldado por la infraestructura de VergeOS. ## Registro del controlador de nodos en Rancher El Docker Machine Driver debe registrarse como un recurso NodeDriver de Rancher. Aplique el siguiente manifiesto con `kubectl`: ```yaml apiVersion: management.cattle.io/v3 kind: NodeDriver metadata: name: vergeos annotations: privateCredentialFields: "apiKey" publicCredentialFields: "host,insecure" spec: active: true builtin: false displayName: vergeos uiUrl: "" url: "https://github.com/verge-io/docker-machine-driver-vergeos/releases/download/v0.1.0/docker-machine-driver-vergeos-linux-amd64.tar.gz" ``` Después de aplicarlo, reinicie Rancher para cargar el nuevo esquema del controlador. La opción VergeOS aparecerá entonces en el asistente de creación de clústeres. ## Resumen La integración de Kubernetes de VergeOS transforma VergeOS de una plataforma de VM en un **proveedor de nube de Kubernetes completo**. Al implementar las interfaces Docker Machine, Cloud Controller Manager y CSI, VergeOS proporciona a Kubernetes los mismos componentes básicos disponibles en los proveedores de nube pública: aprovisionamiento automatizado de nodos, gestión del ciclo de vida, balanceo de carga y almacenamiento persistente, todo ejecutándose en su propia infraestructura con el rendimiento y la eficiencia de VergeOS vSAN y la red virtual. ### Aprovisionamiento automatizado de nodos El controlador Docker Machine clona VMs a partir de plantillas con cloud-init, claves SSH y conexión a la red, totalmente automatizado a través de Rancher. ### Proveedor de nube nativo Los controladores CCM y CSI implementan interfaces estándar de Kubernetes, por lo que las cargas de trabajo usan `LoadBalancer` servicios y `PersistentVolumeClaims` sin modificaciones. ### Despliegue gestionado por Helm Todos los componentes se empaquetan como charts de Helm para una instalación coherente y controlada por versiones en todos los clústeres. ### Experiencia nativa de Rancher La extensión de la interfaz de usuario lleva la configuración de VergeOS directamente al panel de Rancher, sin necesidad de cambiar de contexto. --- # 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/07-kubernetes-rancher.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.