Rola Ansible: k3s (v3.x)

Rola Ansible do instalacji K3S („Lekki Kubernetes”) jako samodzielny serwer lub klaster.

Poszukiwana pomoc!

Cześć! :wave: @xanmanning szuka nowego opiekuna tej roli Ansible. Dzieje się tak, ponieważ mam mniej wolnego czasu i już nie piszę regularnie Ansible w ramach mojej pracy. Jeśli chcesz pomóc, daj znać!

Notatki o wydaniu

Zobacz Wydania i CHANGELOG.md.

Wymagania

Gospodarz, z którego uruchamiasz Ansible, musi mieć następujące zależności Pythona:

• python >= 3.6.0 - Zobacz notatki poniżej.
• ansible >= 2.9.16 lub ansible-base >= 2.10.4

Możesz zainstalować zależności, używając pliku requirements.txt w tym repozytorium: pip3 install -r requirements.txt.

Ta rola została przetestowana na następujących dystrybucjach 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: Wersje v3 tej roli wspierają tylko k3s >= v1.19, dla k3s < v1.19 rozważ aktualizację lub używanie wersji v1.x tej roli.

Przed aktualizacją sprawdź CHANGELOG pod kątem informacji o przełamywających zmiany.

Zmienne roli

Od K3s v1.19.1+k3s1 możesz teraz konfigurować K3s za pomocą pliku konfiguracyjnego zamiast zmiennych środowiskowych lub argumentów wiersza poleceń. Wersja v2 tej roli przeszła na metodę pliku konfiguracyjnego zamiast wypełniania pliku jednostki systemd argumentami wiersza poleceń. Mogą być wyjątki określone w Zmiennych globalnych/klastrowych, jednak głównie będziesz konfigurować k3s za pomocą plików konfiguracyjnych z użyciem zmiennych k3s_server i k3s_agent.

Zobacz "Konfiguracja serwera (płaszczyzna sterująca)" oraz "Konfiguracja agenta (pracownika)" poniżej.

Zmienne globalne/klastrowe

Poniżej znajdują się zmienne ustawione dla wszystkich hostów w grze dla spójności środowiska. Zwykle są to konfiguracje na poziomie klastra.

Zmienna	Opis	Wartość domyślna
k3s_state	Stan k3s: zainstalowany, uruchomiony, zatrzymany, pobrany, odinstalowany, zatwierdzony.	zainstalowany
k3s_release_version	Użyj określonej wersji k3s, np. v0.2.0. Podaj false dla stabilnej.	false
k3s_airgap	Wartość logiczna do włączenia instalacji w odseparowanych środowiskach	false
k3s_config_file	Lokalizacja pliku konfiguracyjnego k3s.	/etc/rancher/k3s/config.yaml
k3s_build_cluster	Kiedy dostępne są wiele hostów, spróbuj zbudować klaster. Przeczytaj notatki poniżej.	true
k3s_registration_address	Ustalony adres rejestracji dla węzłów. IP lub FQDN.	NULL
k3s_github_url	Ustal adres URL GitHub do instalacji k3s.	https://github.com/k3s-io/k3s
k3s_api_url	URL do API aktualizacji K3S.	https://update.k3s.io
k3s_install_dir	Katalog instalacyjny dla k3s.	/usr/local/bin
k3s_install_hard_links	Zainstaluj używając twardych linków zamiast symbolicznych.	false
k3s_server_config_yaml_d_files	Lista szablonów do uzupełnienia konfiguracji k3s_server.	[]
k3s_agent_config_yaml_d_files	Lista szablonów do uzupełnienia konfiguracji k3s_agent.	[]
k3s_server_manifests_urls	Lista URL do wdrożenia na głównym kontrolerze. Przeczytaj notatki poniżej.	[]
k3s_server_manifests_templates	Lista szablonów do wdrożenia na głównym kontrolerze.	[]
k3s_server_pod_manifests_urls	Lista URL do instalacji statycznych manifestów pod na płaszczyźnie sterującej. Przeczytaj notatki poniżej.	[]
k3s_server_pod_manifests_templates	Lista szablonów do instalacji statycznych manifestów pod na płaszczyźnie sterującej.	[]
k3s_use_experimental	Zezwól na korzystanie z eksperymentalnych funkcji w k3s.	false
k3s_use_unsupported_config	Zezwól na korzystanie z nieobsługiwanych konfiguracji w k3s.	false
k3s_etcd_datastore	Włącz wbudowane przechowywanie danych etcd (przeczytaj notatki poniżej).	false
k3s_debug	Włącz logowanie debugowania w usłudze k3s.	false
k3s_registries	Zawartość pliku konfiguracyjnego rejestrów.	{ mirrors: {}, configs:{} }

