Architektonická rozhodnutí

Každý záznam popisuje kontext, rozhodnutí a jeho důsledky. Přijaté záznamy se už neupravují; změněné rozhodnutí dostane nový záznam, který ten starý nahradí.

ADR	Rozhodnutí	Stav
001	k3s přímo na notebooku	Přijato
002	Ubuntu Server bez grafického prostředí	Přijato
003	k3s jako distribuce Kubernetes	Přijato
004	Cloudflare Tunnel pro veřejný přístup	Přijato
005	Tailscale pro správu	Přijato
006	Správa clusteru jen na serveru	Přijato
007	GitOps s Flux (pull model)	Přijato
008	Soukromý repozitář a soukromý registr image	Přijato
009	Statický dokumentační web v Hugo	Přijato

ADR-001: k3s přímo na notebooku

Kontext. Jediný hardware je notebook s 8 GB RAM. Možnosti: WSL2 + kind ve Windows, VM pod Windows, nebo Linux přímo na hardwaru.

Rozhodnutí. Ubuntu Server vedle Windows (dual boot) a k3s přímo na něm.

Důsledky.

✅ všechna paměť pro workloady, provoz 24/7, stabilní adresa v LAN
✅ Windows zůstávají k dispozici
❌ jeden node = jediný bod selhání; obnova stojí na Gitu a zálohách

ADR-002: Ubuntu Server bez grafického prostředí

Kontext. Grafické prostředí stojí 1,5–2 GB RAM. Node se spravuje vzdáleně.

Rozhodnutí. Ubuntu Server LTS bez GUI, správa jen přes SSH.

Důsledky.

✅ víc paměti pro cluster, menší útočná plocha
❌ veškerá práce v terminálu

ADR-003: k3s jako distribuce Kubernetes

Kontext. Cluster musí běžet na jednom nodu s 8 GB a odpovídat verzi zkoušky CKAD (Kubernetes v1.35).

Rozhodnutí. k3s, kanál v1.35.

Důsledky.

✅ jedna binárka včetně containerd, Flannel, CoreDNS, Traefik a local-path úložiště
✅ certifikovaný Kubernetes, stejné API jako na zkoušce
❌ správa clusteru se liší od kubeadm; na CKA je potřeba samostatný kubeadm cluster ve VM

ADR-004: Cloudflare Tunnel pro veřejný přístup

Kontext. Web má být veřejný. Node je na Wi-Fi za dvojitým NATem bez zaručené veřejné IPv4. Port forwarding by vystavil domácí síť skenování.

Rozhodnutí. Konektor cloudflared v clusteru otevře odchozí tunel do Cloudflare; ven se publikuje jen HTTP do Traefiku.

Důsledky.

✅ žádné příchozí porty, HTTPS a ochrana proti DDoS od Cloudflare, vlastní doména
❌ veřejný provoz závisí na Cloudflare; token tunelu je přihlašovací údaj, který se musí chránit

ADR-005: Tailscale pro správu

Kontext. SSH musí fungovat z Macu a iPadu i mimo domácí síť. Možnosti: port forwarding, Cloudflare Access/WARP, Tailscale.

Rozhodnutí. Tailscale na serveru, Macu a iPadu. Autentizaci dál dělá OpenSSH s klíči; Tailscale SSH se nepoužívá.

Důsledky.

✅ žádné příchozí porty, server není z internetu vidět, Termius funguje beze změn
✅ nezávislé na Cloudflare, takže node zůstane dostupný i při výpadku veřejné cesty
❌ na každém zařízení pro správu musí běžet klient Tailscale; může kolidovat s jinými VPN

ADR-006: Správa clusteru jen na serveru

Kontext. Na Macu jsou kubeconfigy i pro jiné clustery. Administrátorský certifikát homelabu na pracovní stanici zvyšuje riziko příkazu do špatného clusteru.

Rozhodnutí. kubectl a k9s běží na serveru přes SSH. Na Macu žádný kubeconfig homelabu.

Důsledky.

✅ administrátorský certifikát nikdy neopustí node, žádná záměna kontextů
✅ stejný způsob práce jako na zkoušce CKAD (terminál na vzdáleném stroji)
❌ grafické nástroje na Macu (Lens, pluginy v IDE) nejsou k dispozici

ADR-007: GitOps s Flux (pull model)

Kontext. Nasazení má proběhnout automaticky po git push. GitHub se do clusteru nedostane a otevřít mu přístup by bylo v rozporu s ADR-004 a ADR-005.

Rozhodnutí. GitHub Actions sestaví a publikuje image; Flux v clusteru si repozitář stáhne a aplikuje. Git je jediný zdroj pravdy.

Důsledky.

✅ mimo cluster nejsou žádné přístupy do clusteru; Flux používá deploy klíč jen pro čtení
✅ ruční odchylky se automaticky vrací; rollback je git revert
❌ ruční změny v clusteru jen s pozastaveným Fluxem, jinak je vrátí
❌ od pushe po web ~1,5–3 minuty

ADR-008: Soukromý repozitář a soukromý registr image

Kontext. Repozitář obsahuje konfiguraci infrastruktury. Image obsahuje jen veřejný obsah, ale nemá být veřejně dostupný.

Rozhodnutí. Soukromý repozitář na GitHubu a soukromý balíček v GHCR; cluster stahuje image s tokenem read:packages uloženým jako Secret ghcr-pull.

Důsledky.

✅ konfigurace i image vidí jen vlastník
❌ v clusteru je token, který jednou ročně vyprší a musí se obnovit

ADR-009: Statický dokumentační web v Hugo

Kontext. Dokumentace má být verzovaná spolu s infrastrukturou, veřejná, dvojjazyčná a levná na provoz přímo na nodu.

Rozhodnutí. Hugo s vlastní šablonou (bez externích témat a CDN), servírované přes nginx bez root práv, čeština a angličtina vedle sebe.

Důsledky.

✅ rychlé, statické, na serveru se nic nespouští; možná přísná CSP
✅ obsah je Markdown ve stejném repozitáři jako konfigurace clusteru
❌ šablonu je potřeba udržovat vlastními silami