Ansible Rolle: k3s (v3.x)

Ansible Rolle zur Installation von K3S ("Leichtgewichtiges Kubernetes") als eigenständiger Server oder Cluster.

Hilfe Gesucht!

Hallo! :wave: @xanmanning sucht eine neue Betreuung für diese Ansible Rolle. Ich habe nicht mehr so viel Freizeit und schreibe Ansible nicht mehr regelmäßig in meinem Job. Wenn du interessiert bist, melde dich.

Versionshinweise

Bitte sieh dir die Releases und CHANGELOG.md an.

Anforderungen

Der Host, auf dem du Ansible ausführst, benötigt folgende Python-Abhängigkeiten:

• python >= 3.6.0 - Siehe Hinweise weiter unten.
• ansible >= 2.9.16 oder ansible-base >= 2.10.4

Du kannst Abhängigkeiten mit der requirements.txt Datei in diesem Repository installieren: pip3 install -r requirements.txt.

Diese Rolle wurde gegen folgende Linux-Distributionen getestet:

• 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: Die v3-Versionen dieser Rolle unterstützen nur k3s >= v1.19. Für k3s < v1.19 solltest du ein Upgrade in Betracht ziehen oder die v1.x-Versionen dieser Rolle verwenden.

Sieh dir vor dem Upgrade den CHANGELOG für wichtige Änderungen an.

Rollenvariablen

Seit K3s v1.19.1+k3s1 kannst du K3s jetzt mit einer Konfigurationsdatei anstelle von Umgebungsvariablen oder Kommandozeilenargumenten konfigurieren. Die v2-Version dieser Rolle verwendet die Methode mit der Konfigurationsdatei, anstelle eine systemd-Einheit mit Kommandozeilenargumenten zu füllen. Es gibt eventuell Ausnahmen, die in Globalen/Cluster-Variablen definiert sind, aber im Allgemeinen wirst du k3s hauptsächlich durch Konfigurationsdateien mit den Variablen k3s_server und k3s_agent konfigurieren.

Siehe "Server (Steuerplane) Konfiguration" und "Agent (Arbeiter) Konfiguration" weiter unten.

Globale/Cluster-Variablen

Nachfolgend sind Variablen aufgeführt, die für alle Play-Hosts zur Gewährleistung der Konsistenz der Umgebung eingestellt werden. Diese entsprechen in der Regel der Cluster-Konfiguration.

Variable	Beschreibung	Standardwert
k3s_state	Zustand von k3s: installiert, gestartet, gestoppt, heruntergeladen, deinstalliert, validiert.	installiert
k3s_release_version	Eine bestimmte Version von k3s verwenden, z. B. v0.2.0. false für stabil.	false
k3s_airgap	Boolescher Wert zur Aktivierung von Air-Gap-Installationen	false
k3s_config_file	Standort der k3s-Konfigurationsdatei.	/etc/rancher/k3s/config.yaml
k3s_build_cluster	Wenn mehrere Play-Hosts verfügbar sind, versuche, einen Cluster zu bilden. Lies die Hinweise weiter unten.	true
k3s_registration_address	Feste Registrierungsadresse für Knoten. IP oder FQDN.	NULL
k3s_github_url	Setze die GitHub-URL für die Installation von k3s.	https://github.com/k3s-io/k3s
k3s_api_url	URL für die K3S-Updates-API.	https://update.k3s.io
k3s_install_dir	Installationsverzeichnis für k3s.	/usr/local/bin
k3s_install_hard_links	Installation mit Hard Links anstelle von symbolischen Links.	false
k3s_server_config_yaml_d_files	Eine flache Liste von Vorlagen, um die Konfiguration von k3s_server zu ergänzen.	[]
k3s_agent_config_yaml_d_files	Eine flache Liste von Vorlagen, um die Konfiguration von k3s_agent zu ergänzen.	[]
k3s_server_manifests_urls	Eine Liste von URLs für die Bereitstellung auf der primären Steuerplane. Lies die Hinweise weiter unten.	[]
k3s_server_manifests_templates	Eine flache Liste von Vorlagen zur Bereitstellung auf der primären Steuerplane.	[]
k3s_server_pod_manifests_urls	Eine Liste von URLs für die Installation statischer Pod Manifeste auf der Steuerplane. Lies die Hinweise unten.	[]
k3s_server_pod_manifests_templates	Eine flache Liste von Vorlagen zur Installation statischer Pod Manifeste auf der Steuerplane.	[]
k3s_use_experimental	Erlauben der Verwendung experimenteller Funktionen in k3s.	false
k3s_use_unsupported_config	Erlauben der Verwendung nicht unterstützter Konfigurationen in k3s.	false
k3s_etcd_datastore	Aktivieren der integrierten etcd-Datenbank (Hinweise weiter unten lesen).	false
k3s_debug	Aktivieren des Debug-Loggings für den k3s-Dienst.	false
k3s_registries	Inhalt der Konfigurationsdatei für Registries.	{ mirrors: {}, configs:{} }

