Операциялар және басқару → Код ретінде операциялардың құжаттамасы

Операциялардың құжаттамасы код ретінде

1) Тәсілдің мәні

Құжаттама код ретінде (Documentation as Code) - бұл операциялық білім, нұсқаулықтар мен процестер Git, pull-requests, review және 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-репозиторийі немесе сабмодулі, сондықтан түрлі пәрмендер мазмұнды тәуелсіз басқара алады.

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 құжаттама өзгертулері.
шолу: домен иесі және Head of Ops мақұлдауы керек.
CI-валидация: құрылымды, міндетті өрістерді, Markdown/YAML линтерін тексеру.
Автоматты жариялау: merge - HTML/вики/дашбордтарды генерациялаудан кейін.
Change log: авторлары мен күндерінің авто-тарихы.
Alert-ескертулер: құжатты әрбір N күн сайын тексеру (SLA бойынша).

7) CI/CD-интеграция

Lint-тексерулер: Markdown-синтаксис, YAML-дәлдігі, owner/version өрістері.
Link-check: URL және ішкі сілтемелерді тексеру.
Docs-build: HTML/Confluence/порталға түрлендіру.
Diff-талдау: өткен құжаттама шығарылымынан бері не өзгерді.
Auto-sync: Графана, Ops UI, Slack дашбордтарындағы сілтемелерді жаңарту.
Review-боттар: ескірген секциялар немесе жоқ иелері бойынша кеңестер.

8) Операциялық құралдармен интеграциялау

Grafana/Kibana: түсіндірмелер және тікелей тақтадан тиісті runbook сілтемелері.
Incident Manager: тикет жасау кезінде «Open Runbook» түймешігі.
On-call порталы: инцидент санаты бойынша өзекті SOP және playbook беру.
AI-көмекшілері: репозиторий бойынша іздеу, TL генерациясы; DR және әрекеттер бойынша кеңестер.
BCP тақтасы: сценарийді белсендіргенде DR нұсқауларын автоматты түрде қотару.

9) Құжаттардың өмірлік циклін басқару

10) Автоматтандыру және синхрондау

Docs-бот: қандай құжаттардың ескіргенін тексереді.
Version badge: '! [last review: 2025-05]' тура қалпақта.
Runbook-finder: алерт бойынша тегпен қажетті құжатты ашады.
Templates-generator: үлгі бойынша жаңа SOP жасайды ('make new-sop' Deployment '').
Audit-sync: SOP нұсқасын жүйе релизімен және commit-ID-мен байланыстырады.

11) Қауіпсіздік және құпиялылық

RBAC репозиторийге: тек домен иелерінде өңдеуге қатынасу.
Құпиялар және PII: ашық құжаттарда сақтауға болмайды; тек қорғалған vault сілтемелері.
Аудит: барлық өзгерiстер мен жарияланымдар.
Жаңарту саясаты: әрбір 6 ай сайын SOP қайта қарау.
Backups: DR аймағындағы репозиторийдің және кэш порталының тұрақты суреттері.

12) Жетілу метрикасы

13) Қарсы үлгілер

Құжаттама Google Docs-те нұсқаларсыз және иелерінсіз сақталады.
Runbook шығарылымдардан кейін жаңартылмайды.
SOP ескірген командаларға/құралдарға сілтеме жасайды.
CI валидациясы жоқ: Қателері бар Markdown және сынған сілтемелер.
Бір нұсқауды әр жерде қайталау.
Иелері мен review процесінің болмауы.

14) Енгізу чек-парағы

• Домен иелерін және құжаттамаға жауапты адамдарды анықтау.
• Git-репозиторий 'ops-docs/' және SOP/runbook/playbook үлгілерін жасау.
• CI тексерулері мен линтерлерін баптау (Markdown/YAML).
• Автоматты жарияланымды порталға немесе Wiki қызметіне теңшеу.
• Графана/Incident Manager бағдарламасымен біріктіру.
• Ескертулер мен SLA тексерулері үшін Ops ботын қосу.
• «docs-as-code workflow» пәрменін оқыту.

15) 30/60/90 - енгізу жоспары

• Репозиторий құрылымын, үлгілерді, CI-линтерді және PR-жаңарту процесін жасау.
• Негізгі SOP және 5-10 сыни runbook бағдарламаларын жылжыту.
• auto-build бағдарламасын порталға баптау.

• Incident Manager және Grafana бағдарламаларымен біріктіру.
• Тексеру және есеп беру үшін Ops-ботты қосу.
• Постмортем үлгісін жаңарту және инцидент-дашбордпен байланыстыру.

• 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 негізінде жаттығу.
Постмортемалар: SOP және playbook сілтемелерін автоматты түрде кірістіру.
Басқару әдебі: өзгерістердің ашықтығы және авторлық.
AI көмекшілері: контекстік іздеу және TL; Репозиторийден DR.

18) FAQ

Q: Confluence бар болса, неге Git?
A: Git нұсқаларын береді, шолу, автоматтандыру және ойнату. Confluence ақырғы терезе болуы мүмкін, бірақ шындық көзі емес.

Q: Ескірген нұсқауларды қалай болдырмау керек?
A: SLA тексеруге (180 күн) + Ops-бот ескертулер + соңғы тексерудің автоматты белгісі.

Q: СІ құжаттамаға қосуға бола ма?
А: Иә. Синтаксисті, міндетті өрістерді және сынған сілтемелерді тексеру код сынағына ұқсас стандартты pipeline ретінде орындалады.