Rol de Ansible: k3s (v3.x)

Rol de Ansible para instalar K3S ("Kubernetes Ligero") como un servidor independiente o en un clúster.

¡Se Busca Ayuda!

¡Hola! :wave: @xanmanning está buscando un nuevo mantenedor para trabajar en este rol de Ansible. Esto se debe a que ya no tengo tanto tiempo libre y ya no escribo Ansible regularmente en mi trabajo. Si estás interesado, contáctate.

Notas de la versión

Por favor, consulta Releases y CHANGELOG.md.

Requisitos

El host en el que estás ejecutando Ansible requiere las siguientes dependencias de Python:

• python >= 3.6.0 - Ver notas a continuación.
• ansible >= 2.9.16 o ansible-base >= 2.10.4

Puedes instalar las dependencias usando el archivo requirements.txt en este repositorio: pip3 install -r requirements.txt.

Este rol ha sido probado en las siguientes distribuciones de Linux:

• Alpine Linux
• Amazon Linux 2
• Archlinux
• CentOS 8
• Debian 11
• Fedora 31
• Fedora 32
• Fedora 33
• openSUSE Leap 15
• RockyLinux 8
• Ubuntu 20.04 LTS

:warning: Las versiones v3 de este rol solo son compatibles con k3s >= v1.19, para k3s < v1.19 por favor considera actualizar o utilizar las versiones v1.x de este rol.

Antes de actualizar, consulta CHANGELOG para notificaciones de cambios rompedores.

Variables del Rol

Desde K3s v1.19.1+k3s1 ahora puedes configurar K3s usando un archivo de configuración en lugar de variables de entorno o argumentos de línea de comando. La versión 2 de este rol se ha movido al método del archivo de configuración en lugar de llenar un archivo de unidad systemd con argumentos de línea de comando. Puede haber excepciones que se definen en Variables Globales/De Clúster, sin embargo, principalmente estarás configurando k3s mediante archivos de configuración usando las variables k3s_server y k3s_agent.

Ver "Configuración del Servidor (Plano de Control)" y "Configuración del Agente (Trabajador)" a continuación.

Variables Globales/De Clúster

A continuación, se presentan las variables que se establecen contra todos los hosts de la ejecución para consistencia en el entorno. Estas son generalmente configuraciones a nivel de clúster.

Variable	Descripción	Valor por Defecto
k3s_state	Estado de k3s: instalado, iniciado, detenido, descargado, desinstalado, validado.	instalado
k3s_release_version	Usa una versión específica de k3s, ej. v0.2.0. Especifica false para estable.	false
k3s_airgap	Booleano para habilitar instalaciones sin conexión a Internet	false
k3s_config_file	Ubicación del archivo de configuración de k3s.	/etc/rancher/k3s/config.yaml
k3s_build_cluster	Cuando hay varios hosts de ejecución disponibles, intenta agruparlos. Lee las notas a continuación.	true
k3s_registration_address	Dirección de registro fija para nodos. IP o FQDN.	NULL
k3s_github_url	Establece la URL de GitHub desde la cual instalar k3s.	https://github.com/k3s-io/k3s
k3s_api_url	URL para el API de actualizaciones de K3S.	https://update.k3s.io
k3s_install_dir	Directorio de instalación de k3s.	/usr/local/bin
k3s_install_hard_links	Instala usando enlaces duros en lugar de enlaces simbólicos.	false
k3s_server_config_yaml_d_files	Una lista plana de plantillas para complementar la configuración de k3s_server.	[]
k3s_agent_config_yaml_d_files	Una lista plana de plantillas para complementar la configuración de k3s_agent.	[]
k3s_server_manifests_urls	Una lista de URLs para desplegar en el plano de control principal. Lee las notas a continuación.	[]
k3s_server_manifests_templates	Una lista plana de plantillas para desplegar en el plano de control principal.	[]
k3s_server_pod_manifests_urls	Una lista de URLs para instalar manifiestos de pods estáticos en el plano de control. Lee las notas a continuación.	[]
k3s_server_pod_manifests_templates	Una lista plana de plantillas para instalar manifiestos de pods estáticos en el plano de control.	[]
k3s_use_experimental	Permitir el uso de funciones experimentales en k3s.	false
k3s_use_unsupported_config	Permitir el uso de configuraciones no soportadas en k3s.	false
k3s_etcd_datastore	Habilitar el almacenamiento de datos etcd incrustado (lee las notas a continuación).	false
k3s_debug	Habilitar el registro de depuración en el servicio k3s.	false
k3s_registries	Contenido del archivo de configuración de registros.	{ mirrors: {}, configs:{} }

