Rôle Ansible : k3s (v3.x)

Rôle Ansible pour installer K3S ("Kubernetes léger") en tant que serveur autonome ou cluster.

Aide Demandée !

Salut ! :wave: @xanmanning cherche un nouveau mainteneur pour travailler sur ce rôle Ansible. Je n'ai plus autant de temps libre et je n'écris plus d'Ansible régulièrement pour mon travail. Si cela vous intéresse, contactez-moi.

Notes de Version

Veuillez consulter Releases et CHANGELOG.md.

Exigences

L'hôte sur lequel vous exécutez Ansible doit avoir les dépendances Python suivantes :

• python >= 3.6.0 - Voir les notes ci-dessous.
• ansible >= 2.9.16 ou ansible-base >= 2.10.4

Vous pouvez installer les dépendances à l'aide du fichier requirements.txt dans ce dépôt : pip3 install -r requirements.txt.

Ce rôle a été testé sur les distributions Linux suivantes :

• 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: Les versions v3 de ce rôle ne prennent en charge que k3s >= v1.19. Pour k3s < v1.19, veuillez envisager de mettre à jour ou d'utiliser les versions v1.x de ce rôle.

Avant de procéder à la mise à niveau, consultez le CHANGELOG pour les notifications de changements majeurs.

Variables du Rôle

Depuis K3s v1.19.1+k3s1, vous pouvez maintenant configurer K3s à l'aide d'un fichier de configuration plutôt que des variables d'environnement ou des arguments en ligne de commande. La version v2 de ce rôle utilise la méthode du fichier de configuration au lieu de peupler un fichier d'unité systemd avec des arguments en ligne de commande. Il peut y avoir des exceptions définies dans Global/Cluster Variables, mais vous configurerez principalement k3s via des fichiers de configuration en utilisant les variables k3s_server et k3s_agent.

Voir "Configuration du Serveur (Plan de Contrôle)" et "Configuration de l'Agent (Travailleur)" ci-dessous.

Variables Globales/Cluster

Voici les variables définies pour tous les hôtes afin d'assurer une cohérence environnementale. Ce sont généralement des configurations au niveau du cluster.

Variable	Description	Valeur par Défaut
k3s_state	État de k3s : installé, démarré, arrêté, téléchargé, désinstallé, validé.	installé
k3s_release_version	Utiliser une version spécifique de k3s, par exemple v0.2.0. Spécifiez false pour stable.	false
k3s_airgap	Booléen pour activer les installations hors ligne	false
k3s_config_file	Emplacement du fichier de configuration k3s.	/etc/rancher/k3s/config.yaml
k3s_build_cluster	Lorsque plusieurs hôtes de lecture sont disponibles, tenter de créer un cluster. Lisez les notes ci-dessous.	true
k3s_registration_address	Adresse d'enregistrement fixe pour les nœuds. IP ou FQDN.	NULL
k3s_github_url	Définir l'URL GitHub pour installer k3s.	https://github.com/k3s-io/k3s
k3s_api_url	URL pour l'API des mises à jour de K3S.	https://update.k3s.io
k3s_install_dir	Répertoire d'installation pour k3s.	/usr/local/bin
k3s_install_hard_links	Installer en utilisant des liens durs plutôt que des liens symboliques.	false
k3s_server_config_yaml_d_files	Liste plate de modèles pour compléter la configuration k3s_server.	[]
k3s_agent_config_yaml_d_files	Liste plate de modèles pour compléter la configuration k3s_agent.	[]
k3s_server_manifests_urls	Liste d'URLs à déployer sur le plan de contrôle principal. Lisez les notes ci-dessous.	[]
k3s_server_manifests_templates	Liste plate de modèles à déployer sur le plan de contrôle principal.	[]
k3s_server_pod_manifests_urls	Liste d'URLs pour installer des manifestes de pods statiques sur le plan de contrôle. Lisez les notes ci-dessous.	[]
k3s_server_pod_manifests_templates	Liste plate de modèles pour installer des manifestes de pods statiques sur le plan de contrôle.	[]
k3s_use_experimental	Autoriser l'utilisation de fonctionnalités expérimentales dans k3s.	false
k3s_use_unsupported_config	Autoriser l'utilisation de configurations non prises en charge dans k3s.	false
k3s_etcd_datastore	Activer le datastore etcd intégré (lisez les notes ci-dessous).	false
k3s_debug	Activer la journalisation de débogage sur le service k3s.	false
k3s_registries	Contenu du fichier de configuration des registres.	{ mirrors: {}, configs:{} }

Configuration du Service K3S

Les variables ci-dessous modifient la manière et le moment où le fichier d'unité de service systemd pour K3S est exécuté. Utilisez cela avec prudence, veuillez vous référer à la documentation systemd pour plus d'informations.

