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

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

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

დოკუმენტაცია, როგორც კოდი, არის პრაქტიკა, რომლის თანახმად, ოპერაციული ცოდნა, ინსტრუქციები და პროცესები ინახება, რედაქტირებულია და შემოწმებულია ისევე, როგორც კოდი: Git, pull-requests, მიმოხილვა და CI.
საოპერაციო წრეში, ეს ქმნის გუნდების საიმედოობის, გამჭვირვალობისა და თავსებადობის საფუძველს.

• შექმენით ცოდნის ცოცხალი, რეპროდუქციული და ვერსირებული სისტემა, სადაც თითოეული ინსტრუქცია არის ინფრასტრუქტურის არტეფაქტი და არა მოძველებული PDF.

2) რატომ არის ეს აუცილებელი?

გამჭვირვალობა: აშკარაა ვინ, როდის და რატომ შეცვალა პროცედურა.
კოორდინაცია: ყველა გუნდი მუშაობს მიმდინარე ვერსიებზე.
ინტეგრაცია CI/CD- სთან: ინსტრუქციის მოქმედების ავტომატური შემოწმება.
რეპლიკაცია: ინფრასტრუქტურა და დოკუმენტაცია სინქრონიზებულია.
უსაფრთხოება: წვდომის კონტროლი და აუდიტი Git- ის საშუალებით.
ონბორდინგის დაჩქარება: ახალი ოპერატორები კოდთან დაკავშირებულ ზუსტ სცენარებს ხედავენ.

3) ძირითადი ობიექტები

4) საცავის არქიტექტურა

ops-docs/
├── README. md # structure description
├── 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

Purpose
Context
Step sequence
Result check
Risks and rollbacks
Contacts and channels

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]

Purpose
Ensure secure and managed deployment of services via ArgoCD.

Context
Used for all microservices with Helm v2 + pattern.
Requires an active GitOps loop and enabled health-checks.

Step sequence
1. Check status' argocd app list'
2. Execute'argocd app sync payments-api '
3. Make sure 'status: Healthy'
4. In case of problems - 'argocd app rollback payments-api --to-rev <rev>'

Result check
SLO API availability ≥ 99. 95%, no alerts.

Risks and rollback
- Synchronization error - rollback.
- On repeated errors - Head of Ops escalation.

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