Este documento ha sido traducido utilizando tecnología de traducción automática. Si bien nos esforzamos por proporcionar traducciones precisas, no ofrecemos garantías sobre la integridad, precisión o confiabilidad del contenido traducido. En caso de discrepancia, la versión original en inglés prevalecerá y constituirá el texto autorizado.

Registro de Clusters Existentes

La función de registro de clústeres reemplazó la función de importar clústeres.

El control que Rancher tiene para gestionar un clúster registrado depende del tipo de clúster. Para más detalles, consulta Capacidades de gestión para clústeres registrados.

Requisitos previos

Roles de nodo de Kubernetes

Los clústeres de Kubernetes RKE registrados deben tener los tres roles de nodo: etcd, controlplane y worker. Un clúster con solo componentes de controlplane no puede ser registrado en Rancher.

Para más información sobre los roles de nodo RKE, consulta las mejores prácticas.

Autorizaciones

Para registrar un clúster en Rancher, debes tener cluster-admin privilegios dentro de ese clúster. Si no los tienes, concede estos privilegios a tu usuario ejecutando:

kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole cluster-admin \
  --user [USER_ACCOUNT]

Dado que, por defecto, Google Kubernetes Engine (GKE) no concede el rol cluster-admin, debes ejecutar estos comandos en los clústeres GKE antes de poder registrarlos. Para aprender más sobre el control de acceso basado en funciones para GKE, consulta la documentación oficial de Google.

Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS) y Google Kubernetes Engine (GKE)

Para importar o aprovisionar con éxito clústeres EKS, AKS y GKE desde Rancher, el clúster debe tener al menos un grupo de nodos gestionado.

Los clústeres AKS solo pueden ser importados si las cuentas locales están habilitadas. Si un clúster está configurado para usar Microsoft Entra ID para la autenticación, entonces Rancher no podrá importarlo y reportará un error.

Los clústeres EKS Anywhere pueden ser importados/registrados en Rancher con una dirección API y credenciales, como cualquier clúster en sentido descendente. Los clústeres EKS Anywhere se tratan como clústeres importados y no tienen soporte completo de ciclo de vida por parte de Rancher.

Los clústeres GKE Autopilot no son compatibles. Consulta Comparar GKE Autopilot y Standard para más información sobre las diferencias entre los modos de GKE.

Registrando un Clúster

  1. Haz clic en ☰ > Gestión de Clústeres.

  2. En la página de Clústeres, Importar Existente.

  3. Elige el tipo de clúster.

  4. Utiliza Roles de Miembros para configurar la autorización de usuarios para el clúster. Haz clic en Añadir Miembro para añadir usuarios que puedan acceder al clúster. Utiliza el menú desplegable Rol para establecer permisos para cada usuario.

  5. Si estás importando un clúster genérico de Kubernetes en Rancher, realiza los siguientes pasos para la configuración:

    1. Haz clic en Variables de Entorno del Agente bajo Opciones del Clúster para establecer variables de entorno para agente del clúster rancher. Las variables de entorno se pueden establecer utilizando pares clave-valor. Si el agente de rancher requiere el uso de un proxy para comunicarse con el servidor de Rancher, las variables de entorno HTTP_PROXY, HTTPS_PROXY y NO_PROXY se pueden establecer utilizando las variables de entorno del agente.

    2. Habilita Aislamiento de Red del Proyecto para asegurar que el clúster soporte recursos de Kubernetes NetworkPolicy. Los usuarios pueden seleccionar la opción Aislamiento de Red del Proyecto en el menú desplegable de Opciones Avanzadas para hacerlo.

    3. Configura la función de gestión de versiones para clústeres RKE2 y K3s importados.

  6. Haga clic en Crear.

  7. Se muestran los requisitos previos para los privilegios de cluster-admin (ver Requisitos Previos arriba), incluyendo un comando de ejemplo para cumplir con el requisito previo.

  8. Copia el comando kubectl en tu portapapeles y ejecútalo en un nodo donde kubeconfig esté configurado para apuntar al clúster que deseas importar. Si no estás seguro de que esté configurado correctamente, ejecuta kubectl get nodes para verificar antes de ejecutar el comando mostrado en Rancher.

  9. Si estás utilizando certificados autofirmados, recibirás el mensaje certificate signed by unknown authority. Para eludir esta validación, copia el comando que comienza con curl mostrado en Rancher en tu portapapeles. Luego ejecuta el comando en un nodo donde kubeconfig esté configurado para apuntar al clúster que deseas importar.

  10. Cuando termines de ejecutar el(los) comando(s) en tu nodo, haz clic en Hecho.