Variable	Description	Valeur par Défaut
k3s_start_on_boot	Démarrer k3s au démarrage.	true
k3s_service_requires	Liste des unités systemd requises pour l'unité de service k3s.	[]
k3s_service_wants	Liste des unités systemd "souhaitées" pour k3s (moins strict que "requires").	[] *
k3s_service_before	Démarrer k3s avant une liste définie d'unités systemd.	[]
k3s_service_after	Démarrer k3s après une liste définie d'unités systemd.	[] *
k3s_service_env_vars	Dictionnaire des variables d'environnement à utiliser dans le fichier d'unité systemd.	{}
k3s_service_env_file	Emplacement sur l'hôte d'un fichier d'environnement à inclure.	false **

* Le modèle d'unité systemd spécifie toujours network-online.target pour wants et after.

** Le fichier doit déjà exister sur l'hôte cible, ce rôle ne créera ni ne gérera le fichier. Vous pouvez gérer ce fichier en dehors du rôle avec des pré-tâches dans votre playbook Ansible.

Variables de Groupe/Hôte

Voici les variables qui sont définies pour des hôtes individuels ou des groupes d'hôtes. Typiquement, vous définiriez cela au niveau du groupe pour le plan de contrôle ou les nœuds de travail.

Variable	Description	Valeur par Défaut
k3s_control_node	Spécifiez si un hôte (ou un groupe d'hôtes) fait partie du plan de contrôle.	false (le rôle déléguera automatiquement un nœud)
k3s_server	Configuration du serveur (plan de contrôle), voir les notes ci-dessous.	{}
k3s_agent	Configuration de l'agent (travailleur), voir les notes ci-dessous.	{}

Configuration du Serveur (Plan de Contrôle)

Le plan de contrôle est configuré avec la variable de dictionnaire k3s_server. Veuillez vous référer à la documentation ci-dessous pour les options de configuration :

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

La variable de dictionnaire k3s_server contiendra des drapeaux des options ci-dessus (en supprimant le préfixe --). Voici un exemple :

k3s_server:
  datastore-endpoint: postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable
  cluster-cidr: 172.20.0.0/16
  flannel-backend: 'none'  # Cela doit être entre guillemets
  disable:
    - traefik
    - coredns

Alternativement, vous pouvez créer un fichier .yaml et le lire dans la variable k3s_server comme dans l'exemple ci-dessous :

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

Consultez la documentation pour un exemple de configuration.

Configuration de l'Agent (Travailleur)

Les agents sont configurés avec la variable de dictionnaire k3s_agent. Veuillez consulter la documentation ci-dessous pour les options de configuration :

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

La variable de dictionnaire k3s_agent contiendra des drapeaux des options ci-dessus (en retirant le préfixe --). Voici un exemple :

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

Alternativement, vous pouvez créer un fichier .yaml et le lire dans la variable k3s_agent comme dans l'exemple ci-dessous :

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

Consultez la documentation pour un exemple de configuration.

Variables de Configuration du Contrôleur Ansible

Les variables ci-dessous sont utilisées pour modifier la manière dont le rôle s'exécute dans Ansible, en particulier concernant l'élévation de privilèges.

Variable	Description	Valeur par Défaut
k3s_skip_validation	Ignorer toutes les tâches qui valident la configuration.	false
k3s_skip_env_checks	Ignorer toutes les tâches qui vérifient la configuration de l'environnement.	false
k3s_skip_post_checks	Ignorer toutes les tâches qui vérifient l'état après l'exécution.	false
k3s_become	Élève les privilèges d'utilisateur pour les tâches nécessitant des permissions root.	false

Important à propos de Python

Depuis la version 3 de ce rôle, Python 3 est requis sur le système cible ainsi que sur le contrôleur Ansible. Cela garantit un comportement cohérent pour les tâches Ansible, car Python 2 n'est plus maintenu.

Si les systèmes cibles ont à la fois Python 2 et Python 3 installés, il est probable que Python 2 soit sélectionné par défaut. Pour vous assurer que Python 3 est utilisé sur un système cible avec les deux versions de Python, assurez-vous que ansible_python_interpreter est défini dans votre inventaire. Voici un exemple d'inventaire :

---

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

Important à propos de k3s_release_version

Si vous ne définissez pas de k3s_release_version, la dernière version stable de k3s sera installée. Si vous développez contre une version spécifique de k3s, vous devez vous assurer que cela est défini dans votre configuration Ansible, par exemple :

k3s_release_version: v1.19.3+k3s1

Il est également possible d'installer des "canaux" spécifiques de K3s, voici quelques exemples pour k3s_release_version :

k3s_release_version: false             # par défaut 'stable'
k3s_release_version: stable            # dernière version 'stable'
k3s_release_version: testing           # dernière version 'testing'
k3s_release_version: v1.19             # dernière version 'v1.19'
k3s_release_version: v1.19.3+k3s3      # version spécifique

# Commit spécifique
# ATTENTION - à utiliser uniquement pour les tests - doit comporter 40 caractères
k3s_release_version: 48ed47c4a3e420fa71c18b2ec97f13dc0659778b

Important à propos de k3s_install_hard_links

Si vous utilisez le system-upgrade-controller, vous devrez utiliser des liens durs plutôt que des liens symboliques, car le contrôleur ne pourra pas suivre les liens symboliques. Cette option a été ajoutée mais n'est pas activée par défaut pour éviter de casser les installations existantes.

Pour activer l'utilisation de liens durs, assurez-vous que k3s_install_hard_links est défini sur true.

k3s_install_hard_links: true

Le résultat de cela peut être vu en exécutant ce qui suit dans k3s_install_dir :

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

Liens symboliques :

[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

Liens durs :

[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

Important à propos de k3s_build_cluster

Si vous définissez k3s_build_cluster sur false, ce rôle installera chaque hôte de jeu comme un nœud autonome. Un exemple d'une telle situation serait lors de la création d'un grand nombre de dispositifs IoT autonomes exécutant K3s. Voici un exemple hypothétique où nous devons déployer 25 appareils Raspberry Pi, chacun agissant comme un système autonome et non en tant que cluster de 25 nœuds. Pour cela, nous utiliserions un playbook similaire à celui-ci :

- hosts: k3s_nodes  # par ex. 25 RPi définis dans notre inventaire.
  vars:
    k3s_build_cluster: false
  roles:
     - xanmanning.k3s

Important à propos de k3s_control_node et haute disponibilité (HA)

Par défaut, seul un hôte sera défini comme nœud de contrôle par Ansible. Si vous ne définissez pas un hôte comme nœud de contrôle, ce rôle déléguera automatiquement le premier hôte de jeu comme nœud de contrôle. Ceci n'est pas adapté à un environnement de production.

Si plusieurs hôtes ont k3s_control_node défini sur true, vous devez également définir datastore-endpoint dans k3s_server comme chaîne de connexion à une base de données MySQL ou PostgreSQL, ou un cluster Etcd externe, sinon le play échouera.

Si vous utilisez TLS, le CA, le certificat et la clé doivent déjà être disponibles sur les hôtes de jeu.

Voir : Haute disponibilité avec une base de données externe

Il est également possible, bien que non pris en charge, d'exécuter un seul nœud de contrôle K3s avec un datastore-endpoint défini. Comme cela n'est pas une configuration habituellement prise en charge, vous devrez définir k3s_use_unsupported_config sur true.

Depuis K3s v1.19.1, il est possible d'utiliser un Etcd intégré comme base de données de backend, ce qui se fait en définissant k3s_etcd_datastore sur true. La meilleure pratique pour Etcd est de définir au moins 3 membres pour garantir qu'un quorum soit établi. De plus, un nombre impair est recommandé pour assurer une majorité en cas de partitionnement du réseau. Si vous souhaitez utiliser 2 membres ou un nombre pair de membres, veuillez définir k3s_use_unsupported_config sur true.

Important à propos de k3s_server_manifests_urls et k3s_server_pod_manifests_urls

Pour déployer des manifestes de serveur et des manifestes de pods de serveur à partir d'URL, vous devez spécifier un url et éventuellement un filename (si aucun n'est fourni, le nom de base est utilisé). Voici un exemple de déploiement de l'opérateur Tigera pour Calico et 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

Important à propos de k3s_airgap

Lors du déploiement de k3s dans un environnement isolé, vous devez fournir le binaire k3s dans ./files/. Le binaire ne sera pas téléchargé depuis GitHub et ne sera donc pas vérifié à l'aide de la somme sha256 fournie, ni capable de vérifier la version que vous exécutez. Tous les risques et responsabilités qui en découlent sont sous la responsabilité de l'utilisateur dans ce scénario.

Dépendances

Pas de dépendances sur d'autres rôles.

Exemples de Playbooks

Exemple de playbook, un seul nœud de contrôle exécutant la version de test de k3s :

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

Exemple de playbook, haute disponibilité avec base de données PostgreSQL exécutant la dernière version stable :

- hosts: k3s_nodes
  vars:
    k3s_registration_address: loadbalancer  # Typiquement un équilibreur de charge.
    k3s_server:
      datastore-endpoint: "postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable"
  pre_tasks:
    - name: Définir chaque nœud comme nœud de contrôle
      ansible.builtin.set_fact:
        k3s_control_node: true
      when: inventory_hostname in ['node2', 'node3']
  roles:
    - role: xanmanning.k3s

Licence

BSD 3-clauses

Contributeurs

Les contributions de la communauté sont les bienvenues, mais veuillez lire les directives de contribution avant de le faire, cela aidera à rendre les choses aussi simples que possible.

De plus, veuillez consulter la superbe liste des contributeurs.

Informations sur l'Auteur

Xan Manning