Rol de Ansible para RKE2

Este rol de Ansible desplegará un clúster de Kubernetes RKE2. RKE2 se instalará utilizando el método de tarball.

El rol puede instalar RKE2 en 3 modos:

• Nodo único de RKE2

• Clúster de RKE2 con un nodo servidor (maestro) y uno o más nodos agente (trabajador)

• Clúster de RKE2 con servidor (maestro) en modo de alta disponibilidad y cero o más nodos agente (trabajador). En modo HA, debes tener un número impar de nodos servidor (se recomiendan tres) que ejecutarán etcd, la API de Kubernetes (dirección VIP de Keepalived o Kube-VIP) y otros servicios del plano de control.

---

• Además, es posible instalar el clúster de RKE2 (los 3 modos) en funcionalidad aislada utilizando artefactos locales.

Es posible actualizar RKE2 cambiando la variable rke2_version y volviendo a ejecutar el playbook con este rol. Durante el proceso de actualización, el servicio de RKE2 en los nodos se reiniciará uno por uno. El rol de Ansible verificará si el nodo en el que se reinició el servicio está en estado listo y solo luego procederá a reiniciar el servicio en otro nodo de Kubernetes.

Requisitos

• Ansible 2.10+

Probado en

• Rocky Linux 9
• Ubuntu 24.04 LTS

Variables del rol

Esta es una copia de defaults/main.yml

---
# Tipo de nodo - servidor o agente
rke2_type: server

# Desplegar el plano de control en modo HA
rke2_ha_mode: false

# Instalar y configurar Keepalived en nodos Servidor
# Se puede desactivar si usas un balanceador de carga preconfigurado
rke2_ha_mode_keepalived: true

# Instalar y configurar kube-vip LB y VIP para el clúster
# rke2_ha_mode_keepalived necesita ser falso
rke2_ha_mode_kubevip: false

# Dirección IP de la API de Kubernetes y registro de RKE2. La dirección predeterminada es la IPv4 del nodo Servidor/Maestro.
# En modo HA, elige una IP estática que se establecerá como VIP en keepalived.
# O si keepalived está deshabilitado, usa la dirección IP de tu LB.
rke2_api_ip: "{{ hostvars[groups[rke2_servers_group_name].0]['ansible_default_ipv4']['address'] }}"

# opción opcional para que el Servidor de RKE2 escuche en una dirección IP privada en el puerto 9345
# rke2_api_private_ip:

# opcional opción para subnet de kubevip
# rke2_api_cidr: 24

# opcional opción para kubevip
# rke2_interface: eth0
# opcional opción para direcciones IPv4/IPv6 a anunciar para el nodo
# rke2_bind_address: "{{ hostvars[inventory_hostname]['ansible_' + rke2_interface]['ipv4']['address'] }}"

# rango de IP del balanceador de carga kubevip
rke2_loadbalancer_ip_range: {}
#  rango-global: 192.168.1.50-192.168.1.100
#  cidr-finance: 192.168.0.220/29,192.168.0.230/29

# Instalar el proveedor de nube kubevip si rke2_ha_mode_kubevip es verdadero
rke2_kubevip_cloud_provider_enable: true

# Habilitar kube-vip para observar Servicios de tipo LoadBalancer
rke2_kubevip_svc_enable: true

# Especificar qué imagen se usa para el contenedor kube-vip
rke2_kubevip_image: ghcr.io/kube-vip/kube-vip:v0.6.4

# Especificar qué imagen se usa para el contenedor del proveedor de nube kube-vip
rke2_kubevip_cloud_provider_image: ghcr.io/kube-vip/kube-vip-cloud-provider:v0.0.4

# Habilitar kube-vip IPVS para el plano de control
rke2_kubevip_ipvs_lb_enable: false
# Habilitar balanceo de carga de capa 4 para el plano de control utilizando el módulo de kernel IPVS
# Debe usar kube-vip versión 0.4.0 o posterior

