Skip to main content

Operator Management Service — Migration Plan

Status: populated Owner: Platform Engineering + SRE Last updated: 2026-04-18

1. Context​

This is a greenfield service — there is no predecessor to retire. However, a migration is required to seed initial operator configuration from the legacy spreadsheet-based operator inventory currently managed by the ops team.

2. Data Migration​

Source​

  • Legacy: operator config stored in a shared Google Sheet maintained by the carrier relations team.
  • ~40 operators with SMPP credentials stored in LastPass (ops team).

Target​

  • PostgreSQL ops.operators, ops.routing_rules, ops.destination_prefixes, ops.tps_limits.
  • Vault secret/ops/operators/{id}/credentials for each operator.

Migration Script​

scripts/migrate-legacy-operators.ts:

  1. Parse Google Sheet export (CSV).
  2. Validate each row with Zod (same schema as CreateOperatorCommand).
  3. For each valid row: call CreateOperatorUseCase (re-uses production logic including Vault write).
  4. Emit migration report: created, skipped (already exist), failed.

Rollback​

Delete all rows where created_by = 'migration-script' if migration must be reverted. Vault secrets at corresponding paths deleted via Vault CLI.

3. Phased Rollout​

PhaseDurationDescription
0. Schema prep1 dayApply PG migrations to staging. Create Vault path policy.
1. Seed staging1 dayRun migration script against staging with production-equivalent data. Validate routing-engine picks up config via NATS.
2. Ops team acceptance2 daysOps team verifies operator config via admin UI.
3. Production seed1 dayRun migration in production with approval. Validate NATS events received by routing-engine.
4. Decommission spreadsheet1 weekAfter ops team confirms admin UI is SOT, archive Google Sheet.

4. Vault Bootstrap​

# One-time Vault policy + KV setup (run by infra team)
vault secrets enable -path=secret kv-v2
vault policy write ops-service-policy ops-vault-policy.hcl
vault auth enable kubernetes
vault write auth/kubernetes/role/operator-management-service \
  bound_service_account_names=operator-management-service \
  bound_service_account_namespaces=ghasi-prod \
  policies=ops-service-policy ttl=1h

5. Risks​

  • LastPass → Vault migration requires one-time plaintext password handling; perform in air-gapped environment, rotate passwords post-migration.
  • Google Sheet may have dirty data; migration validator rejects invalid rows and reports for manual review.