Tien punten, één branch: mijn Ansible-code van “het werkt” naar “het is schoon”

Tien verbeteringen aan mijn Ansible-code, getest zonder productie aan te raken: kubernetes.core, een echte dry run, lint, secret scan, rescue, Renovate.

Illustratie bij het artikel over het opschonen van de Ansible-code

🌐 Ook in: English · Deutsch · Français · Español · Italiano · Português · Polski

Het begon met een ietwat ijdele vraag. Mijn Ansible-repository draait deze blog en twee Nextcloud-servers: 34 rollen, vier playbooks, zo’n 9.000 regels YAML, bijna 200 commits. De meeste van die regels heb ik niet zelf geschreven – dat deed mijn AI-co-admin (Claude), terwijl ik besliste, testte en de playbooks draaide. Dus vroeg ik: als ik het grootste deel van deze code begrijp, ben ik dan een gevorderde Ansible-gebruiker?

Het antwoord was eerlijk en een beetje ongemakkelijk: gevorderd in lezen en beheren, ja. Gevorderd in het van nul af aan schrijven, nog niet bewezen. En toen volgde een lijst van tien dingen die de code zelf beter zouden maken. Ik zei: doe ze alle tien. Test ze goed. Schrijf er daarna over. Dit is die post.

Basisregels, zoals altijd: alles gebeurt op een aparte Git-branch, niets raakt een productieserver tot ik het draai, en elke bewering wordt getest. “Getest” bleek het interessante deel te zijn.

Inhoud

📋 De tien punten

#VerbeteringWaarom
1Kubernetes-objecten via kubernetes.core.k8s in plaats van kubectl apply via shellidempotent, echte diffs, werkt in check mode
2--check echt bruikbaar makeneen dry run vóór elke productierun
3ansible-lint, yamllint en een secret scanner als pre-commit-hook en GitHub Actionfouten en gelekte secrets vangen voordat ze binnenkomen
4Geautomatiseerde idempotentietestde tweede run moet changed=0 melden
5rescue-paden in de update-playbookseen vastgelegde reactie als een update halverwege faalt
6De grote taakbestanden opsplitseneen bestand van 912 regels is niemands vriend
7meta/argument_specs.yml voor de rolleneen ontbrekende variabele faalt aan het begin, niet halverwege
8Dubbele rollen samenvoegenéén ClamAV-rol in plaats van twee bijna identieke
9Collectieversies exact vastpinnen>= laat ongemerkt een major release met breaking changes binnen
10Renovate voor de versiepinsupdatevoorstellen als pull requests in plaats van handmatig uitzoeken

Halverwege voegde ik een elfde wens toe: alle versiepins op één plek, zodat ik in één oogopslag zie wat waar draait. Meer daarover bij punt 10.

🧪 Eerste probleem: hoe test je Kubernetes-code zonder productie aan te raken?

Vroeger stond er een testserver in de inventory. Toen Claude die probeerde te bereiken, weigerde SSH: host key verification failed. Het IP-adres is inmiddels waarschijnlijk van iemand anders, dus maakte het bewust geen verbinding. En mijn vault-wachtwoord geef ik niet weg in een chat, dus kon er ook geen playbook tegen de echte servers draaien.

De oplossing was netjes: een wegwerp-K3s in rootless podman op mijn jump host. Een volledige K3s faalde meteen (failed to find cpuset cgroup – rootless containers krijgen die controller niet gedelegeerd). Maar om te testen of manifests idempotent worden toegepast, heb je helemaal geen draaiende pods nodig, alleen de API-server. K3s heeft precies daarvoor een flag:

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

Een klein vervangscript speelt k3s kubectl: het stuurt alles door naar de container en beantwoordt de commando’s die draaiende pods nodig zouden hebben (exec, rollout status, wait) met “prima”. De test doet dan waar het om gaat: alles toepassen met de oude code uit main (zo staan de servers erbij), daarna de nieuwe code eroverheen draaien – dry run, echte run, nog een echte run, nog een dry run.

1️⃣ kubernetes.core in plaats van kubectl apply

Het oude patroon kwam 29 keer voor: een template renderen naar /tmp, kubectl apply -f, het bestand verwijderen en “changed” raden door in de output naar het woord configured te zoeken. Het nieuwe patroon rendert in het geheugen en praat rechtstreeks met de 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 }}"