rke2_kubevip_service_election_enable: true
# Por defecto, el modo ARP proporciona una implementación HA de un VIP (tu dirección IP de servicio) que recibirá tráfico en el líder de kube-vip.
# Para eludir esto, kube-vip ha implementado una nueva función que es "elección de líder por servicio",
# en lugar de que un nodo se convierta en el líder para todos los servicios, se realiza una elección entre todas las instancias de kube-vip y el líder de esa elección se convierte en el titular de ese servicio. En última instancia,
# esto significa que cada servicio puede terminar en un nodo diferente cuando se crea, en teoría evitando un cuello de botella en el despliegue inicial.
# versión mínima de kube-vip 0.5.0

# (Opcional) Una lista de flags de kube-vip
# Todos los flags pueden encontrarse aquí https://kube-vip.io/docs/installation/flags/
# rke2_kubevip_args: []
# - param: lb_enable
#   value: true
# - param: lb_port
#   value: 6443

# Puerto de métricas de Prometheus para kube-vip
rke2_kubevip_metrics_port: 2112

# Agregar SAN adicionales en el certificado TLS de la API de k8s
rke2_additional_sans: []

# Configurar el dominio del clúster
# rke2_cluster_domain: cluster.example.net

# Puerto de destino del servidor API
rke2_apiserver_dest_port: 6443

# Tintes de nodos Servidor
rke2_server_node_taints: []
  # - 'CriticalAddonsOnly=true:NoExecute'

# Tintes de nodos Agente
rke2_agent_node_taints: []

# Token secreto compartido que otros nodos servidor o agente usarán para registrarse al conectar con el clúster
rke2_token: defaultSecret12345

# Versión de RKE2
rke2_version: v1.25.3+rke2r1

# URL al repositorio de RKE2
rke2_channel_url: https://update.rke2.io/v1-release/channels

# URL del script de instalación de RKE2
# por ejemplo, espejo chino de rancher http://rancher-mirror.rancher.cn/rke2/install.sh
rke2_install_bash_url: https://get.rke2.io

# Directorio de datos local para RKE2
rke2_data_path: /var/lib/rancher/rke2

# URL predeterminada para obtener artefactos
rke2_artifact_url: https://github.com/rancher/rke2/releases/download/

# Ruta local para almacenar artefactos
rke2_artifact_path: /rke2/artifact

# Artefactos requeridos para airgap
rke2_artifact:
  - sha256sum-{{ rke2_architecture }}.txt
  - rke2.linux-{{ rke2_architecture }}.tar.gz
  - rke2-images.linux-{{ rke2_architecture }}.tar.zst

# Cambia la estrategia de despliegue para instalar basándose en artefactos locales
rke2_airgap_mode: false

# Tipo de implementación de airgap - descarga, copia o existe
# - 'download' descargará los artefactos en cada nodo,
# - 'copy' transferirá archivos locales en 'rke2_artifact' a los nodos,
# - 'exists' asume que los archivos de 'rke2_artifact' ya están almacenados en 'rke2_artifact_path'
rke2_airgap_implementation: download

# Ruta de origen local donde se almacenan los artefactos
rke2_airgap_copy_sourcepath: local_artifacts

# Imágenes en tarball para componentes adicionales que se copian de rke2_airgap_copy_sourcepath a los nodos
# (Las extensiones de archivo en la lista y en los archivos reales deben conservarse)
rke2_airgap_copy_additional_tarballs: []

# Destino para imágenes adicionales en tarball para airgap (ver https://docs.rke2.io/install/airgap/#tarball-method)
rke2_tarball_images_path: "{{ rke2_data_path }}/agent/images"

# Arquitectura a descargar, actualmente hay lanzamientos para amd64 y s390x
rke2_architecture: amd64

# Directorio de destino para el script de instalación de RKE2
rke2_install_script_dir: /var/tmp