Konfiguracja usługi K3S

Poniżej znajdują się zmienne, które zmieniają sposób i czas uruchamiania pliku jednostki usługi systemd dla K3S. Używaj tego ostrożnie, zapoznaj się z dokumentacją systemd w celu uzyskania dalszych informacji.

Zmienna	Opis	Wartość domyślna
k3s_start_on_boot	Uruchom k3s przy starcie systemu.	true
k3s_service_requires	Lista wymagań jednostek systemd dla jednostki usługi k3s.	[]
k3s_service_wants	Lista "pożądanych" jednostek systemd dla k3s (słabsza niż "wymaga").	[]*
k3s_service_before	Uruchom k3s przed określoną listą jednostek systemd.	[]
k3s_service_after	Uruchom k3s po określonej liście jednostek systemd.	[]*
k3s_service_env_vars	Słownik zmiennych środowiskowych do użycia w pliku jednostki systemd.	{}
k3s_service_env_file	Lokalizacja pliku środowiskowego na hoście do dołączenia.	false**

* Szablon jednostki systemd zawsze określa network-online.target dla wants i after.

** Plik musi już istnieć na docelowym hoście, ta rola nie utworzy ani nie zarządza plikiem. Możesz zarządzać tym plikiem poza rolą z użyciem pre-tasków w swoim playbooku Ansible.

Zmienne grupowe/hostowe

Poniżej znajdują się zmienne ustawione dla poszczególnych grup hostów w grach. Zwykle ustawiłbyś je na poziomie grupy dla węzłów kontrolnych lub roboczych.

Zmienna	Opis	Wartość domyślna
k3s_control_node	Określa, czy host (lub grupa hostów) są częścią płaszczyzny sterującej.	false (rola automatycznie przydzieli węzeł)
k3s_server	Konfiguracja serwera (płaszczyzna sterująca), zobacz notatki poniżej.	{}
k3s_agent	Konfiguracja agenta (pracownika), zobacz notatki poniżej.	{}

Konfiguracja serwera (płaszczyzna sterująca)

Płaszczyzna sterująca jest konfigurowana za pomocą zmiennej słownikowej k3s_server. Zapoznaj się z poniższą dokumentacją, aby uzyskać opcje konfiguracyjne:

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

Słownik zmiennej k3s_server będzie zawierał flagi z powyższych opcji (usunięcie prefiksu --). Poniżej znajduje się przykład:

k3s_server:
  datastore-endpoint: postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable
  cluster-cidr: 172.20.0.0/16
  flannel-backend: 'none'  # To musi być w cudzysłowach
  disable:
    - traefik
    - coredns

Alternatywnie, możesz stworzyć plik .yaml i wczytać go do zmiennej k3s_server, jak w poniższym przykładzie:

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

Zobacz Dokumentację dla przykładowej konfiguracji.

Konfiguracja agenta (pracownika)

Węzły robocze są konfigurowane za pomocą zmiennej słownikowej k3s_agent. Zapoznaj się z poniższą dokumentacją, aby uzyskać opcje konfiguracyjne:

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

Słownik zmiennej k3s_agent będzie zawierał flagi z powyższych opcji (usunięcie prefiksu --). Poniżej znajduje się przykład:

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

