Sankofa/docs/phoenix/MIGRATION_GUIDE.md

Phoenix Migration Guide

Comprehensive guide for migrating to Phoenix operating model from existing systems and cloud providers

This document provides step-by-step migration guides for moving to Phoenix operating model from existing tenant-based systems, Azure, and AWS.

---

Executive Summary

Migration to Phoenix operating model involves mapping existing entities to Phoenix's five control planes (Commercial, Tenancy, Subscription, Environment, Content & DevOps). This guide provides detailed migration paths for:

1. Existing Phoenix Tenant-Based Model → New Operating Model
2. Azure → Phoenix
3. AWS → Phoenix

Migration Principles:

• Minimal Disruption: Phased migration to minimize downtime
• Data Preservation: Preserve all data and configurations
• Identity Continuity: Maintain user access during migration
• Validation: Comprehensive validation at each phase

---

I. Migration from Existing Phoenix Model

Current State Analysis

Existing Model:

• Tenant-based billing and identity
• Tenant quotas and limits
• Keycloak realms per tenant
• Direct tenant-to-resource mapping

Target Model:

• Client (Billing Profile) → Tenant → Subscription → Environment
• Separated commercial, tenancy, subscription, and environment planes
• Content & DevOps plane separate from billing/tenancy

Migration Strategy

Phase 1: Create Client Structure

Step 1: Analyze Existing Tenants

• Identify all existing tenants
• Group tenants by billing entity (if applicable)
• Document tenant relationships

Step 2: Create Clients

• Create Client for each billing entity
• Map existing tenants to Clients
• Configure billing for Clients

Step 3: Migrate Billing

• Aggregate existing tenant billing to Client level
• Configure Client-level invoicing
• Set up cost centers if needed

Phase 2: Restructure Tenants

Step 1: Review Tenant Structure

• Review existing tenant configurations
• Identify tenant domains and identity providers
• Document tenant compliance profiles

Step 2: Update Tenant Model

• Update tenants with new attributes (data residency, compliance)
• Maintain Keycloak realm mapping (1:1)
• Preserve tenant identity and access

Step 3: Validate Tenant Access

• Verify Keycloak realm access
• Test identity provider configuration
• Validate user access

Phase 3: Create Subscriptions

Step 1: Analyze Tenant Resources

• Identify resources per tenant
• Group resources by service type
• Document quotas and limits

Step 2: Create Subscriptions

• Create Subscriptions for each tenant
• Map service bundles to Subscriptions
• Configure quotas and limits
• Assign Policy Packs

Step 3: Migrate Resources

• Map existing resources to Subscriptions
• Update resource ownership
• Validate resource access

Phase 4: Create Environments

Step 1: Identify Environment Types

• Identify DEV, INT, UAT, STAGING, PROD environments
• Document environment configurations
• Map resources to environments

Step 2: Create Environments

• Create Environment entities
• Configure network and data isolation
• Set up deployment policies
• Configure promotion flows

Step 3: Migrate Resources

• Assign resources to Environments
• Update resource configurations
• Validate environment isolation

Phase 5: Content & DevOps Migration

Step 1: Analyze Content Structure

• Identify Git repositories
• Document application structure
• Map applications to environments

Step 2: Create Content Hierarchy

• Create Enterprise, Portfolio, Product, Application entities
• Map Git repositories to Applications
• Configure ownership and governance

Step 3: Configure CI/CD

• Update CI/CD pipelines for new model
• Configure promotion flows
• Set up approval workflows

Migration Scripts

Create Client from Tenant

mutation {
  migrateTenantToClient(tenantId: "existing-tenant-id", input: {
    clientName: "Client from Tenant"
    preserveTenant: true
    migrateBilling: true
  }) {
    client {
      id
      name
    }
    tenant {
      id
      name
      client {
        id
      }
    }
  }
}

Create Subscription from Tenant Resources

mutation {
  migrateTenantResourcesToSubscription(tenantId: "tenant-id", input: {
    subscriptionName: "Subscription from Tenant"
    serviceBundles: [COMPUTE, STORAGE, NETWORKING]
    preserveResources: true
  }) {
    subscription {
      id
      name
    }
    resources {
      id
      name
      subscription {
        id
      }
    }
  }
}

Validation Checklist

• All Clients created and configured
• All Tenants mapped to Clients
• Billing aggregated at Client level
• All Subscriptions created
• Resources mapped to Subscriptions
• All Environments created
• Resources assigned to Environments
• Content hierarchy created
• CI/CD pipelines updated
• User access validated
• Billing validated
• Compliance validated

