Операциялар жана башкаруу → Код катары иш кагаздары

Код катары операцияларды документтештирүү

1) Мамиленин маңызы

Код катары документтештирүү (Documentation as Code) - операциялык билим, көрсөтмөлөр жана процесстер Git, pull-requests, review жана CI-валидация аркылуу сакталган, редакцияланган жана текшерилген практика.
Операциялык контурда бул командалардын ишенимдүүлүгүнүн, ачыктыгынын жана шайкештигинин негизин түзөт.

• Ар бир көрсөтмө эскирген PDF эмес, инфраструктуралык артефакт болгон жандуу, кайталануучу жана версиялануучу билим системасын түзүү.

2) Эмне үчүн керек

Ачык-айкындуулук: процедураны ким, качан жана эмне үчүн өзгөрткөнүн көрүүгө болот.
Ырааттуулук: бардык командалар актуалдуу версиялар боюнча иштешет.
CI/CD менен интеграция: көрсөтмөлөрдүн аныктыгын автоматтык түрдө текшерүү.
Репликация: инфраструктура жана документтер синхрондоштурулган.
Коопсуздук: Git аркылуу кирүү көзөмөлү жана аудит.
Онбордингдин тездеши: жаңы операторлор кодго байланыштуу так сценарийлерди көрүшөт.

3) Негизги объектилер

4) Репозиторийдин архитектурасы

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

Кеңеш: ар бир папка өзүнүн 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

Цель
Контекст
Последовательность шагов
Проверка результата
Риски и откат
Контакты и каналы

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 документтерди өзгөртүү.
Review: Domain ээси жана Head of Ops бекитүү керек.
CI-валидация: структураны, милдеттүү талааларды, Markdown/YAML линтерин текшерүү.
Автоматтык жарыялоо: кийин merge - HTML/wiki/dashboard түзүү.
Change log: даталар жана жазуучулар менен auto-тарыхы өзгөрүүлөр.
Эскертүү-эскертүүлөр: документти ар бир N күн сайын текшерүү (SLA боюнча).

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

Lint-текшерүү: Markdown-синтаксис, YAML-validity, 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-bot: кайсы документтер эскиргенин текшерет.
Version badge: '! [last review: 2025-05]' түздөн-түз баш кийимде.
Runbook-finder: Алерт тегине керектүү документти ачат.
Templates-generator: шаблон боюнча жаңы SOP түзөт ('make new-sop "Deployment"').
Audit-sync: SOP версиясын системанын релизи жана commit-ID менен байланыштырат.

11) Коопсуздук жана купуялык

RBAC репозиторийге: домен ээлеринин гана редакторлоо мүмкүнчүлүгү.
Сырлар жана PII: ачык документтерде сактоого болбойт; гана корголгон vault шилтемелер.
Аудит: бардык өзгөртүүлөр, ревю жана басылмалардын журналы.
Жаңылоо саясаты: ар бир 6 ай сайын SOP кайра карап чыгуу.
Backups: DR-зонасында сактоо жана кэш порталынын үзгүлтүксүз сүрөттөрү.

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

13) Анти-үлгүлөрү

Документтер Google Docs нускалары жана ээлери жок сакталат.
Runbook чыгарылгандан кийин жаңыланбайт.
SOP эскирген команда/инструменттерди билдирет.
Жок CI-validation: Markdown каталар жана үзүндүлөрү менен.
Бир эле нускамаларды ар кайсы жерде кайталоо.
ээлеринин жоктугу жана review жараяны.

14) Киргизүү чек-тизмеси

• домендердин ээлерин жана документтештирүү үчүн жооптуу адамдарды аныктоо.
• Git-репозиторий 'ops-docs/' жана SOP/runbook/playbook үлгүлөрүн түзүү.
• CI-текшерүү жана Линтерс орнотуу (Markdown/YAML).
• Portal же Wiki үчүн auto-жарыялоо орнотуу.
• Grafana/Incident Manager менен бириктирүү.
• Эскертүү жана SLA текшерүү үчүн Ops-ботту кошуу.
• "docs-as-code workflow" боюнча командаларды окутуу.

15) 30/60/90 - ишке ашыруу планы

• Репозиторийдин структурасын, шаблондорду, CI линтерин жана PR ревю процессин түзүү.
• Негизги SOP жана 5-10 критикалык runbook которуу.
• порталында auto-build орнотуу.

• Incident Manager жана Grafana менен интеграцияны киргизүү.
• Текшерүү жана отчеттуулук үчүн Ops-ботту туташтыруу.
• Postmortem-шаблон жана окуя-dashboard менен байланыштыруу.

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

Цель
Обеспечить безопасное и управляемое развертывание сервисов через 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) Башка процесстер менен интеграция

Операциялык аналитика: Coverage жана SLA аудит отчеттору.
Операторлорду окутуу: реалдуу runbook негизинде окутуу.
Postmortems: автоматтык SOP жана playbook шилтемелерди киргизүү.
Башкаруу этикасы: өзгөрүүлөрдүн ачык-айкындуулугу жана автордук.
AI жардамчылары: контексттик издөө жана TL; репозиторийден DR.

18) FAQ

Q: Confluence бар болсо, эмне үчүн барып?
A: Git версияларын, карап чыгууну, автоматташтырууну жана ойнотууну берет. Confluence акыркы терезе болушу мүмкүн, бирок чындыктын булагы эмес.

Q: Кантип эскирген көрсөтмөлөрдү качуу керек?
A: текшерүү үчүн SLA (180 күн) + Ops-бот эскертүүлөр + акыркы текшерүү автоматтык белги.

Q: Документацияга CI туташтыруу мүмкүнбү?
A: Ооба. Синтаксисти, милдеттүү талааларды жана сынган шилтемелерди текшерүү коддун сыноолоруна окшош стандарттык түтүк катары жүргүзүлөт.