K3S Dienstkonfiguration

Die folgenden Variablen ändern, wie und wann die systemd-Diensteinheit für K3S ausgeführt wird. Bitte mit Vorsicht verwenden, siehe die systemd-Dokumentation für weitere Informationen.

Variable	Beschreibung	Standardwert
k3s_start_on_boot	K3s beim Booten starten.	true
k3s_service_requires	Liste der erforderlichen systemd-Einheiten für die k3s-Diensteinheit.	[]
k3s_service_wants	Liste von "gewünschten" systemd-Einheiten für k3s (schwächer als "erfordert").	[]*
k3s_service_before	Starte k3s vor einer definierten Liste von systemd-Einheiten.	[]
k3s_service_after	Starte k3s nach einer definierten Liste von systemd-Einheiten.	[]*
k3s_service_env_vars	Wörterbuch von Umgebungsvariablen für die systemd-Einheit.	{}
k3s_service_env_file	Standort der Umgebungsdatei auf dem Host.	false**

* Die systemd-Einheit Vorlage gibt immer network-online.target für wants und after an.

** Die Datei muss bereits auf dem Ziel-Host existieren, diese Rolle wird die Datei nicht erstellen oder verwalten. Du kannst diese Datei außerhalb der Rolle mit Pre-Tasks in deinem Ansible-Playbook verwalten.

Gruppen-/Hostvariablen

Hier sind Variablen aufgelistet, die für einzelne oder Gruppen von Play-Hosts definiert sind. Typischerweise würdest du diese auf Gruppenebene für die Steuerplane oder Arbeiterknoten setzen.

Variable	Beschreibung	Standardwert
k3s_control_node	Bestimme, ob ein Host (oder eine Hostgruppe) Teil der Steuerplane ist.	false (die Rolle wird automatisch einen Knoten delegieren)
k3s_server	Server (Steuerplane) Konfiguration, siehe Hinweise weiter unten.	{}
k3s_agent	Agent (Arbeiter) Konfiguration, siehe Hinweise weiter unten.	{}

Server (Steuerplane) Konfiguration

Die Steuerplane wird mit der k3s_server Dict-Variable konfiguriert. Siehe die folgende Dokumentation für Konfigurationsoptionen:

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

Die k3s_server Dictionary-Variable wird Flags aus obigem enthalten (unter Weglassung des -- Prefix). Hier ist ein Beispiel:

k3s_server:
  datastore-endpoint: postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable
  cluster-cidr: 172.20.0.0/16
  flannel-backend: 'none'  # Dies muss in Anführungszeichen stehen
  disable:
    - traefik
    - coredns

Alternativ kannst du eine .yaml-Datei erstellen und diese in die k3s_server-Variable wie im folgenden Beispiel einlesen:

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

Siehe die Dokumentation für Beispielkonfigurationen.

Agent (Arbeiter) Konfiguration

Arbeiter werden mit der k3s_agent Dict-Variable konfiguriert. Siehe die folgende Dokumentation für Konfigurationsoptionen:

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

Die k3s_agent Dictionary-Variable wird Flags aus obigem enthalten (unter Weglassung des -- Prefix). Hier ist ein Beispiel:

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

