Tier Migrations

Tier migrations allow tenants to upgrade from one service tier to another. The migration process involves payment validation, infrastructure provisioning (for dedicated tier upgrades), data migration, verification, and optional rollback. The TierMigrationController at /api/v1/migrations orchestrates the full lifecycle.

Supported Migration Paths

From	To	Infrastructure Change	Requires SP Credentials
FREE	STARTER	Shared cluster	No
FREE	PROFESSIONAL	Dedicated infrastructure	Yes
FREE	ENTERPRISE	Dedicated infrastructure	Yes
STARTER	PROFESSIONAL	Shared to dedicated	Yes
STARTER	ENTERPRISE	Shared to dedicated	Yes
PROFESSIONAL	ENTERPRISE	Dedicated to dedicated	No

Migration Lifecycle

INITIATED --> PAYMENT_VALIDATED --> CREDENTIALS_SUBMITTED --> PROVISIONING
     |                                                            |
     v                                                            v
  CANCELLED                                                  VERIFYING
                                                                  |
                                                          +-------+-------+
                                                          |               |
                                                     COMPLETED      ROLLING_BACK
                                                                         |
                                                                    ROLLED_BACK

Key Concepts

Migration Job: A TierMigrationJob entity tracks the full lifecycle of a tier change
Payment Validation: Platform admins confirm payment before provisioning begins
Service Principal Credentials: Required for dedicated-tier upgrades (Azure subscription access)
Verification Period: After provisioning completes, tenants verify functionality before finalizing
Rollback: During the verification period, tenants can roll back to the previous tier

Endpoints Summary

Method	Path	Description
`POST`	`/migrations/tenants/{tenantId}/upgrade-tier`	Initiate tier migration
`GET`	`/migrations/{jobId}`	Get migration job details
`GET`	`/migrations/tenants/{tenantId}/status`	Get active migration status
`GET`	`/migrations/tenants/{tenantId}/history`	Get migration history
`POST`	`/migrations/{jobId}/validate-payment`	Validate payment (admin)
`POST`	`/migrations/{jobId}/submit-credentials`	Submit SP credentials
`POST`	`/migrations/{jobId}/complete-verification`	Finalize migration
`POST`	`/migrations/{jobId}/rollback`	Rollback migration
`POST`	`/migrations/{jobId}/cancel`	Cancel migration
`GET`	`/migrations`	List active migrations (admin)
`GET`	`/migrations/stats`	Migration statistics (admin)

Source Files

File	Path
Controller	`control-plane/tenant-service/src/main/java/com/matih/tenant/controller/TierMigrationController.java`
Service	`control-plane/tenant-service/src/main/java/com/matih/tenant/service/migration/TierMigrationService.java`
Entity	`control-plane/tenant-service/src/main/java/com/matih/tenant/entity/TierMigrationJob.java`

Rollback Procedures Tier Migration