Desplegando un cluster de K3S con Elemental

En este post explicaremos cómo usar el toolkit de Elemental, un producto de código abierto para desplegar un clúster productivo de K3S. Primero, revisaremos las definiciones básicas del software que vamos a utilizar.

Por un lado, tenemos K3S, un software de orquestación de contenedores muy similar a Kubernetes (K8S) y OpenShift, pero con la particularidad de ser mucho más ligero. Para lograr esta eficiencia, los desarrolladores han eliminado componentes opcionales de un clúster Kubernetes, dejándolo con lo esencial para funcionar. Esto hace que los requisitos mínimos para un despliegue de K3S sean entre 2 y 3 veces menores que los de K8S, y hasta 7 u 8 veces menores que los de OpenShift.

Por otro lado, tenemos Elemental, un producto reciente de Rancher que actúa como un operador, facilitando el despliegue automatizado de un clúster de K3S.

Elemental genera una imagen ISO que puedes descargar. Al utilizar esta imagen, basada en SUSE MicroOS, las máquinas se crearán y se unirán automáticamente al clúster. A través de la interfaz de usuario, puedes definir si cada máquina se utilizará como nodo de control-plane, nodo de cómputo, o incluso dedicarlas exclusivamente a etcd.

Veamos cómo funciona el sistema: el operador genera un endpoint en Rancher, desde el cual puedes generar una ISO de manera automática con solo pulsar un botón. Esta ISO es un liveCD que utiliza el endpoint para registrarse en Rancher. Una vez arrancas los hosts con ese liveCD, estos aparecerán automáticamente en el dashboard de Rancher. Desde ahí, podrás configurar el rol de cada nodo (control-plane, etcd o worker). El proceso para añadir nuevos nodos es el mismo, y para eliminarlos (o hacer un scale down), puedes hacerlo fácilmente desde la interfaz.

Cabe destacar que un servicio similar es ofrecido por Red Hat OpenShift a través de su web console, aunque esta funcionalidad no está disponible en OKD, su versión de código abierto

Comencemos el proceso de instalación.

Nuestra aquitectura va a ser la siguiente:

Revisando las matrices de compatibilidad vemos tan solo una referencia en la documentación de Elemental a la version de Rancher 2.7, dada esta, revisamos su matriz de compatibilidad y vemos que la versión más alta de K3S que vamos a poder utilizar es 1.24, existe otro elemento a revisar, la compatibilidad de cert-manager, esta va en función de la versión de kubernetes utilizada. Por lo que las versiones quedarán tal que así:

K3S - v1.24.15+k3s1

Rancher - v2.7

Elemental - v1.2

Cert-manager - v1.14

Sin embargo, tras pruebas y pruebas me he percatado que la mejor configuración para trabajar sobre KVM es, que además son las últimas versiones estables de todos a excepción del producto Elemental (aunque podrías usar la última estable)

K3S - v1.30.5+k3s1

Rancher - v2.9.2

Elemental - v2.0.0

Cert-manager - v1.16

Los únicos requisitos que vamos a necesitar para nuestra máquina virtual serán, 4 vCPU, 8GB RAM y 30GB de almacenamiento. En mi caso como ya dispongo de un template preparado con Debian 12, es el SO que voy a utilizar, aunque para esta VM podría utilizarse el que se desee.

Instalamos K3S en nuestro nodo de gestión (k3s-mgmt3)

1
2

sudo su
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.30.5+k3s1  sh -s - server --cluster-init

Instalamos helm, vamos a instalar la ultima versión estable ya que es compatible con este despliegue.

1
2
3
4

sudo su
wget -c https://get.helm.sh/helm-v3.16.1-linux-amd64.tar.gz
tar -xzvf helm-v3.16.1-linux-amd64.tar.gz
mv linux-amd64/helm /usr/local/bin/helm

Instalamos Cert-manager

1
2
3
4
5
6
7
8
9

sudo su
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl create namespace cattle-system
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.0/cert-manager.crds.yaml
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace

Para poder utilizar Elemental parece que vamos a utilizar la version de Rancher 2.9.2.