---

II. Migration from Azure

Pre-Migration Assessment

Step 1: Inventory Azure Resources

Azure AD Tenants:

• List all Azure AD Tenants
• Document tenant domains
• Identify identity providers
• Document user and group structure

Azure Subscriptions:

• List all Azure Subscriptions
• Document subscription billing
• Identify resource groups
• Document resources per subscription

Resources:

• List all Azure resources
• Document resource types
• Identify resource dependencies
• Document resource configurations

Step 2: Map to Phoenix Model

Azure AD Tenant → Phoenix Tenant:

• One Azure AD Tenant = One Phoenix Tenant
• Preserve domain and identity configuration
• Map identity providers

Azure Subscription → Phoenix Subscription:

• One Azure Subscription = One Phoenix Subscription (or multiple if needed)
• Map service bundles
• Map quotas and limits

Azure Resource Group → Phoenix Environment:

• Map Resource Groups to Environments
• Identify environment types (DEV, PROD, etc.)
• Map resources to Environments

Azure Billing Account → Phoenix Client:

• One Azure Billing Account = One Phoenix Client
• Aggregate billing from Azure Subscriptions

Migration Process

Phase 1: Setup Phoenix Structure

Step 1: Create Phoenix Client

mutation {
  createClient(input: {
    name: "Client from Azure"
    legalEntity: {
      name: "Legal Entity Name"
      jurisdiction: "Jurisdiction"
    }
    invoicingConfig: {
      format: PDF
      frequency: MONTHLY
      currency: "USD"
    }
  }) {
    id
    name
  }
}

Step 2: Create Phoenix Tenants

• Create Tenant for each Azure AD Tenant
• Configure primary domains
• Set up Keycloak realm
• Configure identity provider

mutation {
  createTenant(input: {
    name: "Tenant from Azure AD"
    clientId: "client-id"
    primaryDomains: ["domain.com"]
    identityProvider: {
      type: KEYCLOAK
      config: {}
    }
    rbacNamespace: "tenant-namespace"
  }) {
    id
    name
    keycloakRealmId
  }
}

Step 3: Create Phoenix Subscriptions

• Create Subscription for each Azure Subscription
• Map service bundles
• Configure quotas and limits
• Assign Policy Packs

mutation {
  createSubscription(input: {
    name: "Subscription from Azure"
    tenantId: "tenant-id"
    type: PRODUCT
    serviceBundles: [COMPUTE, STORAGE, NETWORKING]
    quotas: {
      compute: {
        vcpu: 100
        memory: 512
        instances: 50
      }
    }
  }) {
    id
    name
  }
}

Phase 2: Migrate Identity

Step 1: Export Azure AD Users

• Export users from Azure AD
• Export groups from Azure AD
• Export roles from Azure AD

Step 2: Import to Keycloak

• Import users to Keycloak realm
• Import groups to Keycloak realm
• Import roles to Keycloak realm
• Configure identity provider federation (if needed)

Step 3: Validate Identity

• Test user authentication
• Verify group membership
• Validate role assignments

Phase 3: Migrate Resources

Step 1: Export Azure Resources

• Export VM configurations
• Export storage configurations
• Export network configurations
• Export application configurations

Step 2: Convert to Phoenix Format

• Convert VM configurations
• Convert storage configurations
• Convert network configurations
• Convert application configurations

Step 3: Import to Phoenix

• Create Environments
• Provision resources in Phoenix
• Configure networking
• Validate resource access

Phase 4: Migrate Applications

Step 1: Analyze Applications

• Identify containerized applications
• Identify VM-based applications
• Identify serverless applications
• Document application dependencies

Step 2: Migrate Applications

• Migrate containerized applications to Phoenix Kubernetes
• Migrate VM-based applications to Phoenix VMs
• Port serverless applications (if applicable)
• Update application configurations

Step 3: Update CI/CD

• Update CI/CD pipelines for Phoenix
• Configure promotion flows
• Set up approval workflows

Migration Tools

Azure Export Script

#!/bin/bash
# Export Azure resources

# Export Azure AD Tenants
az ad tenant list --output json > azure-tenants.json

# Export Azure Subscriptions
az account list --output json > azure-subscriptions.json

# Export Resources per Subscription
for sub in $(az account list --query "[].id" -o tsv); do
  az account set --subscription $sub
  az resource list --output json > "azure-resources-$sub.json"
done

Phoenix Import Script

#!/bin/bash
# Import to Phoenix