Configuración del Servicio K3S

A continuación, las variables cambian cómo y cuándo se ejecuta el archivo de unidad del servicio systemd para K3S. Usa esto con precaución, por favor consulta la documentación de systemd para más información.

Variable	Descripción	Valor por Defecto
k3s_start_on_boot	Iniciar k3s al arrancar.	true
k3s_service_requires	Lista de unidades de systemd requeridas por la unidad del servicio k3s.	[]
k3s_service_wants	Lista de unidades de systemd "deseadas" para k3s (más débil que "requeridas").	[]*
k3s_service_before	Iniciar k3s antes de una lista definida de unidades de systemd.	[]
k3s_service_after	Iniciar k3s después de una lista definida de unidades de systemd.	[]*
k3s_service_env_vars	Diccionario de variables de entorno a usar dentro del archivo de unidad de systemd.	{}
k3s_service_env_file	Ubicación en el host de un archivo de entorno para incluir.	false**

* La plantilla de unidad systemd siempre especifica network-online.target para wants y after.

** El archivo debe existir ya en el host objetivo, este rol no creará ni gestionará el archivo. Puedes gestionar este archivo fuera del rol con tareas previas en tu playbook de Ansible.

Variables de Grupo/Host

A continuación, se presentan variables que se establecen para hosts individuales o grupos de hosts de Ansible. Normalmente, establecerías estas a nivel de grupo para el plano de control o los nodos trabajadores.

Variable	Descripción	Valor por Defecto
k3s_control_node	Especifica si un host (o grupo de hosts) es parte del plano de control.	false (el rol delegará automáticamente un nodo)
k3s_server	Configuración del servidor (plano de control), consulta notas a continuación.	{}
k3s_agent	Configuración del agente (trabajador), consulta notas a continuación.	{}

Configuración del Servidor (Plano de Control)

El plano de control se configura con la variable de diccionario k3s_server. Por favor, consulta la documentación a continuación para las opciones de configuración:

https://rancher.com/docs/k3s/latest/en/installation/install-options/server-config/

La variable de diccionario k3s_server contendrá banderas de las anteriores (quitar el prefijo --). A continuación hay un ejemplo:

k3s_server:
  datastore-endpoint: postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable
  cluster-cidr: 172.20.0.0/16
  flannel-backend: 'none'  # Esto necesita estar entre comillas
  disable:
    - traefik
    - coredns

Alternativamente, puedes crear un archivo .yaml y leerlo en la variable k3s_server como en el siguiente ejemplo:

k3s_server: "{{ lookup('file', 'path/to/k3s_server.yml') | from_yaml }}"

Consulta la Documentación para ver ejemplos de configuración.

Configuración del Agente (Trabajador)

Los trabajadores se configuran con la variable de diccionario k3s_agent. Por favor, consulta la documentación a continuación para las opciones de configuración:

https://rancher.com/docs/k3s/latest/en/installation/install-options/agent-config

La variable de diccionario k3s_agent contendrá banderas de las anteriores (quitar el prefijo --). A continuación hay un ejemplo:

k3s_agent:
  with-node-id: true
  node-label:
    - "foo=bar"
    - "hello=world"

Alternativamente, puedes crear un archivo .yaml y leerlo en la variable k3s_agent como en el siguiente ejemplo:

k3s_agent: "{{ lookup('file', 'path/to/k3s_agent.yml') | from_yaml }}"

Consulta la Documentación para ver ejemplos de configuración.

Variables de Configuración del Controlador Ansible

Las siguientes variables se usan para cambiar la forma en que se ejecuta el rol en Ansible, particularmente en relación con la escalación de privilegios.

