> 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/kubernetes-integration.md). # Integración con Kubernetes ## Descripción general VergeOS proporciona integración nativa con Kubernetes a través de un controlador de almacenamiento CSI y un Cloud Controller Manager (CCM). Estos componentes conectan cualquier clúster de Kubernetes que se ejecute en VMs de VergeOS — ya sea aprovisionado mediante [Rancher](/automate-protect-and-extend/es/integraciones-y-api/rancher-integration.md), kubeadm o cualquier otro método — con la plataforma subyacente VergeOS. | Componente | Propósito | | ----------------------------------------------------- | ------------------------------------------------------------------------- | | [Controlador CSI](#csi-driver) | Almacenamiento persistente para pods de Kubernetes mediante VergeOS vSAN | | [Cloud Controller Manager](#cloud-controller-manager) | Gestión del ciclo de vida de nodos e integración con balanceador de carga | ### Requisitos previos * Un clúster de Kubernetes ejecutándose en VMs de VergeOS (RKE2, K3s, kubeadm, etc.) * Una clave de API de VergeOS (generada en Configuración de usuario) * `kubectl` y `helm` Herramientas de CLI * Acceso al kubeconfig del clúster {% hint style="info" %} **Certificados autofirmados** Si el entorno VergeOS usa un certificado autofirmado, establezca `vergeos.verifySSL=false` al instalar el controlador CSI y los charts Helm de CCM. Este es el valor predeterminado, pero conviene tenerlo en cuenta si lo cambiamos más adelante. {% endhint %} *** ## Controlador CSI El controlador de la interfaz de almacenamiento de contenedores (CSI) permite que los pods de Kubernetes soliciten y monten almacenamiento de VergeOS como volúmenes persistentes. Delega las operaciones de almacenamiento directamente a la API de VergeOS, usando vSAN para lo que fue diseñado: deduplicación, colocación multinivel y redundancia distribuida. ### 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 los servicios NAS de VergeOS, expuestos por NFS | | **Bloque** | ReadWriteOnce | Unidades de VM conectadas en caliente a VMs de VergeOS a través de vSAN | {% hint style="info" %} **¿Por qué no Longhorn?** Longhorn ejecuta su propio motor de almacenamiento replicado *en* Kubernetes, superponiendo replicación, instantáneas y programación sobre el hipervisor. En VergeOS, el controlador CSI nativo encaja mejor: * **Sin doble replicación** — la arquitectura de espejado distribuido de vSAN ya proporciona redundancia de datos * **Deduplicación en línea** — la deduplicación de vSAN es global en todo el clúster; los volúmenes de Longhorn son blobs opacos que no pueden participar * **Ubicación multinivel** — los volúmenes se ubican en el nivel correcto de vSAN (NVMe, SSD, HDD) según la StorageClass * **Gestión unificada** — los volúmenes aparecen en la interfaz de VergeOS junto con VMs, instantáneas y recursos compartidos NAS {% endhint %} ### VM de pool de almacenamiento en bloque Para almacenamiento en bloque, cree una VM vacía en VergeOS llamada `k8spool`. Nunca necesita arrancar: solo alberga unidades de bloque inactivas. El ID de la VM se pasa al chart de Helm durante la instalación. ### Instalación El controlador CSI se distribuye como un chart de Helm desde el repositorio `verge-io` de Helm y se puede instalar mediante la CLI de Helm o a través de la **Rancher Apps UI** en clústeres descendentes. Consulte [Documentación y recursos](#documentation-and-resources) a continuación para detalles del chart, valores de Helm y opciones de configuración. {% hint style="warning" %} **Clúster descendente** Al instalar a través de la interfaz de usuario de Rancher Apps, el repositorio de Helm debe agregarse en el **clúster descendente**, no en el clúster de gestión de Rancher. Los ClusterRepos no se propagan desde el clúster de gestión. {% endhint %} *** ## Cloud Controller Manager El Cloud Controller Manager (CCM) es la interfaz estándar del proveedor de nube de Kubernetes para VergeOS. Se encarga de la gestión del ciclo de vida de los nodos y del aprovisionamiento del balanceador de carga. ### Funciones * **Gestión de nodos** — Rellena los metadatos del nodo de Kubernetes (ID de proveedor, tipo de instancia, IP internas) a partir de VMs de VergeOS. Detecta la existencia de la VM y su estado de energía para la gestión del ciclo de vida del nodo. * **Balanceo de carga** — Aprovisiona reglas NAT/traducción de VergeOS VNet para `type: LoadBalancer` Servicios. Asigna IPs de un grupo configurable y mapea automáticamente los puertos del servicio a los puertos de nodo. ### Cómo funciona el ciclo de vida de los nodos La CCM implementa la `InstancesV2` interfaz: 1. **InstanceMetadata** — Resuelve un nodo de Kubernetes a una VM de VergeOS (por ID de proveedor o nombre), luego devuelve el ID de proveedor (`vergeos://`), el tipo de instancia (`cpu-mb`), y las direcciones IP internas de las NIC de la VM 2. **InstanceExists** — Comprueba si la VM subyacente aún existe en VergeOS 3. **InstanceShutdown** — Indica si la VM está apagada ### Cómo funciona el balanceo de carga La CCM implementa la `LoadBalancer` interfaz usando reglas de VergeOS VNet: 1. **EnsureLoadBalancer** — Asigna una IP del grupo y luego crea una regla NAT de VNet por cada puerto del servicio. Las reglas traducen `:` en `:`. Llama a `ApplyRules` para activar. 2. **UpdateLoadBalancer** — Actualiza las IP de destino en las reglas existentes cuando cambian los nodos 3. **EnsureLoadBalancerDeleted** — Elimina todas las reglas de VNet para el servicio y aplica el cambio ### Instalación La CCM se distribuye como un chart de Helm junto con el controlador CSI. Instálela mediante la CLI de Helm o a través de la interfaz de usuario de Rancher Apps en el clúster descendente. Consulte [Documentación y recursos](#documentation-and-resources) a continuación para detalles del chart y opciones de configuración. *** ## Escalador automático de clúster El escalador automático de clúster de Kubernetes funciona con clústeres respaldados por VergeOS aprovisionados mediante [Rancher](/automate-protect-and-extend/es/integraciones-y-api/rancher-integration.md). Ajusta automáticamente el número de nodos en un pool según las solicitudes de recursos pendientes de los pods: escala hacia arriba cuando los pods no pueden programarse y hacia abajo cuando los nodos están infrautilizados. Consulte [Documentación y recursos](#documentation-and-resources) a continuación para el enlace al proyecto upstream. ### Cómo funciona El autoscaler utiliza la API de Rancher para gestionar los pools de nodos: 1. **Escalar hacia arriba** — Cuando los pods quedan pendientes por recursos insuficientes, el autoscaler aumenta el tamaño del pool de nodos. Rancher luego usa el controlador Docker Machine para aprovisionar nuevas VMs de VergeOS. 2. **Escalar hacia abajo** — Cuando los nodos están infrautilizados durante un período configurable, el autoscaler los cordona, vacía y elimina. El controlador elimina las VMs de VergeOS subyacentes. {% hint style="success" %} **Solicitudes de recursos** El autoscaler toma decisiones de escalado basándose en las solicitudes de recursos de los pods, no en el uso real. Asegúrese de que las cargas de trabajo definan `requests` en sus especificaciones de pod para un comportamiento de escalado preciso. {% endhint %} *** ## Resumen VergeOS proporciona tres componentes de Kubernetes que funcionan junto con cualquier clúster que se ejecute en VMs de VergeOS: * **Controlador CSI** — volúmenes persistentes mediante VergeOS NAS (ReadWriteMany) y almacenamiento en bloque vSAN (ReadWriteOnce) * **Cloud Controller Manager** — gestión del ciclo de vida de nodos y `LoadBalancer` Servicios respaldados por reglas de VergeOS VNet * **Escalador automático de clúster** — escalado automático de pools de nodos para clústeres aprovisionados por Rancher Todos los componentes se distribuyen como charts de Helm desde el `verge-io` repositorio y pueden instalarse mediante la CLI de Helm o la interfaz de usuario de Rancher Apps. ## Siguientes pasos * ¿Es nuevo en Rancher en VergeOS? Consulte la guía de [Integración con Rancher](/automate-protect-and-extend/es/integraciones-y-api/rancher-integration.md) para el aprovisionamiento de clústeres, la preparación de VMs plantilla y la configuración del controlador de nodos. * ¿Ya tiene un clúster en ejecución? Añada el repositorio de Helm y explore los charts disponibles: ```bash helm repo add verge-io https://verge-io.github.io/helm-charts helm repo update helm search repo verge-io ``` * Visite los repositorios del proyecto a continuación para valores de chart, referencia de configuración y notas de la versión. ## Documentación y recursos | Repositorio | Descripción | | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | [csi-vergeos](https://github.com/verge-io/csi-vergeos) | Controlador de la interfaz de almacenamiento de contenedores | | [vergeos-cloud-controller-manager](https://github.com/verge-io/vergeos-cloud-controller-manager) | Cloud Controller Manager | | [helm-charts](https://github.com/verge-io/helm-charts) | Repositorio de charts de Helm | | [Escalador automático de clúster de Kubernetes](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler) | Escalador automático de clúster upstream | ## Soporte Si encuentra problemas o tiene solicitudes de funciones, abra un issue en el repositorio de GitHub correspondiente: * [Problemas del controlador CSI](https://github.com/verge-io/csi-vergeos/issues) * [Problemas de CCM](https://github.com/verge-io/vergeos-cloud-controller-manager/issues) * [Problemas de los charts de Helm](https://github.com/verge-io/helm-charts/issues) --- # 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/kubernetes-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.