La variable de entorno NO_PROXY no está estandarizada, y el formato aceptado del valor puede diferir entre aplicaciones. Al configurar la variable NO_PROXY para Rancher, el valor debe adherirse al formato esperado por Golang.

Específicamente, el valor debe ser una cadena delimitada por comas que contenga únicamente direcciones IP, notación CIDR, nombres de dominio o etiquetas DNS especiales (por ejemplo, *). Para una descripción completa del formato de valor esperado, consulta la documentación de Golang en sentido ascendente.

Resultado:

  • Tu clúster está registrado y asignado a un estado de Pendiente. Rancher está desplegando recursos para gestionar tu clúster.

  • Puedes acceder a tu clúster una vez que su estado se actualice a Activo.

  • Los clústeres Activos están asignados a dos Proyectos: Default (que contiene el espacio de nombres default) y System (que contiene los espacios de nombres cattle-system, traefik, kube-public y kube-system, si están presentes).

No puedes volver a registrar un clúster que esté actualmente activo en una configuración de Rancher.

Configurando un Clúster EKS, AKS o GKE Importado con Terraform

Debes definir solo los campos mínimos que Rancher requiere al importar un clúster EKS, AKS o GKE con Terraform. Esto es importante ya que Rancher sobrescribirá lo que había en la configuración del clúster con cualquier configuración que el usuario haya proporcionado.

Incluso una pequeña diferencia entre el clúster actual y una configuración proporcionada por el usuario podría tener resultados inesperados.

Los campos de configuración mínimos requeridos por Rancher para importar clústeres EKS con Terraform usando eks_config_v2 son los siguientes:

  • cloud_credential_id

  • name

  • región

  • importado (este campo siempre debe establecerse en true para clústeres importados)

Ejemplo de configuración YAML para clústeres EKS importados:

resource "rancher2_cluster" "my-eks-to-import" {
  name        = "my-eks-to-import"
  description = "Terraform EKS Cluster"
  eks_config_v2 {
    cloud_credential_id = rancher2_cloud_credential.aws.id
    name                = var.aws_eks_name
    region              = var.aws_region
    imported            = true
  }
}

Puedes encontrar ejemplos adicionales para otros proveedores de nube en la documentación del Proveedor Terraform de Rancher2.

Capacidades de Gestión para Clústeres Registrados

El control que Rancher tiene para gestionar un clúster registrado depende del tipo de clúster.

Características para todos los clústeres registrados

Después de registrar un clúster, el propietario del clúster puede:

Características adicionales para clústeres registrados SUSE® Rancher Prime: RKE2 y SUSE® Rancher Prime: K3s

K3s es una distribución de Kubernetes ligera y completamente compatible para instalaciones en edge.

RKE2 es la distribución de Kubernetes de próxima generación de Rancher para instalaciones en centros de datos y en la nube.

Cuando un clúster RKE2 o K3s está registrado en Rancher, Rancher lo reconocerá. La interfaz de usuario de Rancher expondrá las características disponibles para todos los clústeres registrados, junto con las siguientes opciones para editar y actualizar el clúster:

Características adicionales para clústeres EKS, AKS y GKE registrados

Rancher gestiona los clústeres EKS, AKS o GKE registrados de manera similar a los clústeres creados en Rancher. Sin embargo, Rancher no destruye los clústeres registrados cuando los eliminas a través de la interfaz de usuario de Rancher.

Cuando creas un clúster EKS, AKS o GKE en Rancher y luego lo eliminas, Rancher destruye el clúster. Cuando eliminas un clúster registrado a través de Rancher, el servidor de Rancher se desconecta del clúster. El clúster permanece activo, aunque ya no esté en Rancher. Aún puedes acceder al clúster desregistrado de la misma manera que lo hacías antes de registrarlo.

Consulta Capacidades de gestión de clústeres por tipo de clúster para más información sobre qué características están disponibles para gestionar clústeres registrados.

Configurando la gestión de versiones para clústeres SUSE® Rancher Prime: RKE2 y SUSE® Rancher Prime: K3s

Cuando la gestión de versiones está habilitada para un clúster importado, actualizarlo fuera de Rancher puede llevar a consecuencias inesperadas.

La función de gestión de versiones para clústeres RKE2 y K3s importados se puede configurar utilizando una de las siguientes opciones:

  • Por defecto global (por defecto): Hereda el comportamiento de la configuración global imported-cluster-version-management.

  • Verdadero: Habilita la gestión de versiones, permitiendo a los usuarios controlar la versión de Kubernetes y la estrategia de actualización del clúster a través de Rancher.

  • Falso: Deshabilita la gestión de versiones, permitiendo a los usuarios gestionar la versión de Kubernetes del clúster de manera independiente, fuera de Rancher.

