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.

Ilustracja do artykułu o porządkowaniu kodu Ansible

🌐 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

#UlepszenieDlaczego
1Obiekty Kubernetes przez kubernetes.core.k8s zamiast kubectl apply przez shellidempotentne, prawdziwe diffy, działa w check mode
2Sprawić, by --check był naprawdę użytecznydry run przed każdym uruchomieniem na produkcji
3ansible-lint, yamllint i secret scanner jako hook pre-commit i GitHub Actionłapać błędy i wycieki sekretów, zanim trafią do repo
4Automatyczny test idempotencjidrugie uruchomienie musi zgłosić changed=0
5Ścieżki rescue w playbookach aktualizacjiokreślona reakcja, gdy aktualizacja padnie w połowie
6Podzielić duże pliki z taskamiplik na 912 linii nie jest niczyim przyjacielem
7meta/argument_specs.yml dla rólbrakująca zmienna wywala się na starcie, nie w połowie
8Połączyć zduplikowane rolejedna rola ClamAV zamiast dwóch prawie identycznych
9Przypiąć dokładne wersje kolekcji>= po cichu wpuszcza major release łamiący kompatybilność
10Renovate dla przypiętych wersjipropozycje 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 --install uruchamiał się przy każdym playu i za każdym razem dokładał nową rewizję. kubernetes.core.helm poró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_file nie istnieje. Działało tylko dzięki przestarzałemu przekierowaniu do community.general – kolekcji, której nawet nie było w requirements.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 wersji k3s --version | awk … || echo 'not installed' nigdy nie mogło wypisać „not installed”: bez pipefail liczy się tylko kod wyjścia awk.

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, gdy needsDbUpgrade jest 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-tags przed i po, identyczne.
  • 7 – argument specs: 23 role deklarują swoje wejścia. „Wymagane” jest liczone per typ hosta: wspólne role czytają blog_hostname na jednym serwerze i nextcloud_hostname na 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.0 zmieniło się w 3.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:, żeby freshclam uruchamiał się tylko raz – ale zostawiłem changed_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.asc na 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 jako BINLOG 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_kernel zamiast ansible_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 restartedAt z 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 MONITOR i 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.

Powiązane wpisy

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