Operatsiyalar va Boshqaruv → Operatsiyalar hujjatlari kod sifatida

Kod sifatida operatsiyalarni hujjatlashtirish

1) yondashuvning mohiyati

Hujjatlar kod sifatida (Documentation as Code) operatsion bilimlar, yo’riqnomalar va jarayonlar Git, pull-requests, review va CI-validatsiya orqali saqlanadigan, tahrirlanadigan va tekshiriladigan amaliyotdir.
Operatsion konturda bu jamoalarning ishonchliligi, shaffofligi va mosligi uchun asos yaratadi.

• Har bir yo’riqnoma eskirgan PDF emas, balki infratuzilma artefaktidir.

2) Nima uchun bu zarur?

Shaffoflik: protsedurani kim, qachon va nima uchun o’zgartirganini ko’rish mumkin.
Muvofiqlik: barcha jamoalar dolzarb versiyalar bo’yicha ishlaydi.
CI/CD bilan integratsiya: koʻrsatmalarni avtomatik tekshirish.
Replikatsiya: infratuzilma va hujjatlar sinxronlashtirilgan.
Xavfsizlik: Git orqali kirish va auditni nazorat qilish.
Onbordingning tezlashishi: yangi operatorlar kod bilan bog’liq aniq stsenariylarni ko’rishadi.

3) Asosiy obyektlar

4) Repozitorlik arxitekturasi

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: har bir jildning o’z Git-repozitoriyasi yoki sabmodul bo’lib, turli buyruqlar kontentni mustaqil ravishda boshqarishi mumkin.

5) Format va 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 va o’zgartirish jarayonlari

Pull Request = RFC hujjatlarni oʻzgartirish.
Review: Domen egasi va Head of Ops tasdiqlashi kerak.
CI-validatsiya: Markdown/YAML linteri, majburiy maydonlarning tuzilishini tekshirish.
Avtomatik nashr: merge - HTML/wiki/dashbordlarni yaratish.
Change log: sanalar va mualliflar bilan avto oʻzgarishlar tarixi.
Alert-eslatmalar: hujjatni har N kunda taftish qilish (SLA bo’yicha).

7) CI/CD integratsiyasi

Lint-tekshirish: Markdown-sintaksis, YAML-validlik, owner/version maydonlari.
Link-check: URL va ichki havolalarni tekshirish.
Docs-build: HTML/Confluence/portalga konvertatsiya qilish.
Diff-tahlil: hujjatlar chiqarilganidan beri nima o’zgardi.
Auto-sync: Grafana, Ops UI, Slack dashbordlaridagi bogʻlarni yangilash.
Review-botlar: eskirgan seksiyalar yoki mavjud bo’lmagan egalar bo’yicha maslahatlar.

8) Operatsion vositalar bilan integratsiya

Grafana/Kibana: paneldan tegishli runbook izohlari va havolalari.
Incident Manager: «Open Runbook» tugmasi.
On-call portali: hodisalar toifasi bo’yicha dolzarb SOP va playbook berish.
AI yordamchilari: repozitoriya bo’yicha qidirish, TL ishlab chiqarish; DR va harakatlar bo’yicha maslahatlar.
BCP panellari: stsenariyni faollashtirishda DR koʻrsatmalarini avtomatik yuklash.

9) Hujjatlarning hayot siklini boshqarish

10) Avtomatlashtirish va sinxronlashtirish

Docs-bot: qaysi hujjatlar eskirganligini tekshiradi.

Version badge: ’! [last review: 2025-05] ’

Runbook-finder: alertda kerakli hujjatni tag boʻyicha ochadi.
Templates-generator: yangi SOPlarni yaratadi (’make new-sop "Deployment’’).
Audit-sync: SOP versiyasini tizim relizi va commit-ID bilan bogʻlaydi.

11) Xavfsizlik va maxfiylik

RBAC - faqat domen egalari uchun tahrirlash imkoniyati.
Sirlar va PII: ochiq hujjatlarda saqlash mumkin emas; faqat himoyalangan vault havolalari.
Audit: barcha o’zgarishlar, revyu va nashrlar jurnali.
Yangilanishlar siyosati: SOPni har 6 oyda qayta koʻrib chiqish.
Backups: DR-zonadagi repozitoriya va keshning muntazam suratlari.

12) Etuklik metrikasi

13) Anti-patternlar

Hujjatlar Google Docs’da versiyasiz va egasiz saqlanadi.
Runbook chiqishlardan keyin yangilanmaydi.
SOP eskirgan buyruqlar/vositalarga murojaat qiladi.
Hech qanday CI validatsiyasi yoʻq: Markdown xato va tugmalangan havolalar.
Bir xil yo’riqnomalarni turli joylarda takrorlash.
Mulk egalari va review-jarayon yo’qligi.

14) Joriy etish chek-varaqasi

• Domen egalari va hujjatlar uchun mas’ullarni aniqlash.
• Git’ops-docs/’ va SOP/runbook/playbook shablonlarini yaratish.
• CI tekshirish va linterlarni moslash (Markdown/YAML).
• Avto- postni portal yoki Wikiga moslash.
• Grafana/Incident Manager bilan integratsiya qilish.
• Ogohlantirishlar va SLA taftishlari uchun Ops-bot qoʻshish.
• «docs-as-code workflow» boʻyicha jamoalarni oʻqitish.

15) 30/60/90 - joriy etish rejasi

• Repozitoriya tuzilishi, namunalar, CI-linter va PR-revyu jarayonini yaratish.
• Asosiy SOP va 5-10 tanqidiy runbook’larni koʻchirish.
• Auto-build’ni portalga moslash.

• Incident Manager va Grafana bilan integratsiyani joriy etish.
• Taftish va hisobot uchun Ops-botni ulash.
• Postmortem namunasini yangilash va hodisani dashbord bilan bogʻlash.

• SOP/runbook toʻliq qamrovi (90% ≥).
• KPI: Coverage, Review SLA, Usage kiritilsin.
• «docs-as-code» jarayonining qulayligi va sifati bo’yicha retro o’tkazish.

16) SOP (Markdown) namunasi

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) Boshqa jarayonlar bilan integratsiya qilish

Operatsion tahlil: Coverage va SLA taftishlari bo’yicha hisobotlar.
Operatorlarni oʻqitish: real runbook asosida mashq qilish.
Postmortemalar: SOP va playbook bogʻlamalarini avtomatik qoʻyish.
Boshqaruv odobi: o’zgarishlarning shaffofligi va mualliflik.
AI yordamchilari: kontekstli qidiruv va TL; Repozitoriyadan DR.

18) FAQ

Q: Agar Confluence mavjud bo’lsa, nima uchun Git?
A: Git versiyalar, review, avtomatlashtirish va takrorlanuvchanlikni beradi. Confluence haqiqat manbai emas, balki oxirgi vitrin boʻlishi mumkin.

Q: Qanday qilib eskirgan yo’riqnomalardan qochish mumkin?
A: SLA taftish uchun (180 kun) + Ops-bot-eslatmalar + oxirgi tekshiruvning avtomatik badge.

Q: CI’ni hujjatlarga ulash mumkinmi?
A: Ha. Sintaksis, majburiy maydonlarni va sindirilgan havolalarni tekshirish kod testlariga oʻxshash standart pipeline sifatida amalga oshiriladi.