# Create Clients
jq -r '.tenants[] | .name' azure-tenants.json | while read tenant; do
  # Create Client and Tenant
  # Import resources
done

Validation Checklist

• All Azure AD Tenants mapped to Phoenix Tenants
• All Azure Subscriptions mapped to Phoenix Subscriptions
• All Azure Resources migrated to Phoenix
• Identity migrated and validated
• Applications migrated and validated
• CI/CD pipelines updated
• Billing validated
• User access validated
• Compliance validated

---

III. Migration from AWS

Pre-Migration Assessment

Step 1: Inventory AWS Resources

AWS Organizations:

• List all AWS Organizations
• Document organization structure
• Identify accounts per organization
• Document billing configuration

AWS Accounts:

• List all AWS Accounts
• Document account billing
• Identify resources per account
• Document resource configurations

Resources:

• List all AWS resources
• Document resource types
• Identify resource dependencies
• Document resource configurations

Step 2: Map to Phoenix Model

AWS Organization → Phoenix Client/Tenant:

• One AWS Organization = One Phoenix Client (or multiple if needed)
• AWS Accounts map to Phoenix Tenants or Subscriptions
• Preserve organization structure

AWS Account → Phoenix Subscription:

• One AWS Account = One Phoenix Subscription (or multiple if needed)
• Map service bundles
• Map quotas and limits

AWS Region → Phoenix Landing Zone:

• Map AWS Regions to Phoenix Landing Zones
• Configure regional data residency
• Set up regional governance

AWS Resource Groups/Tags → Phoenix Environment:

• Map Resource Groups/Tags to Environments
• Identify environment types
• Map resources to Environments

Migration Process

Phase 1: Setup Phoenix Structure

Step 1: Create Phoenix Client

mutation {
  createClient(input: {
    name: "Client from AWS"
    legalEntity: {
      name: "Legal Entity Name"
      jurisdiction: "Jurisdiction"
    }
    invoicingConfig: {
      format: PDF
      frequency: MONTHLY
      currency: "USD"
    }
  }) {
    id
    name
  }
}

Step 2: Create Phoenix Tenants

• Create Tenant for AWS Organization or Account
• Configure primary domains
• Set up Keycloak realm
• Configure identity provider

mutation {
  createTenant(input: {
    name: "Tenant from AWS"
    clientId: "client-id"
    primaryDomains: ["domain.com"]
    identityProvider: {
      type: KEYCLOAK
      config: {}
    }
    rbacNamespace: "tenant-namespace"
  }) {
    id
    name
    keycloakRealmId
  }
}

Step 3: Create Phoenix Subscriptions

• Create Subscription for each AWS Account
• Map service bundles
• Configure quotas and limits
• Assign Policy Packs

mutation {
  createSubscription(input: {
    name: "Subscription from AWS"
    tenantId: "tenant-id"
    type: PRODUCT
    serviceBundles: [COMPUTE, STORAGE, NETWORKING]
    quotas: {
      compute: {
        vcpu: 100
        memory: 512
        instances: 50
      }
    }
  }) {
    id
    name
  }
}

Phase 2: Migrate Identity

Step 1: Export AWS IAM

• Export IAM users
• Export IAM groups
• Export IAM roles
• Export IAM policies

Step 2: Import to Keycloak

• Import users to Keycloak realm
• Import groups to Keycloak realm
• Import roles to Keycloak realm
• Configure identity provider federation (if needed)

Step 3: Validate Identity

• Test user authentication
• Verify group membership
• Validate role assignments

Phase 3: Migrate Resources

Step 1: Export AWS Resources

• Export EC2 instances
• Export S3 buckets
• Export RDS databases
• Export VPC configurations
• Export application configurations

Step 2: Convert to Phoenix Format

• Convert EC2 to Phoenix VMs
• Convert S3 to Phoenix object storage
• Convert RDS to Phoenix databases
• Convert VPC to Phoenix networks
• Convert application configurations

Step 3: Import to Phoenix

• Create Environments
• Provision resources in Phoenix
• Configure networking
• Validate resource access

Phase 4: Migrate Applications

Step 1: Analyze Applications

• Identify containerized applications (ECS, EKS)
• Identify EC2-based applications
• Identify Lambda functions
• Document application dependencies

Step 2: Migrate Applications

• Migrate ECS/EKS applications to Phoenix Kubernetes
• Migrate EC2 applications to Phoenix VMs
• Port Lambda functions (if applicable)
• Update application configurations

Step 3: Update CI/CD

• Update CI/CD pipelines for Phoenix
• Configure promotion flows
• Set up approval workflows