Puedes definir el comportamiento por defecto para los clústeres recién creados o existentes configurados como "Global default" modificando la configuración imported-cluster-version-management.

Los cambios en la configuración global de imported-cluster-version-management entran en vigor durante el próximo ciclo de reconciliación del clúster.

Si la gestión de versiones está habilitada para un clúster, Rancher desplegará la app system-upgrade-controller, junto con los planes asociados y otros recursos de Kubernetes requeridos, en el clúster. Si la gestión de versiones está deshabilitada, Rancher eliminará estos componentes del clúster.

Configuración de las Actualizaciones del Clúster SUSE® Rancher Prime: RKE2 y SUSE® Rancher Prime: K3s

Es una buena práctica de Kubernetes hacer una copia de seguridad del clúster antes de actualizar versión. Al actualizar versión un clúster K3s de alta disponibilidad con una base de datos externa, realiza una copia de seguridad de la base de datos de la manera que recomiende el proveedor de la base de datos relacional.

La concurrencia es el número máximo de nodos que se permite que estén no disponibles durante una actualización de versión. Si el número de nodos no disponibles es mayor que la concurrencia, la actualización fallará. Si una actualización falla, es posible que necesites reparar o eliminar nodos fallidos antes de que la actualización de versión pueda tener éxito.

  • Concurrencia del plano de control: El número máximo de nodos de servidor a actualizar a la vez; también el número máximo de nodos de servidor no disponibles

  • Concurrencia de trabajadores: El número máximo de trabajadores a actualizar al mismo tiempo; también el número máximo de trabajadores no disponibles.

En la documentación de RKE2 y K3s, los nodos del plano de control se llaman nodos de servidor. Estos nodos ejecutan el maestro de Kubernetes, que mantiene el estado deseado del clúster. Por defecto, estos nodos del plano de control tienen la capacidad de que se programen cargas de trabajo en ellos por defecto.

También en la documentación de RKE2 y K3s, los nodos con el rol de trabajador se llaman nodos agentes. Cualquier carga de trabajo o pod que se despliegue en el clúster puede ser programado en estos nodos por defecto.

Registro de depuración y solución de problemas para Clústeres SUSE® Rancher Prime: RKE2 y SUSE® Rancher Prime: K3s registrados

Los nodos son actualizados por el controlador de actualización del sistema que se ejecuta en el clúster descendente. Según la configuración del clúster, Rancher despliega dos planes para actualizar los nodos: uno para los nodos del plano de control y otro para los trabajadores. El controlador de actualización del sistema sigue los planes y actualiza los nodos.

Para habilitar el registro de depuración en el despliegue del controlador de actualización del sistema, edita el configmap para establecer la variable de entorno de depuración en verdadero. A continuación, reinicia el system-upgrade-controller pod.

Los registros creados por el system-upgrade-controller se pueden ver ejecutando este comando:

kubectl logs -n cattle-system system-upgrade-controller

El estado actual de los planes se puede ver con este comando:

kubectl get plans -A -o yaml

Si el clúster se queda atascado en la actualización, reinicia el system-upgrade-controller.

Para prevenir problemas al actualizar, se deben seguir las mejores prácticas de actualización de Kubernetes.

Soporte de punto final de clúster autorizado para SUSE® Rancher Prime: RKE2 y SUSE® Rancher Prime: K3s clústeres

Rancher admite puntos finales de clúster autorizados (ACE) para clústeres RKE2 y K3s registrados. Este soporte incluye pasos manuales que realizarás en el clúster descendente para habilitar el ACE. Para obtener información adicional sobre el punto final de clúster autorizado, haz clic aquí.

Notas:

  • Estos pasos solo necesitan ser realizados en los nodos del plano de control del clúster descendente. Debes configurar cada nodo del plano de control individualmente.

  • Los siguientes pasos funcionarán tanto en clústeres RKE2 como K3s registrados en v2.6.x, así como en aquellos registrados (o importados) de una versión anterior de Rancher con una actualización a v2.6.x.

  • Estos pasos alterarán la configuración de los clústeres RKE2 y K3s descendentes y desplegarán el kube-api-authn-webhook. Si una futura implementación del ACE requiere una actualización al kube-api-authn-webhook, entonces esto también tendría que hacerse manualmente. Para más información sobre este webhook, haz clic aquí.
