Wycieczka po Ansible, część 1: jedno repozytorium, trzy serwery – jak zorganizowany jest kod i co dzieje się podczas uruchomienia

Część 1 wycieczki po moim kodzie Ansible: jak jedno repozytorium i 34 role obsługują blog i dwa Nextcloudy, i co dzieje się podczas uruchomienia playbooka.

Ilustracja do serii Wycieczka po Ansible

🌐 Także w: English · Deutsch · Français · Español · Italiano · Português · Nederlands

Pierwsza część serii o kodzie Ansible stojącym za tym blogiem i dwoma serwerami Nextcloud. Kod jest publiczny: github.com/aptupgrademe/www_k3s; seria opisuje release v3.3.0. Część 1 wyjaśnia strukturę i to, co dzieje się podczas uruchomienia, części 2–6 role, a deep dives technologię pod spodem.

Trzy serwery, 34 role, cztery playbooki, około 22 000 linii YAML-a i szablonów. Kto otwiera repozytorium pierwszy raz, widzi głównie pliki. Ta część wyjaśnia trzy rzeczy, które warto wiedzieć na start: jak jeden zestaw ról obsługuje dwie bardzo różne aplikacje, skąd bierze się każda wartość i co faktycznie dzieje się między ansible-playbook a końcowym podsumowaniem.

Spis treści

🧩 Jedno repozytorium dla dwóch aplikacji

Blog (WordPress) i dwa serwery Nextcloud na pierwszy rzut oka mają ze sobą niewiele wspólnego. Pod spodem jednak potrzebują tego samego: utwardzonego AlmaLinuksa, firewalla, SSH tylko z kluczem, K3s, certyfikatów TLS, monitoringu, logów, ochrony przed atakami brute-force. Dlatego role są nazwane od miejsca, w którym są używane:

  • common_* działa na każdym serwerze: firewall, SSH, K3s, Grafana, fail2ban i dobre dwadzieścia innych.
  • blog_* istnieje tylko dla WordPressa, next_* tylko dla Nextclouda.

Dwie trzecie kodu jest wspólne. Poprawka w firewallu trafia na wszystkie trzy serwery przy następnym uruchomieniu, a luka, którą ujawni jeden Nextcloud, zostaje zamknięta także na blogu.

Ceną jest reguła, która nigdy nie robi sobie przerwy: każda zmiana we wspólnej roli musi działać na obu stackach. Jak to wygląda, gdy jest to prawdą tylko na papierze, pokazał bug znaleziony 26 października 2026: filtr fail2ban dla logowań do Nextclouda sprawdzał tylko POST /login. Nextcloud natomiast wysyła swój formularz logowania na /index.php/login. Filtr działał na obu serwerach Nextcloud od lipca i nie policzył ani jednej próby; rate limit przed nim też nie widział tych żądań. Wyszło to dopiero wtedy, gdy test nakarmił filtry prawdziwą linią logu, zamiast tylko sprawdzać, czy fail2ban działa.

Wniosek: wspólny kod oszczędza pracę, ale potrzebuje testów, które sprawdzają wynik. To, że usługa jest skonfigurowana i działa, nie dowodzi, że robi to, co powinna.

📒 Skąd bierze się każda wartość

Role opisują, co zrobić. Inwentarz decyduje, czym: jakie serwery istnieją, które wartości obowiązują wszystkie, a które tylko jeden.

  • hosts.yml zawiera wyłącznie przypisanie: który serwer należy do grupy blog, a który do nextcloud.
  • group_vars/all/ zawiera to, co wszędzie jest takie samo. Najważniejszy plik w tym miejscu to versions.yml: każda wersja, którą instaluje playbook (K3s, Helm, obrazy kontenerów, exportery), jest dokładnie w tym pliku, aż do poziomu patcha. Nigdy latest, nigdy tag w rodzaju 10.11. Taki tag zostawił blog w sierpniu na przestarzałym obrazie MariaDB, wciąż w cache na węźle, choć Docker Hub od dawna miał nowszy pod tą samą nazwą.
  • host_vars/<host>/ zawiera dwa pliki na serwer: vars.yml z adresami, rozmiarami i przełącznikami oraz vault.yml z hasłami, zaszyfrowany Ansible Vault. Żaden z nich nie jest w publicznym repozytorium. Publiczny jest plik .example obok nich, który pokazuje, jakich kluczy potrzebuje host.