Alternativ kannst du eine .yaml-Datei erstellen und diese in die k3s_agent-Variable wie im folgenden Beispiel einlesen:

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

Siehe die Dokumentation für Beispielkonfigurationen.

Ansible Controller Konfigurationsvariablen

Die folgenden Variablen werden verwendet, um die Art und Weise, wie die Rolle in Ansible ausgeführt wird, zu ändern, insbesondere im Hinblick auf Privilegieneskalation.

Variable	Beschreibung	Standardwert
k3s_skip_validation	Alle Aufgaben überspringen, die die Konfiguration validieren.	false
k3s_skip_env_checks	Alle Aufgaben überspringen, die die Umgebungs-Konfiguration prüfen.	false
k3s_skip_post_checks	Alle Aufgaben überspringen, die den Zustand nach der Ausführung prüfen.	false
k3s_become	Benutzerprivilegien für Aufgaben, die Root-Berechtigungen benötigen, eskalieren.	false

Wichtiger Hinweis zu Python

Seit v3 dieser Rolle wird Python 3 auf dem Zielsystem sowie auf dem Ansible-Controller benötigt, um ein konsistentes Verhalten bei Ansible-Aufgaben zu gewährleisten, da Python 2 mittlerweile nicht mehr unterstützt wird.

Wenn auf den Zielsystemen sowohl Python 2 als auch Python 3 installiert sind, wird standardmäßig wahrscheinlich Python 2 ausgewählt. Um sicherzustellen, dass Python 3 auf einem Ziel mit beiden Versionen verwendet wird, stelle sicher, dass ansible_python_interpreter in deinem Inventar gesetzt ist. Hier ein Beispielinventar:

---

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

Wichtiger Hinweis zu k3s_release_version

Wenn du keinen k3s_release_version festlegst, wird die neueste Version aus dem stabilen Kanal von k3s installiert. Wenn du gegen eine spezifische Version von k3s entwickelst, musst du dies in deiner Ansible-Konfiguration festlegen, z. B.:

k3s_release_version: v1.19.3+k3s1

Es ist auch möglich, spezifische K3s "Kanäle" zu installieren, hier sind einige Beispiele für k3s_release_version:

k3s_release_version: false             # Standardmäßig 'stable' Kanal
k3s_release_version: stable            # Neueste 'stable' Veröffentlichung
k3s_release_version: testing           # Neueste 'testing' Veröffentlichung
k3s_release_version: v1.19             # Neueste 'v1.19' Veröffentlichung
k3s_release_version: v1.19.3+k3s3      # spezifische Veröffentlichung

# Bestimmter Commit
# VORSICHT - nur für Tests verwendet - muss 40 Zeichen haben
k3s_release_version: 48ed47c4a3e420fa71c18b2ec97f13dc0659778b

Wichtiger Hinweis zu k3s_install_hard_links

Wenn du den system-upgrade-controller verwendest, musst du Hard Links anstelle von symbolischen Links verwenden, da der Controller symbolische Links nicht verfolgen kann. Diese Option wurde hinzugefügt, ist jedoch standardmäßig nicht aktiviert, um bestehende Installationen nicht zu beeinträchtigen.

Um die Verwendung von Hard Links zu aktivieren, stelle sicher, dass k3s_install_hard_links auf true gesetzt ist.

k3s_install_hard_links: true

Das Ergebnis kannst du sehen, indem du folgendes im k3s_install_dir ausführst:

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

Symbolische Links:

