Migrating Legacy to Platform

The Brownfield Challenge

Most organizations don't start greenfield. They have: 100s of services on Jenkins/GitLab CI, custom deploy scripts, inconsistent observability, tribal knowledge, no catalog. Platform team must migrate without stopping feature delivery. Big bang fails. Incremental wins.

Strangler Fig Pattern

Gradually replace legacy system by creating new platform capabilities alongside, routing traffic incrementally. Legacy system 'strangled' as new system takes over. Named after strangler fig vine that grows around host tree.

Assessment & Prioritization

Before migrating, assess: inventory all services, their CI/CD, deployment, observability, team maturity. Prioritize by: pain level, team willingness, business impact, complexity.

# service-inventory.csv
service_name,team,ci_cd,deploy_method,observability,team_maturity,pain_score,willingness,business_critical,complexity
payment-api,payments,jenkins,helm,datadog,high,9,high,high,medium
user-service,identity,gitlab,ansible,prometheus,medium,7,medium,high,low
notification-svc,notifications,github-actions,custom,none,low,8,high,low,low
legacy-billing,billing,jenkins,manual,datadog,low,10,low,high,high
ml-training,ml,gitlab,kubeflow,mlflow,high,5,high,medium,high

# Priority = Pain * Willingness / Complexity
# High priority: notification-svc (8*high/low), payment-api (9*high/medium)
# Low priority: legacy-billing (10*low/high), ml-training (5*high/high)

migration_waves:
  wave_1_quick_wins:  # Weeks 1-4
    - notification-svc
    - user-service
    - config-service
  
  wave_2_core:  # Months 2-3
    - payment-api
    - order-service
    - inventory-service
  
  wave_3_complex:  # Months 4-6
    - legacy-billing
    - ml-training
    - reporting-service
  
  wave_4_legacy:  # Months 6+
    - mainframe-adapter
    - batch-processing

Migration Paths

# Jenkinsfile (before)
pipeline {
  agent any
  stages {
    stage('Build') { steps { sh 'docker build -t myapp .' } }
    stage('Test') { steps { sh 'npm test' } }
    stage('Deploy') { 
      steps { 
        sh 'kubectl set image deployment/myapp myapp=myapp:${BUILD_NUMBER}'
      }
    }
  }
}

# Jenkinsfile (after - wrap deploy)
pipeline {
  agent any
  stages {
    stage('Build') { steps { sh 'docker build -t myapp .' } }
    stage('Test') { steps { sh 'npm test' } }
    stage('Deploy via Platform') { 
      steps { 
        sh '''
          platform service deploy myapp             --image myapp:${BUILD_NUMBER}             --namespace myteam-myapp             --wait
        '''
      }
    }
  }
}

Quick Wins

• Catalog Registration: Register all existing services in portal (no code change, immediate visibility)
• Observability Defaults: Deploy OpenTelemetry collector + ServiceMonitor to all namespaces (no code change, instant metrics)
• Secrets Migration: Move secrets from Jenkins/ConfigMaps to Vault + ESO (security win, no deploy change)
• Policy Enforcement: Enable Kyverno audit mode (no enforcement, just visibility on violations)
• Catalog Enrichment: Add ownership, runbooks, dashboards to catalog entries (docs win)
• CLI Access: Give teams platform service get/logs/status for existing services (UX win)
• Cost Visibility: Enable Kubecost/OpenCost per namespace (finops win)

Building Trust

Trust is the currency of platform adoption. Without trust, teams won't migrate. Build trust through: transparency, reliability, responsiveness, quick wins, no mandates.

Completion & Decommission

Migration complete when: all services on golden path, legacy CI/CD decommissioned, legacy infra torn down, teams self-sufficient. Celebrate!

• Decommission Checklist: No services using legacy CI/CD, no legacy infra running, no legacy docs referenced
• Knowledge Transfer: Runbooks updated, tribal knowledge documented, new hire onboarding uses platform only
• Celebration: Platform launch party, swag, blog post, metrics dashboard showing before/after
• Retrospective: What worked, what didn't, what would we do differently? Document for next org.
• Platform 2.0: Start planning next evolution based on migration learnings