Gdy wartość jest zdefiniowana w kilku miejscach, decyduje kolejność pierwszeństwa Ansible: defaulty roli są punktem wyjścia, group_vars je nadpisują, host_vars nadpisują oba. Przykładem jest filtr krajów dla SSH: w roli jest wyłączony, a serwer włącza go jedną linijką w swoim vars.yml.

Żeby brakująca wartość nie wyszła w połowie uruchomienia jako niejasny błąd szablonu, 23 role deklarują swoje wejścia w meta/argument_specs.yml. Ansible sprawdza je, zanim rola wykona pierwszy task.

Wniosek: wersja, która nie jest dokładnie przypięta, w rzeczywistości jest przypięta przez cache.

🔀 Jak wspólna rola odróżnia stacki

Rola common_* czasem musi wiedzieć, gdzie działa. Nextcloud ma MariaDB i Redisa na hoście, blog ma oba w kontenerach; dlatego firewall potrzebuje na Nextcloudzie dwóch reguł więcej. Są na to trzy wzorce, w kolejności preferencji:

  1. Mówi to playbook. Każdy pełny playbook ustawia zmienną stack: wordpress albo stack: nextcloud. To jedyne miejsce, w którym zapada decyzja; role tylko czytają tę zmienną.
  2. Jeden profil na stack. Role, które na obu stackach wykonują ten sam rodzaj pracy z innymi ścieżkami – na przykład etykiety SELinux dla montowanych katalogów – trzymają obie listy w swoich defaultach i wybierają jedną według stack.
  3. Zapytać serwer. To, czy serwer dostaje adres przez DHCP, nie jest zapisane w żadnej zmiennej; firewall pyta NetworkManagera. Bez reguł DHCP adres zniknąłby przy następnym odnowieniu dzierżawy.

Do wersji 3.2 role decydowały na podstawie nazw grup w inwentarzu. To się posypało na serwerze testowym, który jest w obu grupach: podczas instalacji bloga firewall otworzył porty bazy danych Nextclouda, a Prometheus próbował scrapować exportery Nextclouda, których tam nie było.

Wniosek: decyzja należy do jednego miejsca – tam, gdzie wiadomo, co jest instalowane, czyli do playbooka, a nie do inwentarza.

📜 Kolejność w playbooku to łańcuch zależności

Są cztery playbooki: na aplikację jeden do pełnego uruchomienia i jeden do aktualizacji. Pełny playbook to lista około 25 ról, a kolejność wynika z zależności, nie z alfabetu:

  • SELinux przed deploymentem. Pody montują katalogi z hosta. Jeśli nie mają one jeszcze etykiety container_file_t, SELinux blokuje każdy zapis i MariaDB nie wstaje.
  • Monitoring po deploymencie. Prometheus scrapuje exportery w podach, a fail2ban czyta logi ingressu; jedno i drugie istnieje dopiero po deploymencie.
  • AIDE zawsze na końcu. AIDE co noc porównuje pliki systemowe z baseline. Uruchomienie celowo zmienia monitorowane pliki, więc ostatnia rola odnawia baseline.

Każda rola ma tag z własną nazwą. To zamienia pełny playbook w precyzyjne narzędzie: --tags blog_k3s_deploy aktualizuje tylko obiekty Kubernetesa. Właśnie tam czaiła się pułapka, która stała się stałą regułą: uruchomienie z --tags pomija ostatnią rolę, baseline AIDE zostaje stary, a w nocy przychodzi mail o zmienionych plikach. Od tamtej pory po każdym uruchomieniu z tagami następuje drugie z --tags common_rkhunter,common_aide_refresh.

Playbooki aktualizacji restartują aplikację i dlatego są napisane defensywnie: odmawiają działania bez --limit, nie aktualizują instancji, która już utknęła w trybie konserwacji, a pracę wykonują w block z rescue, który – jeśli coś się nie uda – pokazuje, w jakim stanie została instancja.

Wniosek: przesunięcie roli przesuwa zależność. Kolejność jest częścią kodu.

⚙️ Co dzieje się podczas uruchomienia

Połączenie. Ansible loguje się jako root przez SSH kluczem; SSH nie przyjmuje hasła. Potem zbiera tylko tych kilka faktów, których potrzebują role: dystrybucję, kernel, hostname.