Variable	Descripción	Valor por Defecto
k3s_skip_validation	Saltar todas las tareas que validan la configuración.	false
k3s_skip_env_checks	Saltar todas las tareas que verifican la configuración del entorno.	false
k3s_skip_post_checks	Saltar todas las tareas que verifican el estado posterior a la ejecución.	false
k3s_become	Escalar privilegios de usuario para tareas que necesitan permisos de root.	false

Nota importante sobre Python

Desde la versión 3 de este rol, se requiere Python 3 en el sistema de destino así como en el controlador Ansible. Esto es para asegurar un comportamiento consistente en las tareas de Ansible ya que Python 2 ahora ha llegado al final de su vida útil.

Si los sistemas de destino tienen instalados Python 2 y Python 3, lo más probable es que se seleccione Python 2 por defecto. Para asegurar que se use Python 3 en un objetivo con ambas versiones de Python, asegúrate de que ansible_python_interpreter esté establecido en tu inventario. A continuación hay un ejemplo de inventario:

---

k3s_cluster:
  hosts:
    kube-0:
      ansible_user: ansible
      ansible_host: 10.10.9.2
      ansible_python_interpreter: /usr/bin/python3
    kube-1:
      ansible_user: ansible
      ansible_host: 10.10.9.3
      ansible_python_interpreter: /usr/bin/python3
    kube-2:
      ansible_user: ansible
      ansible_host: 10.10.9.4
      ansible_python_interpreter: /usr/bin/python3

Nota importante sobre k3s_release_version

Si no estableces una k3s_release_version, se instalará la última versión del canal estable de k3s. Si estás desarrollando contra una versión específica de k3s, debes asegurarte de que esto esté configurado en tu configuración de Ansible, ej:

k3s_release_version: v1.19.3+k3s1

También es posible instalar "Canales" específicos de K3s, a continuación algunos ejemplos para k3s_release_version:

k3s_release_version: false             # por defecto a 'stable' canal
k3s_release_version: stable            # última versión 'stable'
k3s_release_version: testing           # última versión 'testing'
k3s_release_version: v1.19             # última versión 'v1.19'
k3s_release_version: v1.19.3+k3s3      # versión específica

# Compromiso específico
# CUIDADO - solo se usa para pruebas - debe tener 40 caracteres
k3s_release_version: 48ed47c4a3e420fa71c18b2ec97f13dc0659778b

Nota importante sobre k3s_install_hard_links

Si estás utilizando el controlador de actualización del sistema deberás usar enlaces duros en lugar de enlaces simbólicos ya que el controlador no podrá seguir enlaces simbólicos. Esta opción se ha añadido, sin embargo no está habilitada por defecto para evitar romper instalaciones existentes.

Para habilitar el uso de enlaces duros, asegúrate de que k3s_install_hard_links esté establecido en true.

k3s_install_hard_links: true

El resultado de esto puede verse ejecutando lo siguiente en k3s_install_dir:

ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE ".sh$" | sort

Enlaces simbólicos:

[root@node1 bin]# ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE ".sh$" | sort
3277823 -rwxr-xr-x 1 root root  52M Jul 25 12:50 k3s-v1.18.4+k3s1
3279565 lrwxrwxrwx 1 root root   31 Jul 25 12:52 k3s -> /usr/local/bin/k3s-v1.18.6+k3s1
3279644 -rwxr-xr-x 1 root root  51M Jul 25 12:52 k3s-v1.18.6+k3s1
3280079 lrwxrwxrwx 1 root root   31 Jul 25 12:52 ctr -> /usr/local/bin/k3s-v1.18.6+k3s1
3280080 lrwxrwxrwx 1 root root   31 Jul 25 12:52 crictl -> /usr/local/bin/k3s-v1.18.6+k3s1
3280081 lrwxrwxrwx 1 root root   31 Jul 25 12:52 kubectl -> /usr/local/bin/k3s-v1.18.6+k3s1

Enlaces duros:

[root@node1 bin]# ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE ".sh$" | sort
3277823 -rwxr-xr-x 1 root root  52M Jul 25 12:50 k3s-v1.18.4+k3s1
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 crictl
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 ctr
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 k3s
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 k3s-v1.18.6+k3s1
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 kubectl

Nota importante sobre k3s_build_cluster

