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 # 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

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

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

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) 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.