chore: consolidate local WIP (repo cleanup 20260707)

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/phoenix/MIGRATION_GUIDE.md

@@ -0,0 +1,841 @@
+# 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
+