Playbooks des migrations

1) Classification des migrations

Schémas OBD : ajout/modification de colonnes, index, chardonnage, changement de type de clé.
Données : backfill/cleanup en masse, normalisation, rétention/archivage.
Services et API : changement d'endpoints, versioning, refactoring de contrats.
Files d'attente/bus : déplacement des tops, modification des clés de lot, format des événements.
Infrastructure : passage à un nouveau cluster/K8s/cloud/région, changement de secrets/KMS.
Stockage et analyse : changement de moteur (OLTP/OLAP), format/lot de datacets.
Sécurité/conformité : rotation des clés, cryptage à la volée, géolocalisation des données.

2) Les principes d'une migration réussie

1. Expand → Migrate → Contract. D'abord, nous étendons le schéma/comportement (compatible), puis nous transférons les données/trafic, puis nous supprimons l'ancien.
2. Shadow & Dual. Contrôle instantané (shadow read/write) et double enregistrement pour la validation.
3. Drapeaux de ficha et « bouton rouge ». Désactivation rapide, activation étape par étape (percentile/tenants/régions).
4. Idempotence et répétabilité. Les scripts et les tâches peuvent être redémarrés sans effets secondaires.
5. L'observation des changements avant. Dashboards/alerts à l'avance, marqueurs de migration dans les logs/trajets.
6. Le retour est documenté. Le runbook de retour est aussi détaillé que le plan à venir.
7. Mini-parties et pauses. Nous migrons en petites portions en vérifiant le SLI et les invariants d'affaires.

3) Inventaire et analyse de la dépendance

Carte des consommateurs : services, jobs, rapports, partenaires externes, BI/ETL, webhooks.
Contrats et schémas : versions API/événements, compatibilité backward/forward.
Accès/secrets : qui lit/écrit, où sont les casiers/répliques.
Invariants du domaine : unicité, équilibre, idempotence, 24 heures sur 24.
Volumes/vitesses : taille des données, RPS, fenêtres de pointe, RPO/RTO.

4) Modèle de Pleybuck canonique (squelette 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) Modèles de migration

5. 1 Schémas OBD (RDBMS/NoSQL)

Ajoutez - ne modifiez pas. Les nouvelles colonnes/index nullables → le code lit l'ancien et le nouveau.
Reconstruction en ligne. Utilisez les index en ligne/DDL parallèles.
Versions de la sérialisation. Versez votre payload dans les colonnes JSON/Proto/Avro.
Migration de clés. Lorsque vous changez de PK, la table temporelle des correspondances + déclencheur/CDC.

5. 2 Données (backfill/cleanup)

CDC + backfill. D'abord le flux de modifications (pour suivre), puis le paquet backfill.
Les partis et les deblines. Petits batchs avec contrôle des lagunes, checkpoint et redémarrage.
Apdates idempotent. Upsert par clés/versions naturelles.

5. 3 Événements et files d'attente

Versioner les événements. 'event _ type @ vN', les consomers ignorent les champs inconnus.
Déménagement des tops. Double publication, les consommateurs lisent des deux avant de se stabiliser ; puis « couper » l'ancien.
Partition key. Migration de clé - via une réimpression avec carte de correspondance et idempotence.

5. 4 Services et API

Blue/Green/Canary. Chauffage de la piscine, trafic partiel, retour rapide.
Les drapeaux de ficha. Par tenants/régions/pourcentage, inclusion observée.
Les contrats. Contrats CDC et tests d'interopérabilité - avant le changement.

5. 5 Régions/Clauds

Un enregistrement géo-double. Les données sont enregistrées dans deux régions ; lecture - par proximité.
State transfer. Snapshot + réplication ; « ligne rouge » RPO, transbordement DNS/Anycast.
Les juridictions. Consentement/localisation des données, listes « interdites » pour le retrait des jeux.

6) Phases d'exécution (en détail)

1. Préparation

Dashboards, alertes, limites, drapeaux de ficha, backups avec test de récupération, course au steidge.

