Операції та Управління → Документація операцій як код

Документація операцій як код

1) Суть підходу

Документація як код (Documentation as Code) - це практика, при якій операційні знання, інструкції та процеси зберігаються, редагуються і перевіряються так само, як код: через Git, pull-requests, review і CI-валідацію.
В операційному контурі це формує основу для надійності, прозорості та сумісності команд.

• Створити живу, відтворювану і версіоновану систему знань, де кожна інструкція - артефакт інфраструктури, а не застарілий PDF.

2) Навіщо це потрібно

Прозорість: видно, хто, коли і навіщо змінив процедуру.
Узгодженість: всі команди працюють за актуальними версіями.
Інтеграція з CI/CD: автоматична перевірка валідності інструкцій.
Репліковність: інфраструктура та документація синхронізовані.
Безпека: контроль доступу та аудит через Git.
Прискорення онбордингу: нові оператори бачать точні сценарії, пов'язані з кодом.

3) Основні об'єкти

4) Архітектура репозиторію

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

Порада: кожна папка - свій Git-репозиторій або сабмодуль, щоб різні команди могли керувати контентом незалежно.

5) Формат і стандарти

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 і процеси змін

Pull Request = RFC зміни документації.
Review: власник домену і Head of Ops повинні схвалити.
CI-валідація: перевірка структури, обов'язкових полів, лінтер Markdown/YAML.
Автоматична публікація: після merge - генерація HTML/вікі/дашбордів.
Change log: авто-історія змін з датами та авторами.
Alert-нагадування: ревізія документа кожні N днів (по SLA).

7) CI/CD-інтеграція

Lint-перевірки: Markdown-синтаксис, YAML-валідність, поля owner/version.
Link-check: перевірка URL і внутрішніх посилань.
Docs-build: конвертація в HTML/Confluence/портал.
Diff-аналіз: що змінилося з минулого релізу документації.
Auto-sync: оновлення посилань в дашбордах Grafana, Ops UI, Slack.
Review-боти: підказки по застарілих секціях або відсутнім власникам.

8) Інтеграція з операційними інструментами

Grafana / Kibana: анотації та посилання на відповідні runbook прямо з панелі.
Incident Manager: кнопка «Open Runbook» при створенні тікету.
On-call портал: видача актуальних SOP і playbook по категорії інциденту.
AI-помічники: пошук по репозиторію, генерація TL; DR і порад щодо дій.
BCP-панелі: автоматичне завантаження DR-інструкцій при активації сценарію.

9) Управління життєвим циклом документів

10) Автоматизація та синхронізація

Docs-бот: перевіряє, які документи застаріли.
Version badge: `![last review: 2025-05]'прямо в шапці.
Runbook-finder: за алертом відкриває потрібний документ за тегом.
Templates-generator: створює нові SOP за шаблоном ('make new-sop «Deployment»').
Audit-sync: пов'язує версію SOP з релізом системи і commit-ID.

11) Безпека і приватність

RBAC на репозиторій: доступ до редагування тільки у власників доменів.
Секрети та PII: не можна зберігати у відкритих документах; тільки посилання на захищені vault.
Аудит: лог всіх змін, рев'ю і публікацій.
Політика оновлень: перегляд SOP кожні 6 місяців.
Backups: регулярні знімки репозиторію і портал-кеші в DR-зоні.

12) Метрики зрілості

13) Анти-патерни

Документація зберігається в Google Docs без версій і власників.
Runbook не оновлюється після релізів.
SOP посилається на застарілі команди/інструменти.
Немає CI-валідації: Markdown з помилками і биті посилання.
Дублювання одних і тих же інструкцій в різних місцях.
Відсутність власників і review-процесу.

14) Чек-лист впровадження

• Визначити власників доменів і відповідальних за документацію.
• Створити Git-репозиторій'ops-docs/' і шаблони SOP/runbook/playbook.
• Налаштувати CI-перевірки та лінтери (Markdown/YAML).
• Налаштувати авто-публікацію в портал або Wiki.
• Інтегрувати з Grafana/Incident Manager.
• Додати Ops-бота для нагадувань і SLA-ревізій.
• Провести навчання команд з «docs-as-code workflow».

15) 30/60/90 - план впровадження

• Створити структуру репозиторію, шаблони, CI-лінтер і процес PR-рев'ю.
• Перенести ключові SOP і 5-10 критичних runbook.
• Налаштувати auto-build в портал.

• Впровадити інтеграції з Incident Manager і Grafana.
• Підключити Ops-бота для ревізій і звітності.
• Оновити постмортем-шаблон і пов'язати з інцидент-дашбордом.

• Повне охоплення SOP/runbook (≥90%).
• Ввести KPI: Coverage, Review SLA, Usage.
• Провести ретро по зручності і якості «docs-as-code» процесу.

16) Приклад шаблону 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) Інтеграція з іншими процесами

Операційна аналітика: звіти по Coverage і SLA ревізій.
Навчання операторів: тренування на підставі реальних runbook.
Постмортеми: автоматична вставка посилань на SOP і playbook.
Етика управління: прозорість змін і авторство.
AI-помічники: контекстний пошук і TL; DR з репозиторію.

18) FAQ

Q: Навіщо Git, якщо є Confluence?
A: Git дає версії, review, автоматизацію і відтворюваність. Confluence може бути кінцевою вітриною, але не джерелом правди.

Q: Як уникнути застарілих інструкцій?
A: SLA на ревізію (180 днів) + Ops-бот-нагадування + автоматичний badge останньої перевірки.

Q: Чи можна підключити CI до документації?
A: Так. Перевірка синтаксису, обов'язкових полів і битих посилань виконується як стандартний pipeline, аналогічно тестам коду.