Si estableces k3s_build_cluster en false, este rol instalará cada host de ejecución como un nodo independiente. Un ejemplo de cuándo podrías usar esto sería al construir una gran cantidad de dispositivos IoT independientes ejecutando K3s. A continuación un escenario hipotético donde vamos a desplegar 25 dispositivos Raspberry Pi, cada uno como un sistema independiente y no como un clúster de 25 nodos. Para hacer esto usaríamos un playbook similar al siguiente:

- hosts: k3s_nodes  # ej. 25 RPi's definidos en nuestro inventario.
  vars:
    k3s_build_cluster: false
  roles:
     - xanmanning.k3s

Nota importante sobre k3s_control_node y Alta Disponibilidad (HA)

Por defecto, solo se definirá un host como nodo de control por Ansible. Si no configuras un host como nodo de control, este rol delegará automáticamente el primer host de ejecución como nodo de control. Esto no es adecuado para ser utilizado en una carga de trabajo de Producción.

Si varios hosts tienen k3s_control_node establecido en true, debes también establecer datastore-endpoint en k3s_server como la cadena de conexión a una base de datos MySQL o PostgreSQL, o un clúster Etcd externo, de lo contrario, la ejecución fallará.

Si usas TLS, el CA, Certificado y Clave deben estar disponibles en los hosts de ejecución.

Consulta: Alta Disponibilidad con una Base de Datos Externa

También es posible, aunque no soportado, ejecutar un único nodo de control K3s con un datastore-endpoint definido. Como esta no es una configuración normalmente soportada, deberás establecer k3s_use_unsupported_config en true.

Desde K3s v1.19.1, es posible usar un Etcd incrustado como la base de datos de backend, y esto se hace estableciendo k3s_etcd_datastore en true. La mejor práctica para Etcd es definir al menos 3 miembros para asegurar que se establezca un quórum. Además de esto, se recomienda un número impar de miembros para asegurar una mayoría en caso de una partición de red. Si deseas usar 2 miembros o un número par de miembros, por favor establece k3s_use_unsupported_config en true.

Nota importante sobre k3s_server_manifests_urls y k3s_server_pod_manifests_urls

Para desplegar manifiestos de servidor y pod desde URLs, debes especificar una url y opcionalmente un filename (si no se proporciona, se usa el nombre base). A continuación hay un ejemplo de cómo desplegar el operador de Tigera para Calico y kube-vip.

---

k3s_server_manifests_urls:
  - url: https://docs.projectcalico.org/archive/v3.19/manifests/tigera-operator.yaml
    filename: tigera-operator.yaml

k3s_server_pod_manifests_urls:
  - url: https://raw.githubusercontent.com/kube-vip/kube-vip/main/example/deploy/0.1.4.yaml
    filename: kube-vip.yaml

Nota importante sobre k3s_airgap

Al desplegar k3s en un entorno sin conexión a Internet, debes proporcionar el binario de k3s en ./files/. El binario no se descargará desde GitHub y, por lo tanto, no se verificará usando la suma de verificación sha256 proporcionada, ni se podrá verificar la versión que estás ejecutando. Todos los riesgos y cargas asociados son asumidos por el usuario en este escenario.

Dependencias

No depende de otros roles.

Ejemplos de Playbooks

Ejemplo de playbook, nodo de control único ejecutando k3s del canal testing:

- hosts: k3s_nodes
  vars:
    k3s_release_version: testing
  roles:
     - role: xanmanning.k3s

Ejemplo de playbook, Alta Disponibilidad con base de datos PostgreSQL ejecutando la última versión estable:

- hosts: k3s_nodes
  vars:
    k3s_registration_address: loadbalancer  # Normalmente un balanceador de carga.
    k3s_server:
      datastore-endpoint: "postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable"
  pre_tasks:
    - name: Establecer cada nodo como un nodo de control
      ansible.builtin.set_fact:
        k3s_control_node: true
      when: inventory_hostname in ['node2', 'node3']
  roles:
    - role: xanmanning.k3s

Licencia

BSD 3-cláusulas

Contribuidores

Las contribuciones de la comunidad son muy bienvenidas, pero por favor lee las guías de contribución antes de hacerlo, esto ayudará a que todo sea lo más fluido posible.

Además, por favor revisa la increíble lista de contribuyentes.

Información del autor

Xan Manning