Tier Migration Workflow

The tier migration workflow is a multi-step process managed by the TierMigrationController. Each migration is tracked as a TierMigrationJob entity with full audit trail and rollback support.

Initiating a Migration

To upgrade a tenant's tier, send an InitiateMigrationRequest specifying the target tier:

public record InitiateMigrationRequest(
        @NotNull TenantTier targetTier
) {}

curl -X POST http://localhost:8082/api/v1/migrations/tenants/{tenantId}/upgrade-tier \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetTier": "PROFESSIONAL"
  }'

Response (201 Created):

{
  "id": "a1b2c3d4-...",
  "tenantId": "e5f6a7b8-...",
  "sourceTier": "STARTER",
  "targetTier": "PROFESSIONAL",
  "status": "INITIATED",
  "initiatedBy": "c9d0e1f2-...",
  "initiatedAt": "2026-02-12T10:00:00Z"
}

Authorization: Requires ADMIN role or tenant management permission via @tenantSecurityService.canManageTenant.

Payment Validation

After initiation, a platform administrator must validate payment before provisioning begins:

curl -X POST http://localhost:8082/api/v1/migrations/{jobId}/validate-payment \
  -H "Authorization: Bearer $ADMIN_TOKEN"

This endpoint requires the PLATFORM_ADMIN role. After validation, the migration status transitions to PAYMENT_VALIDATED.

Submitting Service Principal Credentials

For migrations that require dedicated infrastructure (moving from shared to dedicated clusters), the tenant must provide Azure Service Principal credentials:

public record SubmitCredentialsRequest(
        @NotBlank String clientId,
        @NotBlank String clientSecretRef,
        @NotBlank String azureTenantId,
        @NotBlank String subscriptionId
) {}

curl -X POST http://localhost:8082/api/v1/migrations/{jobId}/submit-credentials \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "sp-client-id",
    "clientSecretRef": "keyvault-secret-ref",
    "azureTenantId": "azure-tenant-id",
    "subscriptionId": "azure-subscription-id"
  }'

Note that clientSecretRef is a reference to a secret stored in Key Vault, not the actual secret value.

Completing Verification

After provisioning completes, the tenant enters a verification period where they can test the new infrastructure. To finalize:

curl -X POST http://localhost:8082/api/v1/migrations/{jobId}/complete-verification \
  -H "Authorization: Bearer $TOKEN"

This transitions the migration to COMPLETED and the tenant is now on the new tier.

Rollback During Verification

If issues are discovered during verification, the tenant can roll back to the previous tier:

public record RollbackRequest(
        @NotBlank String reason
) {}

curl -X POST http://localhost:8082/api/v1/migrations/{jobId}/rollback \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Performance degradation observed in new infrastructure"
  }'

Cancelling a Migration

An in-progress migration can be cancelled before provisioning completes:

public record CancelRequest(
        @NotBlank String reason
) {}

curl -X POST http://localhost:8082/api/v1/migrations/{jobId}/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Budget constraints require postponement"
  }'

Checking Migration Status

Get Active Migration

curl http://localhost:8082/api/v1/migrations/tenants/{tenantId}/status \
  -H "Authorization: Bearer $TOKEN"

Returns 404 if no active migration exists.

Get Migration History

curl http://localhost:8082/api/v1/migrations/tenants/{tenantId}/history \
  -H "Authorization: Bearer $TOKEN"

Returns all migration jobs for the tenant, ordered by initiation date.

Admin Endpoints

List All Active Migrations

curl http://localhost:8082/api/v1/migrations \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Requires PLATFORM_ADMIN role. Returns all currently active migration jobs across all tenants.

Migration Statistics

curl http://localhost:8082/api/v1/migrations/stats \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Returns a MigrationStats object with aggregated data about migration counts, success rates, and average durations.

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`

Overview Tenant Upgrades