De Ansible-tour, deel 1: één repository, drie servers – hoe de code is georganiseerd en wat er tijdens een run gebeurt
Deel 1 van een tour door mijn Ansible-code: hoe één repository en 34 roles een blog en twee Nextclouds draaien, en wat er tijdens een playbook-run gebeurt.

🌐 Ook in: English · Deutsch · Français · Español · Italiano · Português · Polski
Eerste deel van een serie over de Ansible-code achter deze blog en twee Nextcloud-servers. De code is openbaar: github.com/aptupgrademe/www_k3s; de serie beschrijft release v3.3.0. Deel 1 legt de structuur uit en wat er tijdens een run gebeurt, deel 2 tot 6 de roles, de deep dives de techniek eronder.
Drie servers, 34 roles, vier playbooks, zo’n 22.000 regels YAML en templates. Wie de repository voor het eerst opent, ziet vooral bestanden. Dit deel legt drie dingen uit die je het best eerst weet: hoe één set roles twee heel verschillende applicaties bedient, waar elke waarde vandaan komt, en wat er werkelijk gebeurt tussen ansible-playbook en de eindsamenvatting.
Inhoud
🧩 Eén repository voor twee applicaties
De blog (WordPress) en de twee Nextcloud-servers hebben op het eerste gezicht weinig gemeen. Daaronder hebben ze echter dezelfde dingen nodig: een geharde AlmaLinux, een firewall, SSH alleen met sleutel, K3s, TLS-certificaten, monitoring, logs, bescherming tegen brute-force-aanvallen. Daarom zijn de roles genoemd naar waar ze worden gebruikt:
common_*draait op elke server: firewall, SSH, K3s, Grafana, fail2ban en een goede twintig andere.blog_*bestaat alleen voor WordPress,next_*alleen voor Nextcloud.
Twee derde van de code is gedeeld. Een fix aan de firewall bereikt alle drie de servers bij de volgende run, en een gat dat een Nextcloud blootlegt, wordt ook voor de blog gedicht.
De prijs is een regel die nooit pauze neemt: elke wijziging aan een gedeelde role moet op beide stacks werken. Hoe het eruitziet als dat alleen op papier klopt, liet een bug zien die op 26 oktober 2026 werd gevonden: het fail2ban-filter voor Nextcloud-logins controleerde alleen POST /login. Nextcloud stuurt zijn loginformulier echter naar /index.php/login. Het filter draaide sinds juli op beide Nextcloud-servers en telde geen enkele poging; de rate limit ervoor zag de requests ook niet. Het kwam pas aan het licht toen een test de filters een echte logregel voerde in plaats van alleen te controleren of fail2ban draaide.
De les: gedeelde code bespaart werk, maar heeft tests nodig die het resultaat controleren. Dat een dienst geconfigureerd is en draait, bewijst niet dat hij doet wat hij moet doen.
📒 Waar elke waarde vandaan komt
De roles beschrijven wat er moet gebeuren. De inventory bepaalt waarmee: welke servers er zijn, welke waarden voor allemaal gelden en welke maar voor één.
hosts.ymlbevat niets dan de indeling: welke server bij de groepbloghoort, welke bijnextcloud.group_vars/all/bevat wat overal gelijk is. Het belangrijkste bestand daar isversions.yml: elke versie die een playbook installeert (K3s, Helm, container-images, exporters) staat in precies dat bestand, tot op patchniveau. Nooitlatest, nooit een tag als10.11. Zo’n tag had de blog in augustus op een verouderde MariaDB-image laten staan, nog gecachet op de node, hoewel Docker Hub al lang een nieuwere onder dezelfde naam had.host_vars/<host>/bevat twee bestanden per server:vars.ymlmet adressen, groottes en schakelaars,vault.ymlmet de wachtwoorden, versleuteld met Ansible Vault. Geen van beide staat in de publieke repository. Wat wel openbaar is, is een.example-bestand ernaast dat laat zien welke keys een host nodig heeft.
Als een waarde op meerdere plekken is gedefinieerd, beslist de voorrang van Ansible: de defaults van de role zijn het uitgangspunt, group_vars overschrijven ze, host_vars overschrijven beide. Een voorbeeld is het landenfilter voor SSH: in de role staat het uit, en een server zet het aan met één regel in zijn vars.yml.
Zodat een ontbrekende waarde niet halverwege een run opduikt als obscure templatefout, declareren 23 roles hun invoer in meta/argument_specs.yml. Ansible controleert die voordat de role zijn eerste task draait.
De les: een versie die niet exact is vastgepind, wordt in werkelijkheid door de cache vastgepind.
🔀 Hoe een gedeelde role de stacks uit elkaar houdt
Een common_*-role moet soms weten waar hij draait. Nextcloud heeft MariaDB en Redis op de host, de blog heeft beide in containers; de firewall heeft op Nextcloud daarom twee regels meer nodig. Hiervoor zijn er drie patronen, in volgorde van voorkeur:
- Het playbook zegt het. Elk volledig playbook zet een variabele
stack: wordpressofstack: nextcloud. Dat is de enige plek waar de beslissing valt; de roles lezen alleen deze variabele. - Eén profiel per stack. Roles die op beide stacks hetzelfde soort werk doen met verschillende paden – de SELinux-labels voor de gemounte mappen, bijvoorbeeld – houden beide lijsten in hun defaults en kiezen er één op basis van
stack. - De server vragen. Of een server zijn adres via DHCP krijgt, staat in geen enkele variabele; de firewall vraagt het aan NetworkManager. Zonder de DHCP-regels zou het adres bij de volgende lease-vernieuwing weg zijn.
Tot versie 3.2 beslisten de roles op basis van de groepsnamen in de inventory. Dat ging mis op de testserver, die in beide groepen zit: tijdens een blog-installatie opende de firewall de databasepoorten van Nextcloud, en Prometheus probeerde Nextcloud-exporters te scrapen die daar niet bestonden.
De les: de beslissing hoort op één plek – waar bekend is wat er wordt geïnstalleerd, in het playbook, niet in de inventory.
📜 De volgorde in het playbook is een keten van afhankelijkheden
Er zijn vier playbooks: per applicatie één voor de volledige run en één voor updates. Een volledig playbook is een lijst van zo’n 25 roles, en de volgorde volgt de afhankelijkheden, niet het alfabet:
- SELinux vóór de deployment. De pods mounten mappen van de host. Als die nog niet het label
container_file_tdragen, blokkeert SELinux elke schrijfactie, en MariaDB start niet. - Monitoring na de deployment. Prometheus scrapet de exporters in de pods, en fail2ban leest de ingress-logs; beide bestaan pas na de deployment.
- AIDE altijd als laatste. AIDE vergelijkt elke nacht de systeembestanden met een baseline. Een run wijzigt bewust bewaakte bestanden, dus de laatste role vernieuwt de baseline.
Elke role draagt een tag met zijn eigen naam. Dat maakt van het volledige playbook een precies gereedschap: --tags blog_k3s_deploy brengt alleen de Kubernetes-objecten bij. Precies daar lag een valkuil die een vaste regel werd: een run met --tags slaat de laatste role over, de AIDE-baseline blijft oud, en ’s nachts komt er een mail over gewijzigde bestanden. Sindsdien volgt op elke getagde run een tweede met --tags common_rkhunter,common_aide_refresh.
De update-playbooks herstarten de applicatie en zijn daarom defensief geschreven: ze weigeren te draaien zonder --limit, updaten geen instantie die al vastzit in de onderhoudsmodus, en doen het werk in een block met een rescue die, als er iets misgaat, laat zien in welke toestand de instantie achterblijft.
De les: wie een role verplaatst, verplaatst een afhankelijkheid. De volgorde is onderdeel van de code.
⚙️ Wat er tijdens een run gebeurt
Verbinden. Ansible logt als root in via SSH met een sleutel; SSH accepteert geen wachtwoord. Daarna verzamelt het alleen de paar facts die de roles nodig hebben: distributie, kernel, hostnaam.
Eerst een rapport. De eerste role wijzigt niets. Voor K3s, Helm, de ingress en cert-manager vergelijkt hij wat er geïnstalleerd is, wat versions.yml vastpint en wat de nieuwste release is. Wie de run start, ziet of iets verouderd is voordat er iets verandert.
Task voor task. Ansible draait task 1 op elke host in de run, dan task 2, enzovoort. Elke task meldt ok (niets te doen), changed of failed. Hier zit de belangrijkste eigenschap van de roles: idempotentie. Een tweede run direct na de eerste moet changed=0 melden. Dat maakt van het playbook een controlegereedschap: meldt het een wijziging op een server die met de code zou moeten overeenkomen, dan is dat óf drift – iemand heeft met de hand iets veranderd – óf een bug in de task. Daarvoor lezen de tasks eerst de toestand en wijzigen alleen wat afwijkt. Diensten worden niet bij elke gelegenheid herstart, maar via handlers die één keer aan het einde draaien, en alleen als hun configuratie echt veranderd is.
De dry run. Met --check --diff loopt Ansible door elke task, wijzigt niets en laat zien wat het zou wijzigen. Het script scripts/check-drift.sh filtert alleen de tasks eruit die iets zouden wijzigen. Exitcode 0 betekent: de server is precies wat de code beschrijft.
Het oordeel. Een run die eindigt met ok zegt alleen dat elke task deed wat hem werd opgedragen. Of de applicatie daarna werkt, controleren aan het einde de verify-roles: 30 tot 38 checks per server, een gekleurd rapport, een mail, en de run faalt als een kritieke check niet slaagt. Sinds 26 oktober 2026 horen daar effecttests bij: elk fail2ban-filter krijgt een echte logregel, en elke jail bant kort een testadres dat in de kernel moet aankomen.
En altijd de ene host na de andere: twee parallelle runs op dezelfde server botsten in oktober op de lock van de pakketdatabase.
De les: changed=0 bij de tweede run is geen cosmetisch detail. Het is wat elke echte afwijking laat opvallen.
🧪 Hoe een wijziging een server bereikt
De servers zijn productie: bestanden van andere mensen en een blog met lezers. Een wijziging doorloopt daarom altijd dezelfde fasen, van snel en lokaal naar langzaam en echt:
- Wijziging: de role, het template of
versions.yml. - Linting:
ansible-lintenyamllintover de hele repository; bij de commit controleert gitleaks ook op wachtwoorden en sleutels. - Test zonder server, waar een test bestaat (Kubernetes-roles, update-playbooks).
- Dry run met
check-drift.shen de vraag: is dit precies wat ik wilde? Al het andere op de lijst is een verrassing die je eerst moet begrijpen. - Echte run op één server, met
--tagsbeperkt tot wat de wijziging raakt. - Opnieuw de drift-check: nu moet hij “no drift” zeggen.
- Commit en push; de CI controleert de hele repository nog een keer.
Geen van deze fasen leunt erop dat iemand iets onthoudt. De enige regel die handwerk blijft: echte runs worden door een mens gestart, de ene host na de andere, nadat de dry run is gelezen.
🎯 De vijf lessen van deel 1
- Gedeelde roles besparen werk, maar alleen met tests die het effect controleren in plaats van de toestand.
- Pin elke versie exact vast, op één plek.
- De beslissing “blog of Nextcloud” hoort in het playbook.
- De volgorde van de roles is een keten van afhankelijkheden.
- Idempotentie maakt van een playbook een controlegereedschap.
🧭 Waar de tour hierna heen gaat
- Deel 2 – Het platform: hoe een verse AlmaLinux een basissysteem wordt met K3s, Helm, cert-manager en een ingress, met exacte versies.
- Deel 3 – WordPress en Deel 4 – Nextcloud: de applicaties, hun pods en wat er tijdens updates gebeurt.
- Deel 5 – Beveiliging: firewall, SSH, fail2ban, hardening, SELinux, detectie.
- Deel 6 – Monitoring: Prometheus, Grafana, Loki, alerts.
Elk deel volgt hetzelfde raster: wat een role doet, waarom hij zo gebouwd is, en wat er onderweg misging. Dat laatste punt is meestal het leerzaamst.
