Operacje i → Dokumentacja zarządzania operacjami jako kod

Dokumentacja transakcji jako kod

1) W przedmiocie istoty podejścia

Dokumentacja jako kod jest praktyką, w której wiedza operacyjna, instrukcje i procesy są przechowywane, edytowane i zatwierdzane w taki sam sposób jak kod: poprzez Git, pull-requests, review, i CI validation.
W pętli operacyjnej stanowi to podstawę niezawodności, przejrzystości i kompatybilności poleceń.

• Stwórz żywy, powtarzalny i zweryfikowany system wiedzy, w którym każda instrukcja jest artefaktem infrastruktury, a nie przestarzałym plikiem PDF.

2) Dlaczego go potrzebujesz

Przejrzystość: widać, kto, kiedy i dlaczego zmienił procedurę.
Spójność: wszystkie zespoły pracują nad aktualnymi wersjami.
Integracja z CI/CD: automatyczna walidacja instrukcji.
Powtarzalność - Infrastruktura i dokumentacja są synchronizowane.
Bezpieczeństwo: kontrola dostępu i audyt za pośrednictwem Git.
Przyspieszenie pokładowe: Nowi operatorzy widzą dokładne scenariusze związane z kodem.

3) Główne obiekty

4) Architektura repozytorium

ops-docs/
├── README.md        # описание структуры
├── standards/
│  ├── sop-deploy.md
│  ├── sop-oncall.md
│  └── sop-release.md
├── runbooks/
│  ├── payments-latency.md
│  ├── games-cache.md
│  └── kyc-verification.md
├── playbooks/
│  ├── dr-failover.yaml
│  ├── psp-switch.yaml
│  └── safe-mode.yaml
├── postmortems/
│  └── 2025-03-17-bets-lag.md
├── policies/
│  ├── alerting.yaml
│  ├── communication.yaml
│  └── security.yaml
└── templates/
├── postmortem-template.md
├── sop-template.md
└── playbook-template.yaml

Wskazówka: każdy folder ma własne repozytorium Git lub submoduł, dzięki czemu różne zespoły mogą zarządzać treścią niezależnie.

5) Format i standardy

yaml id: sop-deploy owner: platform-team version: 3.2 last_review: 2025-10-15 tags: [deployment, ci-cd, rollback]
sla: review-180d

Цель
Контекст
Последовательность шагов
Проверка результата
Риски и откат
Контакты и каналы

yaml name: failover-psp triggers:
- alert: PSP downtime steps:
- action: check quota PSP-X
- action: switch PSP-Y
- action: verify payments latency < 200ms rollback:
- action: revert PSP-X

6) GitOps i procesy zmian

Pull Request = Zmiany w dokumentacji RFC.
Recenzja: Właściciel domeny i szef operacji muszą zatwierdzić.
Walidacja CI: kontrola struktury, pola obowiązkowe, liniowiec Markdown/YAML.
Automatyczne publikowanie: po połączeniu - generowanie desek rozdzielczych HTML/wiki.
Dziennik zmian: auto-historia zmian z datami i autorami.
Przypomnienia alarmowe: weryfikacja dokumentu co N dni (przez SLA).

7) integracja CI/CD

Sprawdzenie wiersza: składnia Markdown, ważność YAML, pola właściciela/wersji.
Link-check: sprawdzanie adresów URL i linków wewnętrznych.
Docs-build: konwersja do HTML/Confluence/portal.
Analiza Diff: co zmieniło się od ostatniego wydania dokumentacji.
Automatyczna synchronizacja: aktualizacja linków w deskach rozdzielczych Grafana, Ops UI, Slack.
Recenzja botów: wskazówki dla przestarzałych sekcji lub brakujących właścicieli.

8) Integracja z narzędziami operacyjnymi

Grafana/Kibana: adnotacje i linki do odpowiedniej książki startowej bezpośrednio z panelu.
Menedżer incydentu: przycisk „Otwórz Runbook” podczas tworzenia biletu.
Portal dyżurny: emisja bieżących SOP i odtwarzaczy według kategorii incydentów.
Asystenci AI: wyszukiwanie repozytorium, generacja TL; DR i porady działania.
Panele BCP - Automatycznie ładuje instrukcje DR po aktywacji skryptu.

9) Zarządzanie cyklem życia dokumentu

10) Automatyzacja i synchronizacja