Drie dingen kwamen alleen door de test boven water:

  • De eerste dry run zei “changed” bij bijna alles – zonder diff. Het blijkt dat de module geen diff toont als je hem een lijst objecten geeft. Eén loop-iteratie per object loste het op, en nu zegt de diff precies image: redis:7.4.11-alpine → redis:7.4.12-alpine.
  • De eenmalige migratie herschrijft alleen de annotatie last-applied-configuration (kubectl schrijft er een lege "annotations":{} in, de module niet). Spec en pod template blijven identiek, dus geen pod-herstarts – gecontroleerd via de ReplicaSet-revisies, allemaal nog op 1.
  • Helm: helm upgrade --install draaide bij elke play en stapelde elke keer een nieuwe revisie op. kubernetes.core.helm vergelijkt chartversie en values en doet niets als ze overeenkomen. Addertje: Helm 4 wordt pas ondersteund vanaf collectieversie 6.5.0; het distropakket leverde 6.1.0.

Bijeffect waar ik erg blij mee ben: Kubernetes-Secrets gaan niet meer via een bestand in /tmp op de server.

2️⃣ Een dry run die iets betekent

In check mode slaat Ansible elke shell/command-taak over – ook de onschuldige die alleen iets lezen. Latere taken die die resultaten evalueren falen dan of beslissen op basis van niets. 94 pure queries (versiechecks, occ config:system:get, systemctl is-active …) hebben nu check_mode: false. Alles wat schrijft wordt nog steeds overgeslagen – en waar dat een openstaande wijziging zou verbergen, meldt een kleine extra taak die.

3️⃣ Lint, secret scan, hooks

De eerste ansible-lint-run meldde 811 bevindingen. Zo’n 600 waren stijlregels die ingaan tegen bewuste keuzes (uitgelijnde kolommen, gedeelde variabelenamen zonder rolprefix) – die staan uit, met een schriftelijke reden. De rest is opgelost. Twee echte vondsten:

  • ansible.builtin.ini_file bestaat niet. Het werkte alleen via een legacy-redirect naar community.general – een collectie die niet eens in requirements.yml stond. Op een controller met kale ansible-core was het Nextcloud-playbook precies daar gestopt.
  • 27 shell-pipes zonder pipefail. Meestal onschuldig, maar in de versiecheck kon k3s --version | awk … || echo 'not installed' nooit “not installed” printen: zonder pipefail telt alleen de exitcode van awk.

gitleaks scande alle 191 commits van de geschiedenis: één hit, een PASTE_CONTENT_OF_id_rsa_HERE-placeholder tussen twee key-markers in een oud voorbeeldbestand. Bewust geaccepteerd, gedocumenteerd. De hooks draaien nu bij elke commit – en de eerste commit die ze blokkeerden was die van Claude zelf, een paar uur later (verkeerde YAML-inspringing in gegenereerde bestanden). Precies waarvoor ze dienen.

4️⃣ Idempotentie, getest

De podman-test is nu onderdeel van de repo (tests/k8s/run.sh). Hij faalt als de tweede run nog iets verandert, een pod zou worden uitgerold, een Helm-release een nieuwe revisie krijgt – of als een bewust gewijzigde image-tag niet wordt gedetecteerd. Dat laatste is belangrijk: een test die nooit kan falen, bewijst niets.

Voor de echte servers is er scripts/check-drift.sh <playbook> <host>: een dry run die alleen print wat er zou veranderen, met een leesbare diff. Direct na een echte run moet hij NO DRIFT zeggen.

Onderweg zijn een paar taken gerepareerd die bij elke run “changed” meldden (signature-download, een databasegebruiker, een dnf-module). De gemeenste vondst was het omgekeerde: de negen SMTP-instellingen van Nextcloud werden bij elke run herschreven en meldden altijd “ok”. Een gewijzigd mailwachtwoord zou nooit als wijziging zijn opgevallen. Nu worden ze eerst gelezen, vergeleken, en alleen afwijkende waarden geschreven – doorgegeven via argv, zodat een aanhalingsteken in een wachtwoord het commando niet kan breken.

5️⃣ Als een update halverwege faalt

