ოპერაციები და მენეჯმენტი - ოპერაციების დოკუმენტაცია კოდად

ოპერატიული დოკუმენტაცია, როგორც კოდი

1) მიდგომის არსი

დოკუმენტაცია, როგორც კოდი, არის პრაქტიკა, რომლის თანახმად, ოპერაციული ცოდნა, ინსტრუქციები და პროცესები ინახება, რედაქტირებულია და შემოწმებულია ისევე, როგორც კოდი: Git, pull-requests, მიმოხილვა და 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 საცავი ან sabmodul, რათა სხვადასხვა გუნდს დამოუკიდებლად გააკონტროლოს შინაარსი.

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 დოკუმენტაციის ცვლილებები.
მიმოხილვა: დომენის მფლობელი და Ops Head უნდა დამტკიცდეს.
CI ვალდებულება: სტრუქტურის შემოწმება, სავალდებულო ველები, ლინტერი Markdown/YAML.
ავტომატური გამოცემა: მერის შემდეგ - HTML/VICI/dashboards- ის წარმოება.
Change log: ავტომობილების ისტორია თარიღებთან და ავტორებთან.
ალერტის შეხსენებები: დოკუმენტის გადასინჯვა ყოველ N დღეში (SLA- ს მიხედვით).

7) CI/CD ინტეგრაცია

Lint შემოწმება: Markdown სინტაქსი, YAML მოქმედება, owner/version ველები.
ლინკის შემოწმება: URL- ის შემოწმება და შიდა ბმულები.
Docs build: კონვერტაცია HTML/Confluence/პორტალში.
Diff ანალიზი: რა შეიცვალა დოკუმენტაციის ბოლო გამოშვებიდან.
Auto-sync: Grafana, Ops UI, Slack dashboards ბმულების განახლება.
მიმოხილვის ბოტები: მოძველებული მონაკვეთების ან დაკარგული მფლობელების მინიშნებები.

8) ოპერაციულ ინსტრუმენტებთან ინტეგრაცია

Grafana/Kibana: სურათები და ბმულები შესაბამის runbook- ზე პირდაპირ პანელიდან.
Incident Manager: ღილაკი „Open Runbook“ თიკეტის შექმნისას.
On-call პორტალი: შესაბამისი SOP და playbook გაცემა ინციდენტის კატეგორიაში.
AI თანაშემწეები: საცავის ძებნა, TL წარმოება; DR და საბჭოები მოქმედებების შესახებ.
BCP პანელები: DR ინსტრუქციის ავტომატური დატვირთვა სცენარის გააქტიურებისას.

9) დოკუმენტების სასიცოცხლო ციკლის მართვა

10) ავტომატიზაცია და სინქრონიზაცია

Docs-bot: ამოწმებს რომელი დოკუმენტები მოძველებულია.
Version badge: ''! [ბოლო მიმოხილვა: 2025-05] 'პირდაპირ ქუდში.
Runbook finder: Alert ხსნის სასურველ დოკუმენტს ჭდეზე.
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 შეცდომებით და გატეხილი ბმულები.
იგივე ინსტრუქციის დუბლირება სხვადასხვა ადგილას.
მფლობელების არარსებობა და მიმოხილვის პროცესი.

14) განხორციელების სია

• განსაზღვრეთ დომენის მფლობელები და პასუხისმგებელნი არიან დოკუმენტაციაზე.
• შექმენით Git საცავი 'ops docs/' და SOP/runbook/playbook შაბლონები.
• კონფიგურაცია CI შემოწმება და ლინტერი (Markdown/YAML).
• შეაკეთეთ ავტო პუბლიკაცია პორტალზე ან ვიკში.
• ინტეგრირება Grafana/Incident Manager- თან.
• დაამატეთ Ops bote შეხსენებები და SLA გადასინჯვები.
• ჩაატარეთ ტრენინგი გუნდებში „docs-as-code workflow“.

15) 30/60/90 - განხორციელების გეგმა

• შექმენით საცავის სტრუქტურა, შაბლონები, CI ლინტერი და PR რეპროდუქციის პროცესი.
• გადაიტანეთ ძირითადი SOP და 5-10 კრიტიკული runbook.
• შეაკეთეთ auto-build პორტალზე.

• ინტეგრაციის დანერგვა Incident Manager- სა და Grafana- სთან.
• დაუკავშირდით Ops bot- ს გადასინჯვისა და ანგარიშგებისთვის.
• განაახლეთ postmortem შაბლონი და დაუკავშირდით dashboard ინციდენტს.

• სრული 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- ის საფუძველზე.
Postmortems: ბმულების ავტომატური ჩანართი SOP და playbook.
მართვის ეთიკა: ცვლილებების გამჭვირვალობა და საავტორო უფლებები.
AI თანაშემწეები: კონტექსტური ძებნა და TL; DR საცავიდან.

18) FAQ

Q: რატომ არის Git, თუ არსებობს კონფერენცია?
A: Git იძლევა ვერსიებს, მიმოხილვას, ავტომატიზაციას და რეპროდუქციას. კონფერენცია შეიძლება იყოს საბოლოო ფანჯარა, მაგრამ არა სიმართლის წყარო.

Q: როგორ ავარიდოთ თავი მოძველებულ ინსტრუქციებს?
A: SLA გადასინჯვისთვის (180 დღე) + Ops bot შეხსენებები + ავტომატური ბოლო აუდიტის badge.

Q: შესაძლებელია CI- ს დოკუმენტაციასთან დაკავშირება?
ა: დიახ. სინტაქსის, სავალდებულო ველების და გატეხილი ბმულების შემოწმება ხორციელდება როგორც სტანდარტული მილის მსგავსი კოდის ტესტების მსგავსი.