Dziesięć punktów, jeden branch: mój kod Ansible od „działa” do „jest czysty”
Dziesięć ulepszeń mojego kodu Ansible, przetestowanych bez dotykania produkcji: kubernetes.core, prawdziwy dry run, lint, secret scan, rescue, Renovate.

🌐 Także w: English · Deutsch · Français · Español · Italiano · Português · Nederlands
Zaczęło się od nieco próżnego pytania. Moje repozytorium Ansible obsługuje tego bloga i dwa serwery Nextcloud: 34 role, cztery playbooki, około 9 000 linii YAML, prawie 200 commitów. Większości tych linii nie napisałem sam – zrobił to mój współadmin AI (Claude), a ja decydowałem, testowałem i uruchamiałem playbooki. Zapytałem go więc: jeśli rozumiem większość tego kodu, to czy jestem zaawansowanym użytkownikiem Ansible?
Odpowiedź była szczera i trochę niewygodna: zaawansowany w czytaniu i obsłudze – tak. Zaawansowany w pisaniu od zera – jeszcze nieudowodnione. A potem padła lista dziesięciu rzeczy, które poprawiłyby sam kod. Powiedziałem: zrób wszystkie dziesięć. Przetestuj porządnie. Potem o tym napisz. To jest ten wpis.
Zasady jak zawsze: wszystko dzieje się na osobnym branchu Git, nic nie dotyka serwera produkcyjnego, dopóki sam tego nie uruchomię, a każde twierdzenie jest testowane. „Przetestowane” okazało się najciekawszą częścią.
Spis treści
📋 Dziesięć punktów
| # | Ulepszenie | Dlaczego |
|---|---|---|
| 1 | Obiekty Kubernetes przez kubernetes.core.k8s zamiast kubectl apply przez shell | idempotentne, prawdziwe diffy, działa w check mode |
| 2 | Sprawić, by --check był naprawdę użyteczny | dry run przed każdym uruchomieniem na produkcji |
| 3 | ansible-lint, yamllint i secret scanner jako hook pre-commit i GitHub Action | łapać błędy i wycieki sekretów, zanim trafią do repo |
| 4 | Automatyczny test idempotencji | drugie uruchomienie musi zgłosić changed=0 |
| 5 | Ścieżki rescue w playbookach aktualizacji | określona reakcja, gdy aktualizacja padnie w połowie |
| 6 | Podzielić duże pliki z taskami | plik na 912 linii nie jest niczyim przyjacielem |
| 7 | meta/argument_specs.yml dla ról | brakująca zmienna wywala się na starcie, nie w połowie |
| 8 | Połączyć zduplikowane role | jedna rola ClamAV zamiast dwóch prawie identycznych |
| 9 | Przypiąć dokładne wersje kolekcji | >= po cichu wpuszcza major release łamiący kompatybilność |
| 10 | Renovate dla przypiętych wersji | propozycje aktualizacji jako pull requesty zamiast ręcznego szukania |
W połowie dodałem jedenaste życzenie: wszystkie przypięte wersje w jednym miejscu, żebym jednym rzutem oka widział, co gdzie działa. Więcej o tym w punkcie 10.
🧪 Pierwszy problem: jak testować kod Kubernetes bez dotykania produkcji?
Kiedyś w inventory był serwer testowy. Gdy Claude próbował się z nim połączyć, SSH odmówił: host key verification failed. Ten adres IP należy pewnie już do kogoś innego, więc celowo się nie połączył. A hasła do vaulta nie podaję na czacie, więc żaden playbook nie mógł też ruszyć przeciw prawdziwym serwerom.
Rozwiązanie było zgrabne: jednorazowy K3s w rootless podmanie na moim jump hoście. Pełny K3s padł od razu (failed to find cpuset cgroup – kontenery rootless nie dostają delegacji tego kontrolera). Ale żeby sprawdzić, czy manifesty są nakładane idempotentnie, nie potrzeba w ogóle działających podów, wystarczy API server. K3s ma flagę dokładnie do tego:
podman run -d --name k3s-test --privileged -p 127.0.0.1:16443:6443 \
docker.io/rancher/k3s:v1.36.5-k3s1 server --disable-agent \
--disable traefik --disable servicelb --disable metrics-server
Mały skrypt-zastępca udaje k3s kubectl: przekazuje wszystko do kontenera, a na polecenia, które wymagałyby działających podów (exec, rollout status, wait), odpowiada „w porządku”. Test robi wtedy to, co ważne: nakłada wszystko starym kodem z main (w takim stanie są serwery), a potem uruchamia na tym nowy kod – dry run, prawdziwe uruchomienie, jeszcze raz prawdziwe, jeszcze raz dry run.
1️⃣ kubernetes.core zamiast kubectl apply
Stary wzorzec występował 29 razy: wyrenderuj template do /tmp, kubectl apply -f, usuń plik i zgaduj „changed”, szukając w wyjściu słowa configured. Nowy wzorzec renderuje w pamięci i rozmawia bezpośrednio z API:
- name: Redis | Apply Deployment + Service
kubernetes.core.k8s:
kubeconfig: "{{ k3s_kubeconfig }}"
state: present
apply: true
definition: "{{ item }}"
loop: "{{ lookup('ansible.builtin.template', 'redis-deployment.yml.j2') | ansible.builtin.from_yaml_all | select | list }}"
loop_control:
label: "{{ item.kind }}/{{ item.metadata.name }}"
Trzy rzeczy wyszły na jaw tylko dzięki testowi:
- Pierwszy dry run mówił „changed” prawie przy wszystkim – bez diffa. Okazuje się, że moduł nie pokazuje diffa, gdy podasz mu listę obiektów. Jedna iteracja pętli na obiekt to naprawiła i teraz diff mówi dokładnie
image: redis:7.4.11-alpine → redis:7.4.12-alpine. - Jednorazowa migracja przepisuje tylko adnotację
last-applied-configuration(kubectl wpisuje do niej puste"annotations":{}, moduł nie). Spec i pod template pozostają identyczne, więc żaden pod się nie restartuje – sprawdzone przez rewizje ReplicaSetów, wszystkie nadal na 1. - Helm:
helm upgrade --installuruchamiał się przy każdym playu i za każdym razem dokładał nową rewizję.kubernetes.core.helmporównuje wersję charta i values i nic nie robi, jeśli się zgadzają. Haczyk: Helm 4 jest obsługiwany dopiero od wersji kolekcji 6.5.0; pakiet z dystrybucji dostarczał 6.1.0.
Efekt uboczny, który bardzo mi się podoba: Secrets Kubernetesa nie przechodzą już przez plik w /tmp na serwerze.
2️⃣ Dry run, który coś znaczy
W check mode Ansible pomija każdy task shell/command – także te nieszkodliwe, które tylko coś czytają. Późniejsze taski, które oceniają te wyniki, wtedy padają albo decydują na podstawie niczego. 94 czyste zapytania (sprawdzanie wersji, occ config:system:get, systemctl is-active …) mają teraz check_mode: false. Wszystko, co zapisuje, nadal jest pomijane – a tam, gdzie to ukryłoby oczekującą zmianę, zgłasza ją mały dodatkowy task.
3️⃣ Lint, secret scan, hooki
Pierwsze uruchomienie ansible-lint zgłosiło 811 uwag. Około 600 to były reguły stylu sprzeczne ze świadomymi decyzjami (wyrównane kolumny, wspólne nazwy zmiennych bez prefiksu roli) – te są wyłączone z pisemnym uzasadnieniem. Resztę poprawiono. Dwa prawdziwe znaleziska:
ansible.builtin.ini_filenie istnieje. Działało tylko dzięki przestarzałemu przekierowaniu docommunity.general– kolekcji, której nawet nie było wrequirements.yml. Na kontrolerze z gołym ansible-core playbook Nextcloud zatrzymałby się właśnie tam.- 27 pipe’ów w shellu bez
pipefail. Przeważnie nieszkodliwe, ale w sprawdzaniu wersjik3s --version | awk … || echo 'not installed'nigdy nie mogło wypisać „not installed”: bezpipefailliczy się tylko kod wyjściaawk.
gitleaks przeskanował wszystkie 191 commitów historii: jedno trafienie, placeholder PASTE_CONTENT_OF_id_rsa_HERE między dwoma znacznikami klucza w starym pliku przykładowym. Zaakceptowane celowo, udokumentowane. Hooki działają teraz przy każdym commicie – a pierwszy commit, który zablokowały, był commitem samego Claude’a, kilka godzin później (złe wcięcia YAML w generowanych plikach). Dokładnie po to są.
4️⃣ Idempotencja, przetestowana
Test z podmanem jest teraz częścią repo (tests/k8s/run.sh). Kończy się błędem, jeśli drugie uruchomienie wciąż coś zmienia, pod miałby zostać wdrożony od nowa, release Helma dostaje nową rewizję – albo jeśli celowo zmieniony tag obrazu nie zostanie wykryty. To ostatnie jest ważne: test, który nigdy nie może się nie udać, niczego nie dowodzi.
Dla prawdziwych serwerów jest scripts/check-drift.sh <playbook> <host>: dry run, który wypisuje tylko to, co by się zmieniło, z czytelnym diffem. Zaraz po prawdziwym uruchomieniu musi powiedzieć NO DRIFT.
Po drodze naprawiono kilka tasków, które przy każdym uruchomieniu zgłaszały „changed” (pobieranie sygnatur, użytkownik bazy danych, moduł dnf). Najbardziej podstępne znalezisko było odwrotne: dziewięć ustawień SMTP Nextclouda było przepisywanych przy każdym uruchomieniu i zawsze zgłaszało „ok”. Zmienione hasło do poczty nigdy nie pokazałoby się jako zmiana. Teraz są najpierw odczytywane, porównywane i zapisywane są tylko różniące się wartości – przekazywane przez argv, żeby cudzysłów w haśle nie rozwalił polecenia.
5️⃣ Gdy aktualizacja padnie w połowie
Pierwsza propozycja Claude’a brzmiała „w rescue czysto wyjść z trybu konserwacji”. Po namyśle sam się poprawił: po przerwanym occ upgrade wyłączenie trybu konserwacji wpuszcza użytkowników na w połowie zaktualizowaną instancję. Logika teraz:
- Kontrola wstępna poza blokiem: zainstalowane, nie w trybie konserwacji, brak oczekującego upgrade’u bazy – w przeciwnym razie playbook odmawia startu. Poza blokiem celowo: rescue ma się zajmować tylko stanami, które spowodowało samo uruchomienie.
- Rescue zbiera status occ, pody, eventy i ostatnie linie
nextcloud.log, a tryb konserwacji wyłącza tylko wtedy, gdyneedsDbUpgradejest false. Potem się zatrzymuje, żeby nie ruszyć drugiego serwera. - Bonus: playbooki aktualizacji restartowały Nextclouda i Collaborę przy każdym uruchomieniu. Mała nowa rola porównuje digest każdego świeżo pobranego obrazu z tym, co działa w podach, i restartuje tylko to, co faktycznie zostało przebudowane – łącznie z exporterami i notify_push.
Przetestowane z fałszywymi kubectl/crictl w 14 scenariuszach. A potem ważna część: celowo zepsuć rescue (zawsze wyłączać konserwację) i uruchomić test ponownie. Zrobił się czerwony dokładnie we właściwym scenariuszu. Wcześniej ten sam test raz pokazał „wszystko zielone” z niewłaściwego powodu – dwa scenariusze o tej samej nazwie dzieliły katalog i pomieszały sobie logi. Zielony niewiele znaczy, dopóki nie zobaczysz, jak test się wywala.
6️⃣ do 9️⃣ Te cichsze
- 6 – podział: rola WordPress (912 linii) to teraz siedem plików tematycznych, Grafana trzy, role weryfikacyjne po dwa. Dowód, że nic się nie zmieniło:
--list-tasks --list-tagsprzed i po, identyczne. - 7 – argument specs: 23 role deklarują swoje wejścia. „Wymagane” jest liczone per typ hosta: wspólne role czytają
blog_hostnamena jednym serwerze inextcloud_hostnamena drugim, więc żadna z tych zmiennych nie może być obowiązkowa. Sprawdzone na prawdziwych zmiennych wszystkich trzech serwerów. Wartości z vaulta sąno_log– zweryfikowane, że nie pojawiają się ani z-vvv, ani w błędzie walidacji. - 8 – łączenie: jedna rola ClamAV i jedna rola SELinux z profilem na stack, plus 16 wspólnych smoke checków. Pułapka ominięta: Ansible rozpoznaje wpisy crona po nazwie, więc nazwy musiały zostać dokładnie takie same – inaczej stary job działałby dalej obok nowego.
- 9 – przypięcia:
>=3.0.0zmieniło się w3.15.0. Dry run Renovate pokazał, dlaczego to ważne: czekały już majory 5.x i 13.x.
🔟 Renovate i wszystkie wersje w jednym pliku
Wszystkie przypięte wersje mieszkają teraz w inventory/group_vars/all/versions.yml: wartości zwięźle na górze, powody i historia poniżej. Renovate dostaje regex managery dokładnie dla tych linii i proponuje aktualizacje jako pull requesty – co tydzień, nigdy nie mergowane automatycznie. Lokalny dry run z kontenerem Renovate znalazł wszystkie 21 śledzonych wersji i od razu zaproponował nginx 1.31. To gałąź mainline; ja używam stable (parzysty minor). Są więc teraz barierki:
- nginx zostaje na parzystych wersjach minor.
- Majory (Nextcloud 35, MariaDB, Redis 8) i minory K3s/Calico tylko po akceptacji na dependency dashboardzie, z notatką, co trzeba zrobić.
- PR-y WP-CLI przypominają mi, żeby zaktualizować też sumę kontrolną SHA-512 – Renovate nie umie jej policzyć, a bez niej init container bloga odrzuciłby pobrany plik.
📚 A dokumentacja
Nowość w repo: „Jak działa kod Ansible” po niemiecku, angielsku i francusku – zmienne i ich pierwszeństwo, co się dzieje podczas uruchomienia, jak działają moduły Kubernetes, wzorce idempotencji, obsługa błędów, testy i ścieżka nauki. Aktualizacja istniejących przewodników wyciągnęła przy okazji kilka nieaktualnych faktów: starą wersję obrazu, opis Calico, który wciąż mówił „tylko Nextcloud”, tabelę zmiennych wskazującą zły plik.
🚀 Wdrożenie
Lokalne testy były zielone. Wtedy dałem Claude’owi plik z hasłem do vaulta (utworzony przeze mnie w terminalu, nigdy na czacie), a on uruchomił drift check na prawdziwych serwerach. Pierwsze uruchomienie na blogu się wywaliło – własny skrypt Claude’a potknął się o moduł dnf, który zwraca wyniki jako listę stringów zamiast obiektów. Naprawione, uruchomione ponownie, i wtedy przyszły prawdziwe znaleziska. Większość z nich siedziała w kodzie, który działał od miesięcy.
Co pokazały dopiero prawdziwe serwery
- Rola Grafany w ogóle nie umiała zrobić dry runa. Pyta API „czy datasource istnieje?” przez moduł
uri– który Ansible w check mode pomija – a następny task oceniał wtedy wynik, który nie istniał. Nieszkodliwe przy prawdziwych uruchomieniach, zabójcze dla--check. - Moja własna poprawka z punktu 4 była niekompletna. Dodałem
creates:, żebyfreshclamuruchamiał się tylko raz – ale zostawiłemchanged_when: true, co nadpisuje wynik „skipped, file exists”. Nadal za każdym razem zgłaszał „changed”, nic nie robiąc. - Ping-pong właściciela: playbook ustawiał
publickey.ascna root, coś innego przestawiało z powrotem na www-data – przy każdym uruchomieniu, niezauważone przez miesiące. - Binarki monitoringu Nextclouda były pobierane od nowa po każdym restarcie. Archiwa leżą w
/tmp, restart go opróżnia, a task pobierania nie miał żadnego warunku. Teraz najpierw sprawdza zainstalowaną wersję. - Przemianowane uprawnienie: użytkownik exportera MariaDB dostawał grant od nowa przy każdym uruchomieniu. Kod żądał
REPLICATION CLIENT, MariaDB 10.11 zgłasza to samo uprawnienie jakoBINLOG MONITOR, a moduł widział różnicę, której nie było. - 46 ostrzeżeń o deprecjacji dla zmiennych faktów na najwyższym poziomie (
ansible_kernelzamiastansible_facts['kernel']) – dziś w porządku, zepsute w przyszłym wydaniu Ansible.
Jedno pytanie wymagało więcej niż logu: czy Deployment Nextclouda się zmieni? Jego task jest no_log, bo niesie sekrety, więc diff jest ukryty. Restart oznacza krótką przerwę (strategia Recreate). Claude porównał obiekt na żywo z server-side dry runem apply i wypisał tylko nazwy różniących się pól, nigdy wartości: identyczne, poza adnotacją last-applied. Bez restartu.
Szybciej, skoro już przy tym byliśmy
Zapytałem, czy role mogłyby działać równolegle, żeby przyspieszyć. Szczera odpowiedź: nie na jednym hoście – Ansible przerabia taski hosta jeden po drugim, a prawdziwymi race conditions byłyby locki dnf oraz AIDE/rkhunter potrzebujące stanu końcowego. Bezpieczne zyski leżały gdzie indziej: AIDE porównuje i zapisuje teraz swoją baseline w jednym skanie zamiast dwóch (od 30 sekund do 3 minut na uruchomienie na blogu), a obiekty Kubernetes z jednego template’u idą do API jednym wywołaniem przy normalnych uruchomieniach – per obiekt tylko z --diff, gdzie liczy się czytelny diff. Samo Calico spadło z około 30 sekund do poniżej 2.
Prawdziwe uruchomienia
- Blog: MariaDB i Redis nietknięte, WordPress zrestartowany raz – sprawdziłem dlaczego: jedyną różnicą między starym a nowym pod template był znacznik
restartedAtz celowego restartu po aktualizacjach pluginów. Release’y Helma zostały na rewizji 87 (cert-manager) i 72 (ingress-nginx). Te liczby mówią wszystko: stary kod dokładał jedną rewizję na uruchomienie. Drift check potem: NO DRIFT. - sofie: żaden pod nie zrestartowany, rewizje Helma bez zmian, self-test notify_push zielony, NO DRIFT.
- cvjm (duży Nextcloud): ten sam obraz – żaden pod nie zrestartowany, rewizje Helma bez zmian, użytkownik exportera ma teraz
BINLOG MONITORi nie dostaje już ponownych grantów, NO DRIFT.
🎯 Wniosek
W liczbach: 16 commitów, 165 zmienionych plików, 0 błędów lintu, dwa nowe zestawy testów, trzy przestawione serwery – każdy zakończony NO DRIFT. Ale nie o liczby chodzi. Większość prawdziwych znalezisk pochodziła z testów, którym wolno było się wywalić: ukryta zależność od kolekcji, hasło do poczty, które nigdy nie pojawiało się jako zmiana, brakujący diff, test zielony z niewłaściwego powodu – i, gdy w grę weszły prawdziwe serwery, pół tuzina małych kłamstw w kodzie, który od miesięcy po cichu działał.
A moje pytanie wyjściowe? Repozytorium ma teraz ścieżkę nauki. Krok trzeci mówi: napisz rolę sam, bez szablonu. To już moje zadanie.