Claudes eerste voorstel was “in de rescue netjes de maintenance mode verlaten”. Na wat nadenken corrigeerde het zichzelf: na een afgebroken occ upgrade zet het uitschakelen van de maintenance mode gebruikers op een half geüpgradede instantie. De logica nu:

  • Een pre-flight-check buiten het block: geïnstalleerd, niet in maintenance mode, geen openstaande DB-upgrade – anders weigert het playbook te starten. Bewust erbuiten: de rescue mag alleen omgaan met toestanden die de run zelf heeft veroorzaakt.
  • De rescue verzamelt occ-status, pods, events en de laatste regels van nextcloud.log, en zet de maintenance mode alleen uit als needsDbUpgrade false is. Daarna stopt hij, zodat er geen tweede server wordt aangeraakt.
  • Bonus: de update-playbooks herstartten Nextcloud en Collabora bij elke run. Een kleine nieuwe rol vergelijkt de digest van elk vers gepulld image met wat de pods draaien en herstart alleen wat echt opnieuw gebouwd is – exporters en notify_push inbegrepen.

Getest met nep-kubectl/crictl in 14 scenario’s. En dan het belangrijke stuk: de rescue bewust breken (maintenance altijd uitzetten) en de test opnieuw draaien. Hij werd rood bij precies het juiste scenario. Daarvoor had dezelfde test een keer “alles groen” laten zien om de verkeerde reden – twee scenario’s met dezelfde naam deelden een directory en haalden hun logs door elkaar. Groen betekent weinig zolang je de test niet hebt zien falen.

6️⃣ tot 9️⃣ De stillere

  • 6 – opsplitsen: de WordPress-rol (912 regels) bestaat nu uit zeven thematische bestanden, Grafana uit drie, de verify-rollen elk uit twee. Bewijs dat er niets veranderde: --list-tasks --list-tags ervoor en erna, identiek.
  • 7 – argument specs: 23 rollen declareren hun inputs. “Verplicht” wordt per hosttype berekend: gedeelde rollen lezen blog_hostname op de ene server en nextcloud_hostname op de andere, dus geen van beide mag verplicht zijn. Gecontroleerd tegen de echte variabelen van alle drie de servers. Vault-waarden zijn no_log – geverifieerd dat ze noch met -vvv noch in een validatiefout verschijnen.
  • 8 – samenvoegen: één ClamAV-rol en één SELinux-rol met een profiel per stack, plus 16 gedeelde smoke checks. Valkuil vermeden: Ansible herkent cron-entries aan hun naam, dus de namen moesten exact gelijk blijven – anders was de oude job naast de nieuwe blijven draaien.
  • 9 – pins: >=3.0.0 werd 3.15.0. Renovates dry run liet zien waarom dat ertoe doet: majors 5.x en 13.x stonden al klaar.

🔟 Renovate, en alle versies in één bestand

Alle versiepins staan nu in inventory/group_vars/all/versions.yml: de waarden compact bovenaan, de redenen en geschiedenis eronder. Renovate krijgt regex-managers voor precies deze regels en stelt updates voor als pull requests – wekelijks, nooit automatisch gemerged. Een lokale dry run met de Renovate-container vond alle 21 gevolgde pins en stelde prompt nginx 1.31 voor. Dat is de mainline-branch; ik draai de stable (even minor). Dus zijn er nu vangrails:

  • nginx blijft op even minorversies.
  • Majors (Nextcloud 35, MariaDB, Redis 8) en K3s/Calico-minors alleen na goedkeuring op het dependency dashboard, met een notitie over wat er moet gebeuren.
  • WP-CLI-PR’s herinneren me eraan ook de SHA-512-checksum bij te werken – Renovate kan die niet berekenen, en zonder die checksum zou de init-container van de blog de download weigeren.

📚 En de documentatie

Nieuw in de repo: “Hoe de Ansible-code werkt” in het Duits, Engels en Frans – variabelen en hun voorrang, wat er tijdens een run gebeurt, hoe de Kubernetes-modules werken, idempotentiepatronen, foutafhandeling, de tests en een leerpad. Het bijwerken van de bestaande handleidingen leverde als bonus wat verouderde feiten op: een oude imageversie, een Calico-beschrijving die nog “alleen Nextcloud” zei, een variabelentabel die naar het verkeerde bestand wees.

🚀 De uitrol

De lokale tests waren groen. Toen gaf ik Claude het vault-wachtwoordbestand (door mij in de terminal aangemaakt, nooit in de chat) en draaide het de drift check tegen de echte servers. De allereerste run tegen de blog crashte – Claudes eigen script struikelde over de dnf-module, die zijn resultaten teruggeeft als lijst strings in plaats van objecten. Gerepareerd, opnieuw gedraaid, en toen kwamen de echte vondsten binnen. De meeste zaten in code die al maanden draaide.

