Playbook migrazioni
1) Classificazione delle migrazioni
Schemi database - Aggiungere/modificare colonne, indici, charding, cambiare il tipo di chiave.
Dati: backfill/cleanup di massa, normalizzazione, ritensh/archiviazione.
Servizi e API: cambio di endpoint, versioning, riscossione dei contratti.
Code/pneumatici: trasloco dei topic, modifica delle chiavi di partitura, formato degli eventi.
Infrastruttura: passaggio al nuovo cluster/K8s/cloud/regione, cambio di segreto/KMS.
Storage e analisi: cambio motore (OLTP/OLAP), formato/partizionamento dei dataset.
Protezione/compilazione: rotazione delle chiavi, crittografia in volo, geo-localizzazione dei dati.
2) Principi di migrazione di successo
1. Expand → Migrate → Contract. Prima espandiamo lo schema/comportamento (compatibile), poi spostiamo i dati/traffico, poi rimuoviamo il vecchio.
2. Shadow & Dual. Controllo shadow (shadow read/write) e doppia voce per la convalida.
3. Flag Fiech e pulsante rosso. Disattivazione rapida, attivazione passo passo (persentile/tenenti/regioni).
4. Idipotenza e ripetitività. Gli script e le attività possono essere riavviati senza effetti collaterali.
5. Osservabilità prima dei cambiamenti. Dashboard/alert in anticipo, marcatori di migrazione in unità/roulotte.
6. Recupero documentato. Runbook Ritocco è dettagliato quanto il piano in avanti.
7. Mini partenze e pause. Migriamo con piccole porzioni, controllando gli SLI e gli invarianti aziendali.
3) Inventario e analisi delle dipendenze
Scheda dei consumatori: servizi, jobs, report, partner esterni, BI/ETL, webhoop.
Contratti e schemi: API/eventi, compatibilità backward/forward.
Accessibili/segreti: chi legge/scrive dove sono i caschi/repliche.
Invarianti di dominio: unicità, equilibrio, idimpotenza, 24 ore al giorno.
Volumi/velocità: dimensioni dei dati, RPS, finestre di punta, RPO/RTO.
4) Modello di playbook canonico (scheletro YAML)
yaml playbook: "migrate-orders-to-v2"
owner: "orders-team"
stakeholders: ["platform", "data", "security", "support"]
change_type: ["schema", "data", "api"]
risk_level: "high"
preconditions:
- "Dashboards ready: latency/error/lag"
- "Runbook rollback validated on stage"
- "Backups verified (restore tested)"
plan:
phase_1_prepare:
steps:
- "Add new nullable columns (expand)"
- "Deploy code with dual-write (flag off)"
- "Enable CDC stream to target"
phase_2_shadow:
steps:
- "Shadow-read v2, compare with v1 (1%)"
- "Fix discrepancies; iterate"
phase_3_dual_write:
steps:
- "Enable dual-write (10%→50%→100%)"
- "Start backfill in batches (size=10k, sleep=200ms)"
phase_4_cutover:
steps:
- "Switch reads to v2 by tenants (canary)"
- "Monitor SLI 30m; expand scope"
phase_5_contract:
steps:
- "Drop old indices/columns after T+14d"
- "Disable old topic/api; update docs/SDK"
guardrails:
abort_if:
- "error_rate > 0. 5% for 5m"
- "p95 > baseline1. 5 for 10m"
- "data_mismatch > 0. 01%"
rollback:
steps:
- "Flip flag: reads back to v1"
- "Stop backfill; continue dual-write to v1"
- "Replay missed events (DLQ→v1)"
validation:
checks:
- "Row counts match within epsilon"
- "Business invariants hold (balances, limits)"
comms:
- channel: "on-call-bridge"
- status_updates: "T-24h, T-1h, start, cutover, finish"
window: "low-traffic Sun 02:00–05:00 UTC"5) Pattern migrazioni
5. 1 Diagrammi di database (RDBMS/NoSQL)
Aggiungete, non modificate. Nuove colonne/indici nullable → codice legge vecchio e nuovo.
Ristrutturazione online. Utilizzare gli indici online o i DDL paralleli.
Versioni della serializzazione. Versionare payload nelle colonne JSON/Proto/Avro.
Migrazione delle chiavi. Quando si cambia PK, la tabella temporale delle corrispondenze + trigger/CDC.
5. 2 Dati (backfill/cleanup)
CDC + backfill. Prima il flusso di modifiche (per rimanere indietro), poi il backfill batch.
Lotti e deadline. Piccoli battelli controllati da lame, checkpoint e riattivazione.
Update idepotenti. Upsert per chiavi/versioni naturali.
5. 3 Eventi e code
Versioning degli eventi, «event_type@vN», i conciatori ignorano i campi sconosciuti.
Un trasloco di topic. Doppia pubblicazione, i consumatori leggono da entrambi fino alla stabilizzazione; Poi il taglio del vecchio.
Partition key. Migrazione chiave - Attraverso la riedizione con mappe di conformità e idipotenza.
5. 4 Servizi e API
Blue/Green/Canary. Riscaldamento del pool, traffico parziale, rapido ritorno.
Flag Fiech. Per tenanti/regioni/percentuali, inclusione osservata.
Contratti. Contratti CDC e test di compatibilità - prima del cambio.
5. 5 Regioni/Claudia
Geo-doppia registrazione. I dati vengono registrati in due regioni; letture - vicinanze.
State transfer. Snapshot + replica linea rossa RPO, transbordo DNS/Anycast.
Giurisdizione. Consenso/localizzazione dei dati, elenchi «proibiti» per l'estrazione dei set.
6) Fasi di esecuzione (dettagli)
1. Preparazione
I dashboard, gli alert, i limiti, le bandiere fich, i backup con il test di recupero, la prova di staffa.
2. Shadow (controllo shadow)
Mirroring delle query/scrittura nel nuovo sistema senza influire sugli utenti. Confrontiamo le risposte/stati.
3. Dual-write / Dual-read
Scriviamo in entrambe le direzioni. Le letture si traducono gradualmente in un nuovo sistema. I fogli di non corrispondenza vengono analizzati.
4. Backfill
Stiamo controllando i dati storici dei partiti. Controlliamo la lega CDC, controlliamo il carico di lavoro per lo store/cache.
5. Cutover (commutazione)
Canarim per segmenti (tenenti/regioni/interessi). Ripristiniamo rapidamente.
6. Contract (pulizia)
Tagliamo i vecchi percorsi, rimuoviamo i campi/indici/topici obsoleti dopo il «periodo di sicurezza».
7. Verifica e retrò
Report, metriche, lezioni, aggiornamento playbook/assegno fogli.
7) Osservabilità e SLO durante la migrazione
SLI tecnico: p50/p95/p99, errore rate, retry/timeout, utilization, lag CDC, profondità delle code.
Business SLI: successo delle transazioni/conversioni, invarianti (bilanci, limiti, duplicati).
Etichette speciali: 'migration _ id', 'phase', 'tenant', 'flag _ state'.
Alert-guardie: soglie di coda e errori, auto-stop (abort) SLO.
Pannelli comparativi: v1 vs v2, «delta» per metriche chiave.
8) Ripristino e script di emergenza
Ritorno logico: flag/instradamento del traffico indietro, congelamento backfill.
Dati: compensi, repliche di eventi, DLQ e sistema di origine.
Segreti/chiavi - Restituisci alla chiave/certificato precedente (dual-key).
DNS/Traffico: «retro» Anycast/ALB, TTL breve alla finestra di migrazione.
Comunicazioni: canale e formato di stato pre-concordati.
9) Sicurezza, privacy, compliance
Ridurre al minimo i dati. Spostiamo solo i campi necessari; profili di anonimato su copie.
Crittografia. Crittografia a filo e a riposo, rotazione KMS; Registro delle operazioni con le chiavi.
Disponibile in base al tempo. Ruoli temporanei per i giubbotti migratori, selezione dei diritti dopo il completamento.
Tracce. Occultamento del PD in unità/trailer, restrizioni all'esportazione.
10) Gestione dei cambiamenti e comunicazione
RACI: chi dice chi esegue, chi viene informato.
Periodi freeze - Impedisce i rilasci non rilevanti alla finestra di migrazione.
States: T-24h, T-1h, partenza, canaring, cutover, traguardo, post-mare.
Partner esterni: finestre di interoperabilità, e-mail, sabbia di prova.
11) Modelli di runbook
11. 1 Backfill (pseudocode)
for batch in paginate(ids, size=10_000):
try:
rows = read_v1(batch)
upsert_v2 (rows) # idempotently mark_checkpoint (batch. end)
sleep(jitter_ms(100..300))
except Throttle:
sleep (5s) # backpressure respect except Fatal as e:
alert("backfill-failed", e, context=batch)
abort_if_needed()11. 2 Proverka一致nosti (snapshot/campionamento)
sample = random_ids(n=10_000, stratify=tenant,timestamp)
v1 = fetch_v1(sample); v2 = fetch_v2(sample)
assert schema_compatible(v2)
assert key_invariants_hold (v1, v2) # sum, statuses, versions mismatch_rate = diff (v1, v2). rate()
abort_if(mismatch_rate > 0. 0001)11. 3 Cambio di lettura
flag. enable("read_from_v2", segment="tenants: cohort_A")
monitor(30m)
if SLO_ok(): expand_segment()
else: rollback_segment()12) Anti-pattern
Big Bang invece di expand-migrate-contract.
Un Backfill senza CDC è un inseguimento e una deriva eterni.
La mancanza di idampotenza è stata ripresa/dati sporchi.
Passi manuali senza script, errori umani.
La migrazione senza dashboard/guardie è un volo cieco.
La → non confermata non funziona quando serve.
Ignorare i consumatori (BI/partner) → report/integrazioni «infranti».
13) Assegno-foglia dell'architetto
1. Obiettivo, limite, tipo di migrazione e invarianti del risultato?
2. La mappa dei consumatori e dei contratti è stata compilata, i test di compatibilità sono verdi?
3. Sono stati preparati dashboard, alert, etichette «migration _ id», SLO/guardrails?
4. Shadow e/o dual-write implementati, backfill idipotente?
5. C'è un rollback runbook praticato, controlli di recupero dal backup?
6. Finestra/coordinamento/comunicazione concordata, freeze attivata?
7. Il piano passo-passo con canaring e criteri di espansione/arresto è pronto?
8. Sicurezza/compilazione: chiavi, accessibilità, assistenza sanitaria PII?
9. La documentazione/SDK/spec viene aggiornata nello stesso ciclo di lancio?
10. Il post-mare e l'aggiornamento del playbook sono pianificati?
Conclusione
Playbook delle migrazioni è una pratica architettonica di gestione dei rischi: piccoli passaggi inversi, metriche trasparenti, reimpostazione pronta e disciplina «expand-migrate-contract». Seguendo i modelli descritti, si migrano schemi, dati, servizi e regioni senza interruzioni o sorprese, mantenendo gli invarianti aziendali e la fiducia degli utenti.