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

```graphql
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

```graphql
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**
```graphql
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

```graphql
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

```graphql
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

```bash
#!/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

```bash
#!/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**
```graphql
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

```graphql
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

```graphql
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

```bash
#!/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

```bash
#!/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](./OPERATING_MODEL.md)** - Core operating model documentation
- **[Architecture Diagrams](./OPERATING_MODEL_DIAGRAMS.md)** - Visual diagrams of the operating model
- **[Cloud Provider Mapping](./CLOUD_PROVIDER_MAPPING.md)** - Azure/AWS mapping and competitive analysis
- **[Multi-Region Landing Zones](./MULTI_REGION_LANDING_ZONES.md)** - Landing zone patterns and deployment
- **[MVP Control Plane](./MVP_CONTROL_PLANE.md)** - Minimum viable product specification

### Existing Documentation (Current Model)

- **[Tenant Management](../tenants/TENANT_MANAGEMENT.md)** - Current tenant-based model
- **[Billing Guide](../tenants/BILLING_GUIDE.md)** - Current billing model
- **[Identity Setup](../tenants/IDENTITY_SETUP.md)** - Current identity model

---

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