Wat alleen de echte servers lieten zien

  • De Grafana-rol kon helemaal geen dry run doen. Hij vraagt de API “bestaat de datasource?” via de uri-module – die Ansible in check mode overslaat – en de volgende taak evalueerde dan een resultaat dat niet bestond. Onschuldig bij echte runs, fataal voor --check.
  • Mijn eigen fix van punt 4 was onvolledig. Ik had creates: toegevoegd zodat freshclam maar één keer draait – maar changed_when: true laten staan, wat het resultaat “skipped, file exists” overschrijft. Hij meldde nog steeds elke keer “changed” terwijl hij niets deed.
  • Een eigenaars-pingpong: het playbook zette publickey.asc op root, iets anders zette het terug op www-data – bij elke run, maandenlang onopgemerkt.
  • De monitoringbinaries van Nextcloud werden na elke reboot opnieuw gedownload. De archieven staan in /tmp, een reboot maakt dat leeg, en de downloadtaak had geen voorwaarde. Nu controleert hij eerst de geïnstalleerde versie.
  • Een hernoemd privilege: de MariaDB-exportergebruiker kreeg bij elke run opnieuw een grant. De code vroeg om REPLICATION CLIENT, MariaDB 10.11 meldt hetzelfde privilege als BINLOG MONITOR, en de module zag een verschil dat er geen was.
  • 46 deprecation-waarschuwingen voor fact-variabelen op topniveau (ansible_kernel in plaats van ansible_facts['kernel']) – vandaag prima, kapot in een toekomstige Ansible-release.

Eén vraag vroeg om meer dan een log: zou de Nextcloud-Deployment veranderen? De taak daarvan is no_log omdat hij secrets bevat, dus de diff is verborgen. Een herstart betekent een korte onderbreking (Recreate-strategie). Claude vergeleek het live-object met een server-side dry run van de apply en printte alleen de namen van afwijkende velden, nooit waarden: identiek op de last-applied-annotatie na. Geen herstart.

Sneller, nu we toch bezig waren

Ik vroeg of rollen parallel konden draaien om het te versnellen. Eerlijk antwoord: niet op één host – Ansible werkt de taken van een host na elkaar af, en de echte race conditions zouden dnf-locks zijn en AIDE/rkhunter die de eindtoestand nodig hebben. De veilige winst zat elders: AIDE vergelijkt en schrijft zijn baseline nu in één scan in plaats van twee (30 seconden tot 3 minuten per run op de blog), en de Kubernetes-objecten van een template gaan bij normale runs in één call naar de API – per object alleen met --diff, waar de leesbare diff ertoe doet. Calico alleen al ging van zo’n 30 seconden naar minder dan 2.

De echte runs

  • Blog: MariaDB en Redis onaangeroerd, WordPress één keer herstart – ik heb nagekeken waarom: het enige verschil tussen oude en nieuwe pod template was de restartedAt-stempel van de bewuste herstart na plugin-updates. De Helm-releases bleven op revisie 87 (cert-manager) en 72 (ingress-nginx). Die getallen zeggen alles: de oude code voegde per run een revisie toe. Drift check daarna: NO DRIFT.
  • sofie: geen pod herstart, Helm-revisies ongewijzigd, notify_push-selftest groen, NO DRIFT.
  • cvjm (de grote Nextcloud): hetzelfde beeld – geen pod herstart, Helm-revisies ongewijzigd, de exportergebruiker heeft nu BINLOG MONITOR en krijgt niet meer steeds een nieuwe grant, NO DRIFT.

🎯 Conclusie

In cijfers: 16 commits, 165 bestanden aangeraakt, 0 lint-fouten, twee nieuwe testsuites, drie servers omgezet – elk eindigend met NO DRIFT. Maar de cijfers zijn niet het punt. De meeste echte vondsten kwamen uit tests die mochten falen: de verborgen collectie-afhankelijkheid, het mailwachtwoord dat nooit als wijziging verscheen, de ontbrekende diff, de test die groen was om de verkeerde reden – en, zodra de echte servers meededen, een half dozijn kleine leugens in code die al maanden stilletjes draaide.

En mijn beginvraag? De repository heeft nu een leerpad. Stap drie zegt: schrijf zelf een rol, zonder template. Die is voor mij.

Gerelateerde posts

Sommige teksten en afbeeldingen op deze site zijn met hulp van AI gemaakt of door AI gegenereerd. Details