Docs bot: sprawdzenie, które dokumenty są nieaktualne.
Odznaka wersji: '! [ostatni przegląd: 2025-05] "prawo w pułapie.
Runbook-finder: alert otwiera żądany dokument według tagu.
Generator szablonów: tworzy nowe jednostki SOP według szablonu ('make new-sop „Deployment”).
Synchronizacja audytu: Łączy wersję SOP z wydaniem systemu i commit-ID.

11) Bezpieczeństwo i prywatność

RBAC na repozytorium: tylko właściciele domeny mogą edytować.
Tajemnice i PII: Nie mogą być przechowywane w otwartych dokumentach; tylko linki do chronionych skarbców.
Audyt: dziennik wszystkich zmian, recenzji i publikacji.
Polityka aktualizacji: Przegląd SOP co 6 miesięcy.
Kopie zapasowe: regularne migawki repozytorium i bufory portalu w strefie DR.

12) Wskaźniki zapadalności

13) Anty-wzory

Dokumentacja jest przechowywana w Google Docs bez wersji i właścicieli.
Runbook nie jest aktualizowany po wydaniach.
SOP odnosi się do dotychczasowych poleceń/narzędzi.
Brak walidacji CI: Markdown z błędami i złamanymi linkami.
Powielanie tych samych instrukcji w różnych miejscach.
Brak właścicieli i proces przeglądu.

14) Lista kontrolna wdrażania

• Identyfikacja właścicieli domen i właścicieli dokumentów.
• Utwórz szablony repozytorium Git 'ops-docs/' i SOP/runbook/playbook.
• Konfigurowanie kontrolerów i linterów CI (Markdown/YAML).
• Skonfiguruj Auto-Publish do portalu lub Wiki.
• Integracja z Grafana/Incident Manager.
• Dodaj bot Ops dla przypomnień i rewizji SLA.
• Polecenia pracy docs-as-code pociągu.

15) 30/60/90 - plan realizacji

• Tworzenie struktury repozytorium, szablonów, lintera CI i procesu przeglądu PR.
• Migracja kluczowych SOP i 5-10 krytycznych książek startowych.
• Skonfiguruj auto-build w portalu.

• Wdrożenie integracji z menedżerem incydentów i Grafaną.
• Connect Ops bot do audytów i raportowania.
• Zaktualizuj szablon postmortem i link do incydentu deski rozdzielczej.

• Pełny zakres SOP/runbook (≥ 90%).
• Wprowadź KPI: Pokrycie, Przegląd SLA, Użycie.
• Retro na wygodę i jakość procesu „docs-as-code”.

16) Przykład szablonu SOP (Markdown)

SOP: Deployment через ArgoCD id: sop-deploy owner: platform-team last_review: 2025-10-15 tags: [deployment, rollback, argo]

Цель
Обеспечить безопасное и управляемое развертывание сервисов через ArgoCD.

Контекст
Используется для всех микросервисов с шаблоном Helm v2+.
Требует активного GitOps-контура и включенных health-checks.

Последовательность шагов
1. Проверить статус `argocd app list`
2. Выполнить `argocd app sync payments-api`
3. Убедиться, что `status: Healthy`
4. В случае проблем — `argocd app rollback payments-api --to-rev <rev>`

Проверка результата
SLO API доступность ≥ 99.95%, алертов нет.

Риски и откат
- Ошибка синхронизации — rollback.
- При повторных ошибках — эскалация Head of Ops.

Контакты
@platform-team / #ops-deploy

17) Integracja z innymi procesami

Analiza operacyjna: raporty z zakresu i audytu SLA.
Szkolenie operatora: szkolenie oparte na prawdziwych książkach startowych.
Postmortems: automatyczne wstawianie linków do SOP i playbook.
Etyka zarządzania: przejrzystość zmian i autorstwa.
Asystenci AI: wyszukiwanie kontekstowe i TL; DR z repozytorium.

18) FAQ

P: Dlaczego Git, jeśli jest Confluence?
Odp.: Git daje wersje, recenzję, automatyzację i odtwarzalność. Splątanie może być ostateczną prezentacją, ale nie źródłem prawdy.

P: Jak uniknąć przestarzałych instrukcji?
Odp.: SLA do wersji (180 dni) + boty Ops-reminder + automatyczna odznaka z ostatniego czeku.

P: Czy CI można podłączyć do dokumentacji?
Odp.: Tak. Składnia, wymagane pola i złamane odniesienia są sprawdzane jako standardowy rurociąg, podobny do testów kodowych.