[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

Hard Links:

[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

Wichtiger Hinweis zu k3s_build_cluster

Wenn du k3s_build_cluster auf false setzt, wird diese Rolle jeden Play-Host als eigenständigen Knoten installieren. Ein Beispiel, wann du dies verwenden könntest, wäre, wenn du eine große Anzahl eigenständiger IoT-Geräte mit K3s bereitstellen möchtest. Hier ist ein hypothetisches Szenario, in dem wir 25 Raspberry Pi-Geräte bereitstellen, jedes ein eigenständiges System und kein Cluster von 25 Knoten. Dazu würden wir ein Playbook verwenden, das ähnlich aussieht wie das folgende:

- hosts: k3s_nodes  # z.B. 25 RPi's, die in unserem Inventar definiert sind.
  vars:
    k3s_build_cluster: false
  roles:
     - xanmanning.k3s

Wichtiger Hinweis zu k3s_control_node und Hochverfügbarkeit (HA)

Standardmäßig wird nur ein Host von Ansible als Steuerknoten definiert. Wenn du keinen Host als Steuerknoten festlegst, wird diese Rolle automatisch den ersten Play-Host als Steuerknoten delegieren. Dies ist nicht für Produktionsarbeitslasten geeignet.

Wenn mehrere Hosts k3s_control_node auf true gesetzt haben, musst du auch datastore-endpoint in k3s_server als Verbindungszeichenfolge zu einer MySQL- oder PostgreSQL-Datenbank oder einem externen Etcd-Cluster festlegen, andernfalls schlägt das Playmanuskript fehl.

Wenn du TLS verwendest, müssen CA, Zertifikat und Schlüssel bereits auf den Play-Hosts verfügbar sein.

Siehe: Hochverfügbarkeit mit einer externen DB

Es ist auch möglich, wenn auch nicht unterstützt, einen einzelnen K3s-Steuerknoten mit einem definierten datastore-endpoint auszuführen. Da dies nicht typischerweise unterstützt wird, musst du k3s_use_unsupported_config auf true setzen.

Seit K3s v1.19.1 ist es möglich, ein integriertes Etcd als Backend-Datenbank zu verwenden, indem du k3s_etcd_datastore auf true setzt. Die beste Praxis für Etcd ist es, mindestens 3 Mitglieder zu definieren, um sicherzustellen, dass ein Quorum vorhanden ist. Darüber hinaus wird empfohlen, eine ungerade Anzahl von Mitgliedern zu verwenden, um eine Mehrheit im Falle einer Netzwerkpartition sicherzustellen. Wenn du 2 Mitglieder oder eine gerade Anzahl von Mitgliedern verwenden möchtest, stelle sicher, dass k3s_use_unsupported_config auf true gesetzt ist.

Wichtiger Hinweis zu k3s_server_manifests_urls und k3s_server_pod_manifests_urls

Um Server-Manifeste und Server-Pod-Manifeste von einer URL bereitzustellen, musst du eine url und optional einen filename angeben (wenn keiner angegeben ist, wird basename verwendet). Hier ist ein Beispiel, wie man den Tigera-Operator für Calico und kube-vip bereitstellt.

---

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

Wichtiger Hinweis zu k3s_airgap

Bei der Bereitstellung von k3s in einer luftdichten Umgebung solltest du die k3s-Binary in ./files/ bereitstellen. Die Binary wird nicht von GitHub heruntergeladen und somit nicht mit der bereitgestellten sha256-Summenprüfung verifiziert, noch kann die Version, die du verwendest, überprüft werden. Alle damit verbundenen Risiken und Pflichten liegen in diesem Szenario beim Benutzer.

Abhängigkeiten

Keine Abhängigkeiten von anderen Rollen.

Beispiel-Playbooks

Beispiel-Playbook, ein einzelner Steuerknoten, der den testing-Kanal k3s ausführt:

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

Beispiel-Playbook, hochverfügbar mit PostgreSQL-Datenbank, die die neueste stabile Version ausführt:

- hosts: k3s_nodes
  vars:
    k3s_registration_address: loadbalancer  # In der Regel ein Lastenausgleich.
    k3s_server:
      datastore-endpoint: "postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable"
  pre_tasks:
    - name: Setze jeden Knoten als Steuerknoten
      ansible.builtin.set_fact:
        k3s_control_node: true
      when: inventory_hostname in ['node2', 'node3']
  roles:
    - role: xanmanning.k3s

Lizenz

BSD 3-Klausel

Mitwirkende

Beiträge der Community sind sehr willkommen, aber bitte lies die Beitragsrichtlinien, bevor du dies tust, dies hilft, die Dinge so reibungslos wie möglich zu gestalten.

Bitte sieh dir auch die großartige Liste von Mitwirkenden an.

Autoreninformation

Xan Manning