2. Shadow (contrôle de l'ombre)

Miroir des requêtes/entrées dans le nouveau système sans affecter les utilisateurs. Nous comparons les réponses/états.

3. Dual-write / Dual-read

Nous écrivons dans les deux sens. Lectures - nous le transférons progressivement au nouveau système. Les logs de non-conformité sont analysés.

4. Backfill

Nous rattrapons les données historiques par lots. Nous surveillons la bande CDC, surveillons la charge de storage/cache.

5. Cutover (commutation)

Canarim par segment (tenants/régions/pourcentage). Maintenez le retour rapide.

6. Contrat (nettoyage)

Nous coupons les anciens chemins, nous supprimons les champs/index/tops obsolètes après la « période de sécurité ».

7. Vérification et rétro

Rapport, métriques, leçons, mise à jour des feuilles de pleybuck/chèques.

7) Observabilité et SLO pendant la migration

SLI technique : p50/p95/p99, error rate, retry/timeout, utilisation, lag CDC, profondeur des files d'attente.
SLI d'entreprise : succès des transactions/conversions, invariants (bilans, limites, doublons).
Étiquettes spéciales : 'migration _ id', 'phase', 'tenant', 'flag _ state'.
Alert-gardiens : seuils sur les queues et les erreurs, auto-stop (abort) par SLO.
Panneaux comparatifs : v1 vs v2, « delta » par métriques clés.

8) Scénarios de retour et d'urgence

Retour logique : drapeaux/routage du trafic vers l'arrière, gel backfill.
Données : « compensation » (Saga), relais d'événements, DLQ → système source.
Secrets/clés : retour à la clé/certificat précédente (double clé).
DNS/trafic : « retour drift » Anycast/ALB, TTL court dans la fenêtre de migration.
Communications : canal convenu à l'avance et format des statuts.

9) Sécurité, vie privée, conformité

Minimisation des données. Nous ne transférons que les champs nécessaires ; profils d'anonymisation sur copie.
Cryptographie. Cryptage « sur fil » et « au repos », rotation KMS ; Journal des opérations avec les clés.
Accès dans le temps. Rôles temporaires pour les jobs migratoires, sélection des droits après achèvement.
Des traces. Masquage des PD dans les logs/remorques, restrictions d'exportation.

10) Gestion du changement et communications

RACI : qui prétend qui exécute, qui est informé.
Périodes Freeze : interdire les sorties non pertinentes dans la fenêtre de migration.
Statuts : T-24h, T-1h, départ, canaring, cutover, arrivée, post-mer.
Partenaires externes : fenêtres de compatibilité, lettres de contrat, bac à sable de test.

11) Modèles de runbook's

11. 1 Backfill (pseudo-code)

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/échantillonnage)

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 Changement de lecture

flag. enable("read_from_v2", segment="tenants: cohort_A")
monitor(30m)
if SLO_ok(): expand_segment()
else: rollback_segment()

12) Anti-modèles

« Big Bang » au lieu d'expand-migrate-contract.
Backfill sans CDC → un rattrapage et une dérive éternels.
Manque d'idempotence → doublures/données sales.
Étapes manuelles sans scripts → erreurs humaines.
Migration sans dashboards/gardes → « vol aveugle ».
Un retour en arrière → non confirmé ne fonctionne pas quand vous en avez besoin.
Ignorer les consommateurs (BI/partenaires) → rapports/intégrations « cassés ».

13) Chèque de l'architecte

1. Définition de l'objectif, des limites, du type de migration et des invariants du résultat ?
2. La carte des consommateurs et des contrats est établie, les tests d'interopérabilité sont verts ?
3. Les dashboards, alertes, étiquettes "migration _ id', SLO/guardrails sont-ils prêts ?
4. Réalisé par shadow et/ou dual-write, backfill idempotenten ?
5. Y a-t-il un rollback runbook pratiqué, des tests de récupération à partir d'un backup ?
6. Fenêtre/coordination/communications cohérentes, freeze inclus ?
7. Plan étape par étape avec canaring et critères d'extension/stop prêt ?
8. Sécurité/conformité : clés, accès, PII-assainissement ?
9. Documentation/SDK/Specks mis à jour dans le même cycle de sortie ?
10. L'après-mer et le renouvellement du playbook une fois terminé sont prévus ?

Conclusion

Les pleybooks de migration sont une pratique architecturale de gestion des risques : petites étapes réversibles, métriques transparentes, retour prêt et discipline « expand-migrate-contract ». En suivant les modèles décrits, vous migrez les schémas, les données, les services et les régions sans interruption ni surprise, tout en préservant les invariants des entreprises et la confiance des utilisateurs.