Tenant Upgrades

When a tenant upgrades from a shared-cluster tier (FREE/STARTER) to a dedicated-infrastructure tier (PROFESSIONAL/ENTERPRISE), the platform provisions new infrastructure, migrates data, and transitions services. This page details the upgrade provisioning flow.

Upgrade Flow: Shared to Dedicated

The ProvisioningOrchestrator handles the two-tier upgrade flow:

1. Validate Service Principal credentials
2. Acquire Terraform lock
3. Provision infrastructure (AKS cluster, networking, storage)
4. Create Kubernetes resources (namespaces, RBAC, network policies)
5. Deploy data plane services (13 services)
6. Setup DNS zones and ingress
7. Migrate data from shared cluster
8. Setup observability stack
9. Verification period
10. Cutover (DNS switch + decommission old resources)

Infrastructure Provisioning

For dedicated tiers, the orchestrator calls executeDedicatedTierFlow():

private void executeDedicatedTierFlow(UUID tenantId, String clusterName) {
    // Phase 1: Validate Azure Service Principal
    stateMachine.transition(tenantId, VALIDATING_SERVICE_PRINCIPAL);
    provisioningService.validateServicePrincipal(tenantId);
 
    // Phase 2: Acquire Terraform lock
    stateMachine.transition(tenantId, ACQUIRING_TF_LOCK);
    provisioningService.acquireTerraformLock(tenantId, clusterName);
 
    // Phase 3: Provision infrastructure
    stateMachine.transition(tenantId, PROVISIONING_INFRASTRUCTURE);
    provisioningService.provisionInfrastructure(tenantId, clusterName);
 
    // Phase 4: Create K8s resources
    stateMachine.transition(tenantId, CREATING_K8S_RESOURCES);
    provisioningService.createKubernetesResources(tenantId, clusterName);
 
    // Phase 5: Deploy services
    stateMachine.transition(tenantId, DEPLOYING_SERVICES);
    provisioningService.deployServices(tenantId, clusterName);
 
    // Phase 6: Verification
    stateMachine.transition(tenantId, VERIFYING_DEPLOYMENT);
    provisioningService.verifyDeployment(tenantId, clusterName);
}

Data Migration During Upgrade

When upgrading from shared to dedicated infrastructure, tenant data must be migrated:

Database Migration: Export tenant-scoped data from shared PostgreSQL, import into dedicated instance
Object Storage: Copy S3/Blob objects from shared bucket to dedicated storage
Cache Migration: Redis keys are re-populated on the new cluster (cache warming)
Kafka Topics: Topic consumer offsets are reset; historical data is replayed from configured retention

Tier Defaults Applied During Upgrade

When the tier changes, the TenantService applies new tier defaults:

Resource	STARTER	PROFESSIONAL	ENTERPRISE
Max Users	25	100	Unlimited
Max Connections	10	50	200
Storage (GB)	50	500	5000
API Rate Limit	1000/min	5000/min	20000/min
Deployment Type	Shared	Dedicated	Dedicated
Support	Email	Priority	Dedicated
SLA	99.5%	99.9%	99.99%

Monitoring the Upgrade

Use the migration status endpoint to monitor progress:

# Check migration status
curl http://localhost:8082/api/v1/migrations/tenants/{tenantId}/status \
  -H "Authorization: Bearer $TOKEN"
 
# Check provisioning progress (if active)
curl http://localhost:8082/api/v1/tenants/{tenantId}/provisioning/status \
  -H "Authorization: Bearer $TOKEN"
 
# Stream real-time updates
curl -N http://localhost:8082/api/v1/tenants/{tenantId}/provisioning/status/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

Source Files

File	Path
Orchestrator	`control-plane/tenant-service/src/main/java/com/matih/tenant/service/provisioning/ProvisioningOrchestrator.java`
Migration Service	`control-plane/tenant-service/src/main/java/com/matih/tenant/service/migration/TierMigrationService.java`
Tenant Service	`control-plane/tenant-service/src/main/java/com/matih/tenant/service/TenantService.java`

Tier Migration Data Migration