Ə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 # 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

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

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 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]

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) 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.