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.

🌐 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
| # | Verbetering | Waarom |
|---|---|---|
| 1 | Kubernetes-objecten via kubernetes.core.k8s in plaats van kubectl apply via shell | idempotent, echte diffs, werkt in check mode |
| 2 | --check echt bruikbaar maken | een dry run vóór elke productierun |
| 3 | ansible-lint, yamllint en een secret scanner als pre-commit-hook en GitHub Action | fouten en gelekte secrets vangen voordat ze binnenkomen |
| 4 | Geautomatiseerde idempotentietest | de tweede run moet changed=0 melden |
| 5 | rescue-paden in de update-playbooks | een vastgelegde reactie als een update halverwege faalt |
| 6 | De grote taakbestanden opsplitsen | een bestand van 912 regels is niemands vriend |
| 7 | meta/argument_specs.yml voor de rollen | een ontbrekende variabele faalt aan het begin, niet halverwege |
| 8 | Dubbele rollen samenvoegen | één ClamAV-rol in plaats van twee bijna identieke |
| 9 | Collectieversies exact vastpinnen | >= laat ongemerkt een major release met breaking changes binnen |
| 10 | Renovate voor de versiepins | updatevoorstellen 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 --installdraaide bij elke play en stapelde elke keer een nieuwe revisie op.kubernetes.core.helmvergelijkt 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_filebestaat niet. Het werkte alleen via een legacy-redirect naarcommunity.general– een collectie die niet eens inrequirements.ymlstond. 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 konk3s --version | awk … || echo 'not installed'nooit “not installed” printen: zonderpipefailtelt alleen de exitcode vanawk.
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 alsneedsDbUpgradefalse 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-tagservoor en erna, identiek. - 7 – argument specs: 23 rollen declareren hun inputs. “Verplicht” wordt per hosttype berekend: gedeelde rollen lezen
blog_hostnameop de ene server ennextcloud_hostnameop de andere, dus geen van beide mag verplicht zijn. Gecontroleerd tegen de echte variabelen van alle drie de servers. Vault-waarden zijnno_log– geverifieerd dat ze noch met-vvvnoch 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.0werd3.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 zodatfreshclammaar één keer draait – maarchanged_when: truelaten 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.ascop 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 alsBINLOG MONITOR, en de module zag een verschil dat er geen was. - 46 deprecation-waarschuwingen voor fact-variabelen op topniveau (
ansible_kernelin plaats vanansible_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 MONITORen 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.