Najpierw raport. Pierwsza rola niczego nie zmienia. Dla K3s, Helma, ingressu i cert-managera porównuje to, co jest zainstalowane, to, co przypina versions.yml, i to, jaki jest najnowszy release. Kto uruchamia playbook, widzi, czy coś jest nieaktualne, zanim cokolwiek się zmieni.

Task po tasku. Ansible wykonuje task 1 na każdym hoście w uruchomieniu, potem task 2 i tak dalej. Każdy task zgłasza ok (nic do zrobienia), changed albo failed. Tu leży najważniejsza cecha ról: idempotentność. Drugie uruchomienie zaraz po pierwszym musi zgłosić changed=0. To zamienia playbook w narzędzie kontrolne: jeśli zgłasza zmianę na serwerze, który powinien zgadzać się z kodem, to jest to albo drift – ktoś coś zmienił ręcznie – albo bug w tasku. W tym celu taski najpierw czytają stan i zmieniają tylko to, co odbiega. Usługi nie są restartowane przy każdej okazji, tylko przez handlery, które działają raz na końcu i tylko wtedy, gdy ich konfiguracja naprawdę się zmieniła.

Dry run. Z --check --diff Ansible przechodzi przez każdy task, niczego nie zmienia i pokazuje, co by zmienił. Skrypt scripts/check-drift.sh odfiltrowuje tylko te taski, które by coś zmieniły. Kod wyjścia 0 oznacza: serwer jest dokładnie tym, co opisuje kod.

Werdykt. Uruchomienie, które kończy się na ok, mówi tylko, że każdy task zrobił to, co mu kazano. Czy aplikacja potem działa, sprawdzają na końcu role verify: 30 do 38 testów na serwer, kolorowy raport, mail, a uruchomienie kończy się błędem, jeśli krytyczny test nie przejdzie. Od 26 października 2026 należą do nich testy efektu: każdy filtr fail2ban dostaje prawdziwą linię logu, a każdy jail na chwilę banuje adres testowy, który musi dotrzeć do kernela.

I zawsze jeden host po drugim: dwa równoległe uruchomienia na tym samym serwerze zderzyły się w październiku na blokadzie bazy pakietów.

Wniosek: changed=0 przy drugim uruchomieniu to nie kosmetyka. To dzięki temu każde prawdziwe odchylenie rzuca się w oczy.

🧪 Jak zmiana trafia na serwer

Serwery to produkcja: pliki innych ludzi i blog z czytelnikami. Dlatego zmiana zawsze przechodzi przez te same etapy, od szybkich i lokalnych do wolnych i prawdziwych:

  1. Zmiana: rola, szablon albo versions.yml.
  2. Linting: ansible-lint i yamllint po całym repozytorium; przy commicie gitleaks dodatkowo szuka haseł i kluczy.
  3. Test bez serwera, tam gdzie test istnieje (role Kubernetesa, playbooki aktualizacji).
  4. Dry run z check-drift.sh i pytanie: czy to dokładnie to, czego chciałem? Wszystko inne na liście to niespodzianka, którą najpierw trzeba zrozumieć.
  5. Prawdziwe uruchomienie na jednym serwerze, ograniczone przez --tags do tego, czego dotyczy zmiana.
  6. Ponownie sprawdzenie driftu: teraz musi powiedzieć “no drift”.
  7. Commit i push; CI jeszcze raz sprawdza całe repozytorium.

Żaden z tych etapów nie polega na tym, że ktoś coś zapamięta. Jedyna reguła, która zostaje ręczna: prawdziwe uruchomienia startuje człowiek, jeden host po drugim, po przeczytaniu dry runa.

🎯 Pięć lekcji z części 1

  • Wspólne role oszczędzają pracę, ale tylko z testami, które sprawdzają efekt zamiast stanu.
  • Przypinaj każdą wersję dokładnie, w jednym miejscu.
  • Decyzja “blog czy Nextcloud” należy do playbooka.
  • Kolejność ról to łańcuch zależności.
  • Idempotentność zamienia playbook w narzędzie kontrolne.

🧭 Dokąd wycieczka zmierza dalej

Każda część trzyma się tego samego schematu: co robi rola, dlaczego jest tak zbudowana i co poszło nie tak po drodze. Ten ostatni punkt jest zwykle najbardziej pouczający.

Część tekstów i obrazów na tej stronie powstała z pomocą AI lub została wygenerowana przez AI. Szczegóły