Alternatywnie, możesz stworzyć plik .yaml i wczytać go do zmiennej k3s_agent, jak w poniższym przykładzie:

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

Zobacz Dokumentację dla przykładowej konfiguracji.

Zmienne konfiguracyjne kontrolera Ansible

Poniżej znajdują się zmienne używane do zmiany sposobu wykonywania roli w Ansible, szczególnie w odniesieniu do eskalacji uprawnień.

Zmienna	Opis	Wartość domyślna
k3s_skip_validation	Pomiń wszystkie zadania, które weryfikują konfigurację.	false
k3s_skip_env_checks	Pomiń wszystkie zadania, które sprawdzają konfigurację środowiska.	false
k3s_skip_post_checks	Pomiń wszystkie zadania, które sprawdzają stan po wykonaniu.	false
k3s_become	Eskaluj uprawnienia użytkownika dla zadań wymagających uprawnień root.	false

Ważna uwaga dotycząca Pythona

Od wersji 3 tej roli, Python 3 jest wymagany na systemie docelowym oraz na kontrolerze Ansible. Ma to na celu zapewnienie spójnego zachowania dla zadań Ansible, ponieważ Python 2 jest już nieobsługiwany.

Jeśli systemy docelowe mają zainstalowane zarówno Pythona 2, jak i Pythona 3, najprawdopodobniej domyślnie zostanie wybrany Python 2. Aby upewnić się, że Python 3 jest używany na systemie docelowym z obiema wersjami Pythona, upewnij się, że ansible_python_interpreter jest ustawiony w swoim inwentarzu. Poniżej znajduje się przykładowy inwentarz:

---

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

Ważna uwaga dotycząca k3s_release_version

Jeśli nie ustawisz k3s_release_version, najnowsza wersja z stabilnego kanału k3s zostanie zainstalowana. Jeśli rozwijasz się w oparciu o konkretną wersję k3s, musisz upewnić się, że jest to ustawione w swojej konfiguracji Ansible, np.:

k3s_release_version: v1.19.3+k3s1

Możliwe jest również instalowanie określonych "Kanałów" K3s, poniżej kilka przykładów dla k3s_release_version:

k3s_release_version: false             # domyślnie do kanału 'stable'
k3s_release_version: stable            # najnowsze wydanie 'stable'
k3s_release_version: testing           # najnowsze wydanie 'testing'
k3s_release_version: v1.19             # najnowsze wydanie 'v1.19'
k3s_release_version: v1.19.3+k3s3      # konkretny wydanie

# Konkretny commit
# OSTROŻNIE - używane tylko do testowania - musi mieć 40 znaków
k3s_release_version: 48ed47c4a3e420fa71c18b2ec97f13dc0659778b

Ważna uwaga dotycząca k3s_install_hard_links

Jeśli używasz system-upgrade-controller, musisz użyć twardych linków zamiast symbolicznych, ponieważ kontroler nie będzie w stanie śledzić linków symbolicznych. Ta opcja została dodana, ale nie jest domyślnie włączona, aby uniknąć łamania istniejących instalacji.

Aby włączyć użycie twardych linków, upewnij się, że k3s_install_hard_links jest ustawione na true.

k3s_install_hard_links: true

Wynik ten można zobaczyć uruchamiając następujące polecenie w k3s_install_dir:

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

Linki symboliczne:

