Əməliyyatlar və İdarəetmə → Kod kimi əməliyyatların sənədləşdirilməsi

Kod kimi əməliyyatların sənədləşdirilməsi

1) Yanaşmanın mahiyyəti

Kod kimi sənədləşdirmə (Documentation as Code) - əməliyyat bilikləri, təlimatlar və proseslər kodla eyni qaydada saxlanılır, redaktə olunur və yoxlanılır: Git, pull-requests, review və CI-validasiya vasitəsilə.
Əməliyyat dövrəsində bu, komandaların etibarlılığı, şəffaflığı və uyğunluğu üçün əsas təşkil edir.

• Hər bir təlimat köhnəlmiş PDF deyil, infrastruktur artefaktıdır.

2) Niyə lazımdır

Şəffaflıq: proseduru kim, nə vaxt və nə üçün dəyişdirdiyini görmək olar.
Uyğunluq: bütün komandalar mövcud versiyalara uyğun işləyir.
CI/CD ilə inteqrasiya: təlimatların etibarlılığının avtomatik yoxlanılması.
Replikasiya: infrastruktur və sənədləşmə sinxronlaşdırılmışdır.
Təhlükəsizlik: Git vasitəsilə giriş nəzarəti və audit.
Onbordinq sürətləndirilməsi: yeni operatorlar kodla əlaqəli dəqiq ssenariləri görürlər.

3) Əsas obyektlər

4) Anbar arxitekturası

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

Məsləhət: Hər qovluq fərqli komandaların məzmunu müstəqil idarə edə bilməsi üçün öz Git-repositorudur və ya submoduldur.

5) Format və standartlar

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 və dəyişikliklər prosesləri

Pull Request = RFC sənədləşmə dəyişikliyi.
Review: Domain sahibi və Head of Ops təsdiq etməlidir.
CI-validasiya: strukturu, məcburi sahələri, Markdown/YAML linter yoxlama.
Avtomatik nəşr: merge sonra - HTML/wiki/dashboard generation.
Change log: tarixlər və müəlliflər ilə avtomatik dəyişiklik tarixi.
Alert-xatırlatmalar: sənədin hər N gündə bir yoxlanması (SLA üzrə).

7) CI/CD inteqrasiyası

Lint-yoxlama: Markdown-sintaksis, YAML-doğruluğu, owner/version sahələri.
Link-check: URL və daxili linklərin yoxlanılması.
Docs-build: HTML/Confluence/portala çevirmək.
Diff-analiz: sənədlərin son buraxılışından bəri nə dəyişdi.
Auto-sync: Grafana, Ops UI, Slack dashboard linklərinin yenilənməsi.
Review-botlar: köhnəlmiş bölmələr və ya mövcud olmayan sahiblər üçün ipuçları.

8) Əməliyyat alətləri ilə inteqrasiya

Grafana/Kibana: paneldən birbaşa müvafiq runbook üçün şərhlər və bağlantılar.
Incident Manager: biletin yaradılmasında «Open Runbook» düyməsi.
On-call portal: hadisə kateqoriyası üzrə aktual SOP və playbook verilməsi.
AI köməkçiləri: anbar axtarışı, TL generasiyası; DR və fəaliyyət məsləhətləri.
BCP panelləri: ssenari aktivləşdirildikdə avtomatik olaraq DR təlimatları yüklənir.

9) Sənədlərin həyat dövrünün idarə edilməsi

10) Avtomatlaşdırma və sinxronizasiya

Docs-bot: hansı sənədlərin köhnəldiyini yoxlayır.
Version badge: '! [last review: 2025-05]' düz papaq.
Runbook-finder: Alert etiketlə istədiyiniz sənədi açır.
Templates-generator: şablon əsasında yeni SOP ('make new-sop "Deployment' ') yaradır.
Audit-sync: SOP versiyasını sistemin buraxılışı və commit-ID ilə əlaqələndirir.

11) Təhlükəsizlik və məxfilik

RBAC anbarına: redaktəyə yalnız domen sahibləri daxil olur.
Sirlər və PII: açıq sənədlərdə saxlanılmamalıdır; yalnız qorunan vault linkləri.
Audit: bütün dəyişikliklər, review və nəşrlər log.
Yeniləmə siyasəti: hər 6 ayda bir SOP-ə yenidən baxılması.
Backups: DR zonasında müntəzəm anbar və keş portal şəkilləri.

12) Yetkinlik metrikası

13) Anti-nümunələr

Sənədlər Google Docs-da heç bir versiya və sahibləri olmadan saxlanılır.
Runbook buraxılışlardan sonra yenilənmir.
SOP köhnəlmiş komandalara/alətlərə istinad edir.
Heç bir CI-validasiya: Markdown səhvlər və sındırılmış bağlantılar ilə.
Eyni təlimatları müxtəlif yerlərdə təkrarlayın.
Sahiblərinin olmaması və review prosesi.

14) Giriş çek siyahısı

• Domen sahibləri və sənədləşmə məsul müəyyən edin.
• Git-repository 'ops-docs/' və SOP/runbook/playbook şablonları yaratmaq.
• CI-check və linter (Markdown/YAML) konfiqurasiya.
• Portal və ya Wiki-də avtomatik yayım qurun.
• Grafana/Incident Manager ilə inteqrasiya.
• Xatırlatmalar və SLA reviziyaları üçün Ops-bot əlavə edin.
• «docs-as-code workflow» üzrə komandalar üçün təlim keçirmək.

15) 30/60/90 - tətbiq planı

• Resepsiyon strukturu, şablonlar, CI-linter və PR-review prosesi yaratmaq.
• Əsas SOP və 5-10 kritik runbook köçürün.
• Portala auto-build qurun.

• Incident Manager və Grafana ilə inteqrasiyanı həyata keçirmək.
• Reviziyalar və hesabatlar üçün Ops-botu bağlayın.
• Postmortem şablonunu yeniləyin və hadisə dashboard ilə əlaqələndirin.

• Tam SOP/runbook əhatə (≥ 90%).
• KPI daxil edin: Coverage, Review SLA, Usage.
• «docs-as-code» prosesinin rahatlığı və keyfiyyətinə görə retro keçirin.

16) SOP nümunə (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) Digər proseslərlə inteqrasiya

Əməliyyat analitikası: Coverage və SLA reviziyaları üzrə hesabatlar.
Operator təlim: real runbook əsasında təlim.
Postmortemlər: SOP və playbook-a bağlantıları avtomatik daxil edin.
İdarəetmə etikası: dəyişikliklərin şəffaflığı və müəlliflik.
AI köməkçiləri: kontekstli axtarış və TL; DR anbardan.

18) FAQ

Q: Confluence varsa niyə Git?
A: Git versiyası verir, review, avtomatlaşdırma və oynatma. Confluence son vitrin ola bilər, lakin həqiqət mənbəyi deyil.

Q: Köhnə təlimatlardan necə qaçmaq olar?
A: SLA reviziya üçün (180 gün) + Ops-bot xatırlatmalar + son yoxlama avtomatik badge.

Q: CI-ni sənədlərə qoşmaq olarmı?
A: Bəli. Sintaksisin, məcburi sahələrin və sınıq linklərin yoxlanılması kod testlərinə bənzər standart pipeline kimi həyata keçirilir.