# Canal de RKE2
rke2_channel: stable

# No desplegar componentes empaquetados y eliminar cualquier componente desplegado
# Elementos válidos: rke2-canal, rke2-coredns, rke2-ingress-nginx, rke2-metrics-server
rke2_disable:

# Opción para deshabilitar kube-proxy
disable_kube_proxy: false

# Opción para deshabilitar el controlador de nube integrado - principalmente para on-prem
rke2_disable_cloud_controller: false

# Proveedor de nube a usar para el clúster (aws, azure, gce, openstack, vsphere, externo)
# aplicable solo si rke2_disable_cloud_controller es verdadero
rke2_cloud_provider_name: "external"

# Ruta a manifiestos personalizados desplegados durante la instalación de RKE2
# Es posible usar plantillas Jinja2 en los manifiestos
rke2_custom_manifests:

# Ruta a pods estáticos desplegados durante la instalación de RKE2
rke2_static_pods:

# Configurar registro de mirros personalizado para Containerd
rke2_custom_registry_mirrors: []
  # - name:
  #   endpoint: {}
#   rewrite: '"^rancher/(.*)": "mirrorproject/rancher-images/$1"'

# Configurar configuración adicional del registro de Containerd
rke2_custom_registry_configs: []
#   - endpoint:
#     config:

# Ruta a la plantilla de archivo de configuración del registro de contenedores
rke2_custom_registry_path: templates/registries.yaml.j2

# Ruta a la plantilla del archivo de configuración de RKE2
rke2_config: templates/config.yaml.j2

# Directorio de origen de instantáneas de etcd
rke2_etcd_snapshot_source_dir: etcd_snapshots

# Nombre del archivo de instantánea de etcd.
# Cuando se define el nombre del archivo, el etcd se restaurará en el primer despliegue del run de Ansible.
# El etcd solo se restaurará durante el primer run, por lo que incluso si dejas definido el nombre del archivo,
# el etcd permanecerá sin tocarse en los siguientes runs.
# Puedes usar esto o configurar opciones en `rke2_etcd_snapshot_s3_options`
rke2_etcd_snapshot_file:

# Ubicación de la instantánea de etcd
rke2_etcd_snapshot_destination_dir: "{{ rke2_data_path }}/server/db/snapshots"

# Opciones para instantáneas de etcd en S3
# Establecer todos estos valores o `rke2_etcd_snapshot_file` y `rke2_etcd_snapshot_source_dir`

# rke2_etcd_snapshot_s3_options:
  # s3_endpoint: "" # requerido
  # access_key: "" # requerido
  # secret_key: "" # requerido
  # bucket: "" # requerido.
  # snapshot_name: "" # requerido.
  # skip_ssl_verify: false # opcional
  # endpoint_ca: "" # opcional. Se puede omitir si se usan los valores predeterminados
  # region: "" # opcional - predeterminado a us-east-1
  # folder: "" # opcional - predeterminado a nivel superior del bucket
# Sobrescribir el snapshot default de containerd
rke2_snapshooter: overlayfs

# Desplegar RKE2 con CNI canal por defecto
rke2_cni: canal

# Validar la configuración del sistema contra el benchmark seleccionado
# (Valor soportado es "cis-1.23" o eventualmente "cis-1.6" si ejecutas RKE2 antes de 1.25)
rke2_cis_profile: ""

# Descargar archivo de configuración de Kubernetes al controlador de Ansible
rke2_download_kubeconf: false

# Nombre del archivo de configuración de Kubernetes que se descargará al controlador de Ansible
rke2_download_kubeconf_file_name: rke2.yaml

# Directorio de destino donde se descargará el archivo de configuración de Kubernetes al controlador de Ansible
rke2_download_kubeconf_path: /tmp

# Nombre del grupo de inventario predeterminado de Ansible para el clúster RKE2
rke2_cluster_group_name: k8s_cluster