[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

Linki twarde:

[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

Ważna uwaga dotycząca k3s_build_cluster

Jeśli ustawisz k3s_build_cluster na false, ta rola zainstaluje każdy host jako samodzielny węzeł. Przykładem, kiedy mogłoby to być używane, byłoby budowanie dużej liczby samodzielnych urządzeń IoT działających na K3s. Poniżej znajduje się hipotetyczna sytuacja, w której zamierzamy wdrożyć 25 urządzeń Raspberry Pi, z których każde jest samodzielnym systemem, a nie klastrem 25 węzłów. Aby to zrobić, użyjemy playbooka podobnego do poniższego:

- hosts: k3s_nodes  # np. 25 RPi zdefiniowanych w naszym inwentarzu.
  vars:
    k3s_build_cluster: false
  roles:
     - xanmanning.k3s

Ważna uwaga dotycząca k3s_control_node i wysokiej dostępności (HA)

Domyślnie Ansible zdefiniuje tylko jeden host jako węzeł kontrolny. Jeśli nie ustawisz hosta jako węzeł kontrolny, ta rola automatycznie przydzieli pierwszy host w grze jako węzeł kontrolny. To nie jest odpowiednie do użycia w produkcji.

Jeśli wiele hostów ma ustawione k3s_control_node na true, musisz również ustawić datastore-endpoint w k3s_server jako łańcuch połączenia do bazy danych MySQL lub PostgreSQL lub zewnętrznego klastra Etcd, inaczej gra nie zakończy się sukcesem.

Jeśli używasz TLS, CA, certyfikat i klucz muszą być już dostępne na hostach w grze.

Zobacz: Wysoka dostępność z zewnętrzną bazą danych

Możliwe jest również, choć nie jest to wspierane, uruchomienie pojedynczego węzła kontrolnego K3s z określonym datastore-endpoint. Ponieważ nie jest to zwykle wspierana konfiguracja, musisz ustawić k3s_use_unsupported_config na true.

Od wersji K3s v1.19.1 możliwe jest użycie wbudowanego Etcd jako bazy danych, co realizuje się przez ustawienie k3s_etcd_datastore na true. Najlepszą praktyką dla Etcd jest zdefiniowanie co najmniej 3 członków, aby zapewnić ustanowienie kworum. Dodatkowo, zalecane jest posiadanie nieparzystej liczby członków dla zapewnienia większości w przypadku podziału sieci. Jeśli chcesz użyć 2 członków lub parzystej liczby członków, proszę ustawić k3s_use_unsupported_config na true.

Ważna uwaga dotycząca k3s_server_manifests_urls i k3s_server_pod_manifests_urls

Aby wdrożyć manifesty serwera i manifesty podów serwera z URL, musisz określić url i opcjonalnie filename (jeśli nie podano, używana jest nazwa bazowa). Poniżej znajduje się przykład, jak wdrożyć operatora Tigera dla Calico i 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

Ważna uwaga dotycząca k3s_airgap

Podczas wdrażania k3s w odseparowanym środowisku powinieneś dostarczyć binarkę k3s w ./files/. Binarka nie zostanie pobrana z Githuba i w zależności od tego nie zostanie zweryfikowana przy użyciu dostarczonego sumy sha256, ani nie będzie możliwe potwierdzenie, jaką wersję uruchamiasz. Wszystkie ryzyka i obciążenia związane są przypisane użytkownikowi w tym przypadku.

Zależności

Brak zależności od innych ról.

Przykład playbooków

Przykładowy playbook, pojedynczy węzeł kontrolny uruchamiający k3s z kanału testing:

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

Przykładowy playbook, wysokiej dostępności z bazą danych PostgreSQL uruchamiającą najnowszą stabilną wersję:

- hosts: k3s_nodes
  vars:
    k3s_registration_address: loadbalancer  # Zwykle balanser obciążenia.
    k3s_server:
      datastore-endpoint: "postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable"
  pre_tasks:
    - name: Ustaw każdy węzeł jako węzeł kontrolny
      ansible.builtin.set_fact:
        k3s_control_node: true
      when: inventory_hostname in ['node2', 'node3']
  roles:
    - role: xanmanning.k3s

Licencja

BSD 3-clause

Współpraca

Wkład społeczności jest bardzo mile widziany, ale proszę przeczytać wytyczne dotyczące wkładu, aby ułatwić wszystko tak bardzo, jak to możliwe.

Również sprawdź wspaniałą listę współpracowników.

Informacje o autorze

Xan Manning