1
2
3
4
5
6
7
8
9

helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm repo update
helm install rancher rancher-stable/rancher \
  --version=v2.9.2 \
  --namespace cattle-system \
  --create-namespace \
  --set hostname=rancher.k3s-pro.alefnode.com \
  --set replicas=1 \
  --set bootstrapPassword=<PASSWORD_FOR_RANCHER_ADMIN>

Para poder realizar la instalación del operador de Elemental, necesitamos añadir los Rancher Extensions

Una vez añadidos los repositorios podremos ver en el apartado de Extensions el componente Elemental y le damos a instalar. El registry que tenemos que utilizar es:

1
2

Channel Image: registry.opensuse.org/isv/rancher/elemental/maintenance/5.5/containers/rancher/elemental-channel
Channel Tag: 1.5.4

Necesitamos crear el primer endpoint para el cluster, en este caso vamos a utilizar 2 endpoints, de forma que tengamos bien identificados los roles de control-plane y worker

El endpoint para los nodos de control-plane va a ser tal que así.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

config:
  cloud-config:
    users:
      - name: root
        passwd: root
  elemental:
    install:
      device-selector:
        - key: Name
          operator: In
          values:
            - /dev/sda
            - /dev/vda
            - /dev/nvme0
        - key: Size
          operator: Gt
          values:
            - 45Gi
      reboot: true
      snapshotter:
        type: btrfs
    registration:
      auth: mac
    reset:
      reboot: true
      reset-oem: true
      reset-persistent: true
machineInventoryLabels:
  machineuse: control-plane
  CPUcores: ${System Data/CPU/Total Cores}
  GPUmodel: ${System Data/GPU/Model}
  GPUvendor: ${System Data/GPU/Vendor}
  MEMtotal: ${System Data/Memory/Total Physical Bytes}

Para el endpoint de los nodos worker vamos a modificar el parametro a machineuse: worker

Por cada endpoint vamos a generar una imagen, dentro del endpoint seleccionamos el modelo ISO y la imagen SL Micro ISO x86_64 v2.0.2, esperamos un poco y podremos descargar la iso que se genera. Si obtienes errores puedes revisar en el apartado final ya que he anotado alguno de los problemas que te puedes encontrar en este apartado.

Una vez tengamos las ISO vamos a crear nuestras máquinas, de esta forma se registrarán automáticamente en nuestro dashboard. Importante nuestras VM deben utilizar UEFI (y si correspondiente EFI disk, si usas Proxmox), también es importante que la arquitectura de la CPU tiene que ser x86_64-v2, es importante ya que sino no vamos a poder hacerlo funcionar. En este despliegue vamos a utilizar máquinas con 4 vCPU y 4G de RAM con un almacenamiento de 50GB.

Por último vamos a generar la definición de nuestro cluster, para ello vamos a hacer uso de las etiquetas que hemos definido anteriormente para saber que role va a tener cada máquina. En la siguiente imagen podéis ver la definición completa.

Tambien puedes editar todo lo referente al propio cluster asi como las versiones a utilizar o politicas.

Una vez creado el cluster podemos añadir o eliminar nodos de igual forma.

Con esto ya tendriamos el cluster completo. Y aqui podemos ver el cluster creado.

Posibles errores y como solventarlos

Generación de la imagen ISO

Algo muy importante si en el paso de generar la imagen obtenemos un error tal que así.

fleet-default iso-image-reg-k3s-pro-eelspbtj 0/1 Init:Error 0 91s

Esto se debe al siguiente error, y lo que esta pasando es que nuestra VM no tiene correctamente seteada la CPU, por lo que tenemos ponerla correctamente o en modo host (o x86_64-v2) en nuestro KVM.

Fatal glibc error: CPU does not support x86-64-v2

La ISO no arranca

Si la ISO no arranca es muy probable que no estemos hayamos selecciondo bien nuestra BIOS en el KVM, tenemos que usar una UEFI y por consiguiente si usamos Proxmox es necesario añadir el disco EFI.