Operațiuni și → Documentația de gestionare a operațiunilor ca cod

Documentația tranzacției ca cod

1) Esența abordării

Documentația ca cod este o practică în care cunoștințele operaționale, instrucțiunile și procesele sunt stocate, editate și validate în același mod ca și codul: prin Git, pull-requests, review și CI validation.
Într-o buclă operațională, aceasta constituie baza pentru fiabilitatea, transparența și compatibilitatea comenzilor.

• Creați un sistem de cunoștințe viu, reproductibil și versionat, în care fiecare instrucțiune este un artefact al infrastructurii, și nu un PDF învechit.

2) De ce ai nevoie de ea

Transparență: puteți vedea cine, când și de ce a schimbat procedura.
Consecvență: toate echipele lucrează la versiunile actuale.
Integrarea cu CI/CD: validarea automată a instrucțiunilor.
Replicabilitate - Infrastructura și documentația sunt sincronizate.
Securitate: control acces și audit prin Git.
Accelerarea îmbarcării: Noii operatori văd scenarii exacte legate de cod.

3) Principalele facilități

4) Arhitectura depozitului

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

Sfat: fiecare dosar are propriul depozit Git sau submodul, astfel încât diferite echipe să poată gestiona conținutul în mod independent.

5) Formatul și standardele

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 și procesele de schimbare

Pull Request = RFC documentation changes.
Recenzie: Proprietarul domeniului și șeful Ops trebuie să aprobe.
Validarea CI: verificarea structurii, câmpuri obligatorii, linter Markdown/YAML.
Publicare automată: după îmbinare - generare HTML/wiki/tablouri de bord.
Schimbați jurnalul: auto-istoricul modificărilor cu datele și autorii.
Notificări de alertă: revizuirea documentelor la fiecare N zile (de SLA).

7) integrare CI/CD

Lint verifică: sintaxa Markdown, valabilitatea YAML, câmpurile proprietar/versiune.
Link-check: verificarea URL-urilor și a legăturilor interne.
Docs-build: conversie la HTML/Confluence/portal.
Analiza Diff: ce s-a schimbat de la ultima lansare a documentației.
Auto-sync: actualizarea link-uri în tablouri de bord Grafana, Ops UI, Slack.
Roboți de revizuire: sfaturi pentru secțiuni învechite sau proprietari lipsă.

8) Integrarea cu instrumente operaționale

Grafana/Kibana: adnotări și link-uri către runbook-ul corespunzător direct din panou.
Manager de incidente: „Deschideți Runbook” buton atunci când creați un bilet.
Portal de gardă: emiterea de POS-uri și playbook-uri actuale pe categorii de incidente.
Asistenți AI: căutare depozit, generare TL; DR și sfaturi de acțiune.
Panouri BCP - Încarcă automat instrucțiunile DR atunci când este activat un script.

9) Gestionarea ciclului de viață al documentelor

10) Automatizare și sincronizare

Docs bot: verifică ce documente sunt depășite.
Versiunea insigna: '! [ultima recenzie: 2025-05] 'chiar în capac.
Runbook-finder: prin alertă se deschide documentul dorit după tag.
Șabloane-generator: creează noi SOP-uri prin șablon („make new-sop” Implementare „”).
Audit-sincronizare: Asociază versiunea SOP cu eliberarea sistemului și ID-ul de comitere.

11) Securitate și confidențialitate

RBAC per depozit: numai proprietarii de domenii pot edita.
Secrete și PII: Nu pot fi păstrate în documente deschise; numai link-uri la seifuri protejate.
Audit: jurnalul tuturor modificărilor, recenziilor și publicațiilor.
Politica de actualizare: Revizuirea POS la fiecare 6 luni.
Backup-uri: instantanee depozit regulate și cache-uri portal în zona DR.

12) Valorile maturității

13) Anti-modele

Documentația este stocată în Google Docs fără versiuni și proprietari.
Runbook nu este actualizat după lansări.
SOP se referă la comenzi/instrumente moștenite.
Nu există validare CI: Markdown cu erori și link-uri rupte.
Duplicați aceleași instrucțiuni în locații diferite.
Lipsa proprietarilor și procesul de revizuire.

14) Lista de verificare a implementării

• Identificați proprietarii de domenii și proprietarii de documente.
• Creați un depozit Git 'ops-docs/' și șabloane SOP/runbook/playbook.
• Configurați verificările CI și linterele (Markdown/YAML).
• Configurați Auto-Publish la Portal sau Wiki.
• Integrează-te cu Grafana/Incident Manager.
• Adăugați un bot Ops pentru memento-uri și revizii SLA.
• Instrui docs-as-cod comenzi de flux de lucru.

15) 30/60/90 - plan de implementare

• Creați structura depozitului, șabloane, linter CI și procesul de revizuire PR.
• Migrați POS-uri cheie și 5-10 cărți critice.
• Configurați auto-construi în portal.

• Implementați integrările cu Incident Manager și Grafana.
• Conectați bot Ops pentru audituri și raportare.
• Actualizați șablonul postmortem și link-ul la incidentul tabloului de bord.

• Acoperirea completă a SOP/runbook (≥90%).
• Introduceți KPI: acoperire, revizuire SLA, utilizare.
• Retro asupra comodității și calității procesului „docs-as-code”.

16) Exemplu de șablon 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) Integrarea cu alte procese

Analiza operațională: rapoarte de acoperire și audit SLA.
Training operator: training bazat pe cărți reale.
Postmortems: inserarea automată a link-urilor către SOP și playbook.
Etica guvernanței: transparența schimbării și a autorității.
Asistenți AI: căutare contextuală și TL; DR din depozit.

18) ÎNTREBĂRI FRECVENTE

Î: De ce Git dacă există confluență?
R: Git oferă versiuni, revizuire, automatizare și reproductibilitate. Confluența poate fi prezentarea finală, dar nu sursa adevărului.

Î: Cum să evitați instrucțiunile depășite?
R: SLA pentru revizie (180 zile) + boți de memento Ops + insigna automată a ultimei verificări.

Î: Poate fi conectat CI la documentație?
R: Da. Sintaxa, câmpurile necesare și referințele rupte sunt verificate ca conducte standard, similare cu testele de cod.