Pasos manuales a seguir en el plano de control de cada clúster descendente para habilitar el ACE:

  1. Crea un archivo en /var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml con el siguiente contenido:

     apiVersion: v1
 kind: Config
 clusters:
 ** name: Default
cluster:
  insecure-skip-tls-verify: true
  server: http://127.0.0.1:6440/v1/authenticate
 users:
 ** name: Default
user:
  insecure-skip-tls-verify: true
 current-context: webhook
 contexts:
 ** name: webhook
context:
  user: Default
  cluster: Default

  2. Añade lo siguiente al archivo de configuración (o crea uno si no existe); ten en cuenta que la ubicación predeterminada es /etc/rancher/{rke2,k3s}/config.yaml:

     kube-apiserver-arg:
     - authentication-token-webhook-config-file=/var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml

  3. ejecute los comandos siguientes:

    sudo systemctl stop {rke2,k3s}-server
sudo systemctl start {rke2,k3s}-server

  4. Finalmente, debes volver a la interfaz de usuario de Rancher y editar el clúster importado allí para completar la habilitación de ACE. Haz clic en ⋮ > Editar Config, luego haz clic en la pestaña Red bajo Configuración del Clúster. Finalmente, haz clic en el botón Habilitado para Punto de Entrada Autorizado. Una vez que ACE esté habilitado, tendrás la opción de introducir un nombre de dominio completo (FQDN) y la información del certificado.

El campo FQDN es opcional, y si se introduce uno, debe apuntar al clúster descendente. La información del certificado solo es necesaria si hay un equilibrador de carga delante del clúster descendente que está utilizando un certificado no confiable. Si tienes un certificado válido, entonces no es necesario añadir nada al campo Certificados CA.

Anotando Clústeres Registrados

Para todos los tipos de clústeres de Kubernetes registrados, excepto para los clústeres de Kubernetes RKE2 y K3s, Rancher no tiene información sobre cómo se aprovisiona o configura el clúster.

Por lo tanto, cuando Rancher registra un clúster, asume que varias capacidades están deshabilitadas por defecto. Rancher asume esto para evitar exponer opciones de la interfaz de usuario al usuario, incluso cuando las capacidades no están habilitadas en el clúster registrado.

Sin embargo, si el clúster tiene una cierta capacidad, un usuario de ese clúster podría querer seleccionar la capacidad para el clúster en la interfaz de usuario de Rancher. Para hacer eso, el usuario necesitará indicar manualmente a Rancher que ciertas capacidades están habilitadas para el clúster.

Al anotar un clúster registrado, es posible indicar a Rancher que un clúster recibió capacidades adicionales fuera de Rancher.

La siguiente anotación indica capacidades de Ingress. Ten en cuenta que los valores de objetos no primitivos necesitan ser codificados en JSON, con las comillas escapadas.

"capabilities.cattle.io/ingressCapabilities": "[
  {
    "customDefaultBackend":true,
    "ingressProvider":"asdf"
  }
]"

Estas capacidades pueden ser anotadas para el clúster:

  • ingressCapabilities

  • loadBalancerCapabilities

  • nodePoolScalingSupported

  • nodePortRange

  • taintSupport

Todas las capacidades y sus definiciones de tipo se pueden ver en la vista de API de Rancher, en [Rancher Server URL]/v3/schemas/capabilities.

Para anotar un clúster registrado,

  1. Haz clic en ☰ > Gestión de Clústeres.

  2. En la página de Clusters, ve al clúster personalizado que deseas anotar y haz clic en ⋮ > Editar Config.

  3. Expande la sección de Etiquetas y Anotaciones.

  4. Haz clic en Añadir Anotación.

  5. Añade una anotación al clúster con el formato capabilities/<capability>: <value> donde value es la capacidad del clúster que será anulada por la anotación. En este escenario, Rancher no es consciente de ninguna capacidad del clúster hasta que añadas la anotación.

  6. Haz clic en Guardar.

Resultado: La anotación no otorga capacidades al clúster, pero indica a Rancher que el clúster tiene esas capacidades.

Solución de problemas

Esta sección enumera algunos de los errores más comunes que pueden ocurrir al importar un clúster y proporciona pasos para solucionarlos.

AKS

El siguiente error puede ocurrir si las cuentas locales están deshabilitadas en tu clúster:

Error: Getting static credential is not allowed because this cluster is set to disable local accounts.

Para resolver este problema, habilita las cuentas locales antes de intentar importar el clúster de nuevo:

az aks update --resource-group <resource-group> --name <cluster-name> --enable-local-accounts