Migration Tools

AWS Export Script

#!/bin/bash
# Export AWS resources

# Export AWS Organizations
aws organizations list-accounts --output json > aws-accounts.json

# Export Resources per Account
for account in $(aws organizations list-accounts --query "Accounts[].Id" --output text); do
  aws sts assume-role --role-arn "arn:aws:iam::$account:role/MigrationRole" --role-session-name migration
  aws ec2 describe-instances --output json > "aws-ec2-$account.json"
  aws s3 ls --output json > "aws-s3-$account.json"
done

Phoenix Import Script

#!/bin/bash
# Import to Phoenix

# Create Clients and Tenants
jq -r '.accounts[] | .name' aws-accounts.json | while read account; do
  # Create Client and Tenant
  # Import resources
done

Validation Checklist

• All AWS Organizations mapped to Phoenix Clients/Tenants
• All AWS Accounts mapped to Phoenix Subscriptions
• All AWS Resources migrated to Phoenix
• Identity migrated and validated
• Applications migrated and validated
• CI/CD pipelines updated
• Billing validated
• User access validated
• Compliance validated

---

IV. Migration Planning

Assessment Phase

Duration: 2-4 weeks

Activities:

1. Inventory existing resources
2. Map to Phoenix model
3. Identify migration complexity
4. Estimate migration timeline
5. Identify risks and mitigation

Deliverables:

• Migration assessment report
• Entity mapping document
• Migration timeline
• Risk assessment

Planning Phase

Duration: 2-4 weeks

Activities:

1. Create migration plan
2. Design Phoenix structure
3. Plan identity migration
4. Plan resource migration
5. Plan application migration
6. Plan cutover strategy

Deliverables:

• Migration plan
• Phoenix structure design
• Cutover plan
• Rollback plan

Execution Phase

Duration: 4-12 weeks (depending on scale)

Activities:

1. Setup Phoenix structure
2. Migrate identity
3. Migrate resources
4. Migrate applications
5. Update CI/CD
6. Validate migration

Deliverables:

• Migrated resources
• Updated applications
• Validation reports

Cutover Phase

Duration: 1-2 weeks

Activities:

1. Final validation
2. Cutover execution
3. Monitor and support
4. Decommission old systems

Deliverables:

• Cutover completion
• Decommission confirmation

---

V. Risk Mitigation

Common Risks

Risk 1: Data Loss

Mitigation:

• Comprehensive backup before migration
• Validation at each migration step
• Rollback plan ready
• Data verification after migration

Risk 2: Identity Disruption

Mitigation:

• Parallel identity systems during migration
• Gradual user migration
• Identity validation at each step
• Rollback capability

Risk 3: Application Downtime

Mitigation:

• Phased migration
• Parallel systems during migration
• Minimal downtime windows
• Rollback capability

Risk 4: Billing Disruption

Mitigation:

• Parallel billing during migration
• Billing validation
• Cost reconciliation
• Rollback capability

Rollback Plans

Rollback Triggers

• Data loss detected
• Identity disruption
• Application failures
• Billing errors
• Compliance violations

Rollback Process

1. Immediate: Stop migration, restore from backup
2. Assessment: Identify issues, assess impact
3. Remediation: Fix issues, re-validate
4. Resume: Resume migration after validation

---

VI. Post-Migration

Validation

Functional Validation:

• All resources accessible
• All applications functional
• All users can authenticate
• All billing accurate

Performance Validation:

• Performance meets requirements
• No performance degradation
• Scalability validated

Security Validation:

• Security policies enforced
• Access controls working
• Audit logging functional

Compliance Validation:

• Compliance requirements met
• Audit trails complete
• Compliance reporting functional

Optimization

Post-Migration Optimization:

• Optimize resource allocation
• Optimize costs
• Optimize performance
• Optimize security

Documentation

Update Documentation:

• Update architecture documentation
• Update operational runbooks
• Update user guides
• Update compliance documentation

---

References

Phoenix Operating Model Documentation

• Operating Model - Core operating model documentation
• Architecture Diagrams - Visual diagrams of the operating model
• Cloud Provider Mapping - Azure/AWS mapping and competitive analysis
• Multi-Region Landing Zones - Landing zone patterns and deployment
• MVP Control Plane - Minimum viable product specification

Existing Documentation (Current Model)

• Tenant Management - Current tenant-based model
• Billing Guide - Current billing model
• Identity Setup - Current identity model

---

Last Updated: 2025-01-09
Version: 1.0
Status: Complete Migration Guide