Amallar we Dolandyryş → Kod hökmünde amallaryň resminamalary

Amallary kod hökmünde resminamalaşdyrmak

1) Çemeleşmäniň düýp manysy

Kod hökmünde resminamalaşdyrmak (Documentation as Code) - bu amal bilimleriniň, görkezmeleriniň we amallarynyň Git, pull-requests, review we CI-tassyklama arkaly kod ýaly saklanýan, redaktirlenen we barlanylýan tejribedir.
Operasiýa konturynda bu toparlaryň ygtybarlylygy, aç-açanlygy we sazlaşygy üçin esas döredýär.

• Her bir görkezme köne PDF däl-de, infrastruktura artefaktydyr.

2) Bu näme üçin zerur?

Aç-açanlyk: prosedurany kimiň, haçan we näme üçin üýtgedendigini görmek bolýar.
Ylalaşyklylyk: ähli toparlar häzirki wersiýalar boýunça işleýär.
CI/CD bilen integrasiýa: görkezmeleriň dogrulygyny awtomatiki barlamak.
Köpelmek ukyby: infrastruktura we resminamalar sinhronlaşdyryldy.
Howpsuzlyk: Git arkaly giriş gözegçiligi we audit.
Onbordingiň tizlenmegi: täze operatorlar kod bilen baglanyşykly takyk ssenariýalary görýärler.

3) Esasy obýektler

4) Repozitoryň arhitekturasy

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

Maslahat: Dürli toparlar mazmuny özbaşdak dolandyryp biler ýaly, her bukjanyň öz Git-repozitory ýa-da sabmodul.

5) Format we 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 we üýtgetmek prosesleri

Pull Request = RFC resminamalaryny üýtgetmek.
Syn: Domen eýesi we Head of Ops tassyklamaly.
CI-tassyklama: gurluşy, hökmany meýdanlary, Markdown/YAML linterini barlamak.
Awtomatiki neşir etmek: merge - HTML/wiki/dashboard döretmek.
Change log: seneler we awtorlar bilen awto-taryhy.
Alert-ýatlatmalar: her N günde resminama gözden geçirmek (SLA boýunça).

7) CI/CD integrasiýasy

Lint-barlaglar: Markdown-sintaksis, YAML-tassyklama, owner/wersiýa meýdanlary.
Link-check: URL we içerki baglanyşyklary barlamak.
Docs-build: HTML/Confluence/portala öwürmek.
Diff-analiz: resminamalaryň soňky çykarylmagyndan bäri näme üýtgedi.
Awto-sync: Grafana, Ops UI, Slack dashbordlaryndaky baglanyşyklary täzelemek.
Syn-botlar: köne bölümler ýa-da ýok eýeler boýunça maslahatlar.

8) Amal gurallary bilen integrasiýa

Grafana/Kibana: panelden degişli runbook düşündirişleri we baglanyşyklary.
"Incident Manager": "Açyk Runbook" düwmesi.
On-call portal: wakanyň kategoriýasy boýunça aktual SOP we playbook bermek.
AI-kömekçileri: repozitory gözlemek, TL döretmek; DR we hereketler boýunça maslahatlar.
BCP panelleri: Ssenarini işjeňleşdireniňizde awtomatiki usulda DR görkezmelerini ýükläň.

9) Resminamalaryň durmuş siklini dolandyrmak

10) Awtomatlaşdyryş we sinhronlaşdyrma

Docs-bot: haýsy resminamalaryň köne bolandygyny barlaýar.
Version badge: '! [last review: 2025-05]' gönüden-göni şlýapada.
Runbook-finder: alert belligi boýunça zerur resminamany açýar.
Templates-generator: şablon boýunça täze SOP döredýär ('make new-sop' Deployment '').
Audit-sync: SOP wersiýasyny ulgamyň we commit-ID-iň çykmagy bilen baglanyşdyrýar.

11) Howpsuzlyk we gizlinlik

Repozitoriýa RBAC: redaktirlemäge diňe domen eýeleriniň elýeterliligi.
Syrlar we PII: açyk resminamalarda saklanyp bilinmez; diňe ygtybarly vault baglanyşyklary.
Audit: ähli üýtgeşmeleriň, seslenmeleriň we neşirleriň sanawy.
Täzelenmeler syýasaty: SOP-e her 6 aýda täzeden seredilýär.
Backups: DR zolagynda yzygiderli reseptler we keş portaly.

12) Kämillik ölçegleri

13) Anti-patternler

Resminamalar Google Docs-da wersiýalar we eýeler bolmazdan saklanýar.
Runbook goýberilenden soň täzelenmeýär.
SOP köne buýruklara/gurallara salgylanýar.
CI tassyklamasy ýok: Markdown we döwülen baglanyşyklar.
Şol bir görkezmeleri dürli ýerlerde köpeltmek.
Eýeleriniň we gözden geçiriş prosesiniň ýoklugy.

14) Girizmegiň çek-sanawy

• Domen eýelerini we dokumentasiýa üçin jogapkärleri kesgitlemek.
• Git-repozitory 'ops-docs/' we SOP/runbook/playbook şablonlaryny dörediň.
• CI barlaglaryny we linterlerini sazla (Markdown/YAML).
• Awto-neşirini portala ýa-da Wiki-e sazla.
• Grafana/Incident Manager bilen integrasiýa.
• Ýatlatmalar we SLA barlaglary üçin Ops-bot goşuň.
• "docs-as-code workflow" boýunça toparlara tälim bermek.

15) 30/60/90 - durmuşa geçirmek meýilnamasy

• Repozitoryň gurluşyny, şablonlaryny, CI-linterini we PR-review prosesini dörediň.
• Esasy SOP we 5-10 möhüm runbook göçüriň.
• Auto-build -y portala sazla.

• "Incident Manager" we "Grafana" bilen integrasiýalary girizmek.
• Barlaglar we hasabat üçin Ops-boty birikdirmek.
• Postmortem şablonyny täzelemek we dashbord hadysasy bilen baglanyşdyrmak.

• SOP/runbook doly (90% ≥).
• KPI giriň: Coverage, Review SLA, Usage.
• "docs-as-code" prosesiniň amatlylygy we hili boýunça retro geçirmek.

16) SOP şablonynyň mysaly (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) Beýleki prosesler bilen integrasiýa

Amal seljermesi: Coverage we SLA barlaglary boýunça hasabatlar.
Operatorlary taýýarlamak: hakyky runbook esasynda okuw.
Postmortemalar: SOP we playbook baglanyşyklaryny awtomatiki goýmak.
Dolandyryş etikasy: üýtgeşmeleriň aç-açanlygy we awtorlyk.
AI kömekçileri: kontekstli gözleg we TL; DR.

18) FAQ

Q: Confluence bar bolsa näme üçin Git?
A: Git wersiýalary, synlary, awtomatlaşdyrmagy we köpeldilmegini berýär. Confluence hakykatyň çeşmesi däl-de, ahyrky vitrin bolup biler.

Q: Köne görkezmelerden nädip gaça durmaly?
A: SLA (180 gün) + Ops-bot-ýatlatmalar + soňky barlagyň awtomatiki badge.

Q: CI-ni resminamalara birikdirip bolarmy?
A: Hawa. Sintaksisi, hökmany meýdanlary we döwülen baglanyşyklary barlamak kod synaglaryna meňzeş standart pipeline hökmünde amala aşyrylýar.