# Nombre del grupo de inventario predeterminado de Ansible para los Servidores RKE2
rke2_servers_group_name: masters

# Nombre del grupo de inventario predeterminado de Ansible para los Agentes RKE2
rke2_agents_group_name: workers

# (Opcional) Una lista de flags del servidor de API de Kubernetes
# Todos los flags pueden encontrarse aquí https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver
# rke2_kube_apiserver_args: []

# (Opcional) Lista de etiquetas para nodos
# k8s_node_label: []

# (Opcional) Opciones de configuración adicionales del servidor RKE2
# Puedes encontrar los flags en https://docs.rke2.io/reference/server_config
# rke2_server_options:
#   - "option: value"
#   - "node-ip: {{ rke2_bind_address }}"  # ex: (agent/networking) Direcciones IPv4/IPv6 a anunciar para nodo

# (Opcional) Opciones de configuración adicionales del agente RKE2
# Puedes encontrar los flags en https://docs.rke2.io/reference/linux_agent_config
# rke2_agent_options:
#   - "option: value"
#   - "node-ip: {{ rke2_bind_address }}"  # ex: (agent/networking) Direcciones IPv4/IPv6 a anunciar para nodo

# (Opcional) Configurar Proxy
# Todos los flags pueden encontrarse aquí https://docs.rke2.io/advanced#configuring-an-http-proxy
# rke2_environment_options: []
#   - "option=value"
#   - "HTTP_PROXY=http://your-proxy.example.com:8888"

# (Opcional) Personalizar argumentos predeterminados del kube-controller-manager
# Esta funcionalidad permite agregar el argumento si no está presente por defecto o reemplazarlo si ya existe.
# rke2_kube_controller_manager_arg:
#   - "bind-address=0.0.0.0"

# (Opcional) Personalizar argumentos predeterminados del kube-scheduler
# Esta funcionalidad permite agregar el argumento si no está presente por defecto o reemplazarlo si ya existe.
# rke2_kube_scheduler_arg:
#   - "bind-address=0.0.0.0"

# (Opcional) Configurar nginx a través de HelmChartConfig: https://docs.rke2.io/networking/networking_services#nginx-ingress-controller
# rke2_ingress_nginx_values:
#   controller:
#     config:
#       use-forwarded-headers: "true"
rke2_ingress_nginx_values: {}

# Cordon, drenar el nodo que se está actualizando. Descordon el nodo una vez que RKE2 se haya actualizado.
rke2_drain_node_during_upgrade: false

# Esperar a que todos los pods estén listos después del reinicio del servicio rke2 durante el reinicio progresivo.
rke2_wait_for_all_pods_to_be_ready: false

# Habilitar modo de depuración (rke2-service)
rke2_debug: false

# (Opcional) Personalizar argumentos predeterminados del kubelet
# rke2_kubelet_arg:
#   - "--system-reserved=cpu=100m,memory=100Mi"

# (Opcional) Personalizar argumentos predeterminados de kube-proxy
# rke2_kube_proxy_arg:
#   - "proxy-mode=ipvs"

# El valor para la opción de configuración del nombre del nodo
rke2_node_name: "{{ inventory_hostname }}"

# la red a usar para Pods. Se establece en '10.42.0.0/16' por defecto.
rke2_cluster_cidr:
  - 10.42.0.0/16

# la red a usar para Servicios ClusterIP. Se establece en '10.43.0.0/16' por defecto.
rke2_service_cidr:
  - 10.43.0.0/16

Ejemplo de archivo de inventario

Este rol se basa en la distribución de nodos en grupos de inventario masters y workers. Los nodos maestros/servidores de Kubernetes de RKE2 deben pertenecer al grupo masters y los nodos trabajadores/agentes deben ser miembros del grupo workers. Ambos grupos deben ser los hijos del grupo k8s_cluster.

