Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Release prebehol.
Aplikácia prestala fungovať.
Vývojár hovorí:
„Na dev to ide.“
DevOps odpovie:
„Na serveri je to nasadené správne.“
Tester vidí:
„Systém nefunguje.“
Nakoniec sa zistí:
chýbal konfiguračný parameter v produkcii.
Nikde nebolo napísané:
- čo má byť nastavené
- kde
- v akej hodnote
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v deploymente.
Problém je, že chýba dokumentácia pre prevádzku.
V mnohých projektoch existuje:
- dokumentácia pre používateľa
- dokumentácia pre vývoj
Ale chýba:
- dokumentácia pre infra a DevOps
Výsledok:
- systém sa síce vyvinie
- ale nedá sa spoľahlivo prevádzkovať
Skutočné náklady (čas, chaos, riziko)
Keď chýba infra dokumentácia:
- release je rizikový
- konfigurácie sa nastavujú manuálne
- prostredia sa líšia
- incidenty sa riešia naslepo
Typická situácia:
systém funguje
ale len v jednom prostredí
Minimálny model riešenia
Netreba komplexný DevOps manuál.
Treba základnú prevádzkovú mapu.
1. Prostredia
Musí byť jasné:
- dev
- test
- staging
- produkcia
A rozdiely medzi nimi:
- konfigurácia
- prístupy
- obmedzenia
2. Nasadenie (deployment)
- ako sa aplikácia nasadzuje
- aké kroky treba vykonať
- čo sa kontroluje po nasadení
Bez toho je každý release experiment.
3. Konfigurácia
- zoznam parametrov
- hodnoty pre jednotlivé prostredia
- kritické nastavenia
Toto je častý zdroj problémov.
4. Závislosti
- externé služby
- databáza
- infra komponenty
Musí byť jasné, čo systém potrebuje, aby fungoval.
5. Monitoring a logy
- kde sa sleduje stav systému
- kde sa nachádzajú logy
- čo sa kontroluje pri incidente
6. Recovery scenáre
- čo robiť pri výpadku
- ako reštartovať službu
- ako rollbacknúť verziu
Príklad
Bez dokumentácie:
„Po deploymente to nefunguje.“
S dokumentáciou:
- nasadenie prebehlo
- parameter X chýba
- služba Y nie je dostupná
Zrazu je jasné:
čo skontrolovať
kde je problém
čo opraviť
Mini checklist
Sú definované prostredia?
Je popísaný deployment?
Je jasná konfigurácia?
Sú uvedené závislosti?
Je popísaný monitoring?
Existujú recovery scenáre?
Ak nie, systém nie je pripravený na prevádzku.
Prepojenie na kvalitu a workflow
DevOps dokumentácia nie je len pre infra tím.
Je základ pre:
- stabilné release
- testovanie v správnom prostredí
- rýchle riešenie incidentov
Pre testera:
Bez nej nevieš:
- v akom prostredí testuješ
- čo má byť nastavené
- prečo sa systém správa inak
Krátke zhrnutie
Systém nestačí vyvinúť.
Treba ho vedieť:
nasadiť
nastaviť
sledovať
opraviť
Ak chýba dokumentácia pre DevOps:
- vzniká chaos
- release je riziko
Ak existuje:
- systém je stabilný
- tím vie reagovať
A to je základ spoľahlivej prevádzky.