Operazioni e Gestione → Documentazione delle operazioni come codice

Documentazione delle operazioni come codice

1) L'essenza dell'approccio

La documentazione come codice è una pratica in cui le conoscenze operative, le istruzioni e i processi vengono memorizzati, modificati e convalidati nello stesso modo del codice, tramite Git, pull-richiesti, review e convalida CI.
Il tracciato operativo costituisce la base per l'affidabilità, la trasparenza e la compatibilità dei comandi.

• Creare un sistema di conoscenza vivente, riproduttivo e versionabile in cui ogni istruzione è un artefatto dell'infrastruttura e non un PDF obsoleto.

2) Perché è necessario

Trasparenza: si vede chi, quando e perché ha cambiato la procedura.
Coerenza: tutti i comandi sono aggiornati.
Integrazione con CI/CD: verifica automatica della validità delle istruzioni.
Replica: infrastruttura e documentazione sincronizzati.
Sicurezza: controllo degli accessi e controllo tramite Git.
Accelerazione del sistema: i nuovi operatori vedono gli script precisi associati al codice.

3) Oggetti principali

4) Architettura del repository

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

Suggerimento: ogni cartella è un repository Git o Sabmodul per consentire a comandi diversi di gestire i contenuti in modo indipendente.

5) Formato e standard

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 e processi di modifica

Pull Sollest = RFC modifiche alla documentazione.
Review: il proprietario del dominio e Head of Ops devono approvare.
Convalida CI: controllo della struttura, dei campi obbligatori, linter Markdown/YAML.
Pubblicazione automatica - Dopo merge - generazione HTML/wiki/dashboard.
Change log: cronologia automatica dei cambiamenti con date e autori.
Promemoria Alert: revisione del documento ogni N giorni (SLA).

7) Integrazione CI/CD

Controlli Lint: sintassi markdown, valenza YAML, campi owner/variante.
Link-check - Verifica URL e collegamenti interni.
Docs-build: conversione in HTML/Confluence/portale.
Analisi differenziata - Cosa è cambiato dalla precedente presentazione della documentazione.
Auto-sync - Aggiorna i collegamenti nei dashboard Grafana, Ops UI, Slack.
Review-bot - Suggerimenti sulle sezioni obsolete o sui proprietari mancanti.

8) Integrazione con gli strumenti operativi

Grafana/Kibana - Annotazioni e collegamenti ai rispettivi runbook direttamente dal pannello.
Inserisci Manager - Pulsante «Open Runbook» durante la creazione del ticket.
Portale on-call - Rilascia SOP aggiornati e playbook per categoria di incidenti.
Assistenti AI: ricerca nel repository, generazione TL; DR. e consigli di azione.
Dashboard BCP - Caricamento automatico delle istruzioni DR al momento dell'attivazione dello script.

9) Gestione del ciclo di vita dei documenti

10) Automazione e sincronizzazione

Docs-bot - Verifica i documenti obsoleti.
Versione badge: '! [last review: 2025-05]' proprio nel cappello.
Runbook-finder - Apre l'alert per il documento di tag desiderato.
Templates-generator - Crea nuovi SOP per modello ('make new-sop «Deployment»).
Audit-sync collega la versione SOP al lancio del sistema e al commit-ID.

11) Sicurezza e privacy

RBAC nel repository: accesso alla modifica solo per i proprietari di domini.
Segreti e PII: non possono essere memorizzati in documenti aperti; solo riferimenti a vault protetti.
Controllo: riepilogo di tutte le modifiche, gelosie e pubblicazioni.
Criteri di aggiornamento - Revisione di SOP ogni 6 mesi.
Backups - Copie istantanee regolari del repository e del portale cache nella zona DR.

12) Metriche di maturità

13) Anti-pattern

La documentazione è memorizzata in Google Docs senza versioni o proprietari.
Runbook non viene aggiornato dopo le release.
SOP fa riferimento a comandi o strumenti obsoleti.
Nessuna convalida CI: Markdown con errori e riferimenti a bit.
Duplicare le stesse istruzioni in luoghi diversi.
Nessun proprietario e nessun processo di review.

14) Assegno foglio di implementazione

• Identificare i proprietari dei domini e i responsabili della documentazione.
• Crea un repository Git «ops-docs/» e modelli SOP/runbook/playbook.
• Configura controlli CI e lintern (Markdown/YAML).
• Configura la pubblicazione automatica in un portale o Wiki.
• Integrare con Grafana/Incent Manager.
• Aggiungi Ops-bot per avvisi e revisioni SLA.
• Esercitare i comandi con «docs-as-code workflow».

15) 30/60/90 - Piano di implementazione

• Creare la struttura del repository, i modelli, il linter CI e il processo di review PR.
• Spostare le SOP chiave e i runbook critici 5-10.
• Configura auto-build nel portale.

• Implementare le integrazioni con Incorporent Manager e Grafana.
• Connetti Ops-bot per le revisioni e i report.
• Aggiorna il modello postmortem e associa a un incidente dashboard.

• Copertura totale SOP/runbook (≥90%).
• Inserisci KPI: Coverage, Review SLA, Usage.
• Fare retrò in base alla comodità e alla qualità del processo «docs-as-code».

16) Modello SOP di esempio (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) Integrazione con altri processi

Analisi operativa: report su Coverage e revisione SLA.
Formazione degli operatori: allenamento basato su runbook reali.
Postmortem: inserisci automaticamente i collegamenti a SOP e playbook.
L'etica di gestione è la trasparenza dei cambiamenti e l'autore.
Assistenti AI: ricerca contestuale e TL; DR dal repository.

18) FAQ

Perché Git se c'è la Confluence?
A: Git fornisce versioni, review, automazione e riproduzione. La confluenza può essere la vetrina finale, ma non la fonte della verità.

Q: Come evitare istruzioni obsolete?
A: SLA per revisione (180 giorni) + avviso Ops-bot + automatico badge ultima verifica.

Q: È possibile collegare CHI alla documentazione?
A: Sì. La convalida della sintassi, dei campi obbligatori e dei riferimenti a bit viene eseguita come pipeline standard, allo stesso modo dei test di codice.