[masters]
master-01 ansible_host=192.168.123.1 rke2_type=server
master-02 ansible_host=192.168.123.2 rke2_type=server
master-03 ansible_host=192.168.123.3 rke2_type=server

[workers]
worker-01 ansible_host=192.168.123.11 rke2_type=agent
worker-02 ansible_host=192.168.123.12 rke2_type=agent
worker-03 ansible_host=192.168.123.13 rke2_type=agent

[k8s_cluster:children]
masters
workers

Ejemplo de Playbook

Este playbook desplegará RKE2 en un solo nodo actuando como servidor y agente.

- name: Desplegar RKE2
  hosts: node
  become: yes
  roles:
     - role: lablabs.rke2

Este playbook desplegará RKE2 en un clúster con un servidor (maestro) y varios nodos agentes (trabajadores).

- name: Desplegar RKE2
  hosts: all
  become: yes
  roles:
     - role: lablabs.rke2

Este playbook desplegará RKE2 en un clúster con un servidor (maestro) y varios nodos agentes (trabajadores) en modo de airgap. Usará Multus y Calico como CNI.

- name: Desplegar RKE2
  hosts: all
  become: yes
  vars:
    rke2_airgap_mode: true
    rke2_airgap_implementation: download
    rke2_cni:
      - multus
      - calico
    rke2_artifact:
      - sha256sum-{{ rke2_architecture }}.txt
      - rke2.linux-{{ rke2_architecture }}.tar.gz
      - rke2-images.linux-{{ rke2_architecture }}.tar.zst
    rke2_airgap_copy_additional_tarballs:
      - rke2-images-multus.linux-{{ rke2_architecture }}
      - rke2-images-calico.linux-{{ rke2_architecture }}
  roles:
     - role: lablabs.rke2

Este playbook desplegará RKE2 en un clúster con un plano de control de servidor (maestro) HA y varios nodos agentes (trabajadores). Los nodos (maestros) del servidor serán teñidos, por lo que la carga de trabajo se distribuirá solo en nodos trabajadores (agentes). El rol también instalará Keepalived en los nodos del plano de control y configurará la dirección VIP donde será accesible la API de Kubernetes. También descargará el archivo de configuración de Kubernetes a la máquina local.

- name: Desplegar RKE2
  hosts: all
  become: yes
  vars:
    rke2_ha_mode: true
    rke2_api_ip : 192.168.123.100
    rke2_download_kubeconf: true
    rke2_server_node_taints:
      - 'CriticalAddonsOnly=true:NoExecute'
  roles:
     - role: lablabs.rke2

Tener un token separado para nodos agentes

Según la documentación de configuración del servidor, es posible definir un token de agente, que será utilizado por los nodos agentes para conectarse al clúster, dándoles menos acceso al clúster que los nodos servidores. Las siguientes modificaciones serían necesarias en la configuración anterior:

• eliminar rke2_token de las variables globales
• agregar a group_vars/masters.yml:

rke2_token: defaultSecret12345
rke2_agent_token: agentSecret54321

• agregar a group_vars/workers.yml:

rke2_token: agentSecret54321

Si bien cambiar el token del servidor es problemático, el token del agente se puede rotar a voluntad, siempre que los servidores y los agentes tengan el mismo valor y los servicios (rke2-server y rke2-agent, según corresponda) se hayan reiniciado para asegurarse de que los procesos usen el nuevo valor.

Solución de problemas

Playbook atascado mientras inicia el servicio RKE2 en agentes

Si el playbook comienza a bloquearse en la tarea Iniciar servicio RKE2 en el resto de los nodos y luego falla en la tarea Esperar que los nodos restantes estén listos, probablemente tengas algunas limitaciones en la red de tus nodos.

Por favor verifica las Reglas de Entrada requeridas para los Nodos Servidor de RKE2 en el siguiente enlace: https://docs.rke2.io/install/requirements/#networking.

Licencia

MIT

Información del Autor

Creado en 2021 por Labyrinth Labs