Chapter 7: Tenant Lifecycle and Provisioning

The Tenant Service is the largest and most complex service in the MATIH control plane, orchestrating the full lifecycle of tenant organizations from initial registration through infrastructure provisioning, day-to-day operations, upgrades, and eventual decommissioning. With 25+ controllers, 30+ services, and 20+ repositories, this service serves as the backbone of MATIH's multi-tenant architecture.

What You Will Learn

By the end of this chapter, you will understand:

• Tenant management -- creating, updating, suspending, and deleting tenants with full lifecycle state tracking
• Multi-phase provisioning -- the 56-step provisioning pipeline that takes a tenant from registration to a fully operational data platform
• Two-tier provisioning paths -- how FREE tier shared-cluster provisioning differs from PROFESSIONAL/ENTERPRISE dedicated infrastructure
• State machine orchestration -- how provisioning, upgrades, and migrations are modeled as state machines with explicit transitions and rollback
• DNS and ingress management -- Azure DNS child zones, NS delegation, per-tenant NGINX ingress controllers, and TLS certificate provisioning
• Tier migration -- upgrading tenants between FREE, STARTER, PROFESSIONAL, and ENTERPRISE tiers
• Branding and custom domains -- white-label customization, theme presets, custom domain registration with DNS verification and SSL
• Resource management -- quotas, usage tracking, alerts, cost attribution, and cost dashboards
• Privacy compliance -- GDPR/CCPA consent management, data subject requests, encryption key lifecycle, and privacy dashboards
• Helm release management -- installing, upgrading, rolling back, and monitoring Helm releases per tenant
• Platform deployment -- recording deployments, version tracking, and platform-level rollback
• Playground environments -- free-tier sandbox slots, waitlists, and conversion to paid subscriptions

Chapter Structure

Service at a Glance

Domain Model Overview

The tenant entity is the central aggregate in the service. Key fields include:

public class Tenant {
    private UUID id;
    private String name;
    private String slug;                    // Unique, URL-safe identifier (3-63 chars)
    private TenantTier tier;                // FREE, STARTER, PROFESSIONAL, ENTERPRISE
    private TenantStatus status;            // PENDING, PROVISIONING, ACTIVE, UPGRADING, SUSPENDED, FAILED, DELETED
    private DeploymentType deploymentType;  // SHARED or DEDICATED
    private String region;                  // Cloud region (default: eastus)
    private String kubernetesNamespace;     // Assigned K8s namespace
    private String ingressIp;              // Dedicated LoadBalancer IP
    private String dnsZoneId;              // Azure DNS zone resource ID
    // ... 60+ fields for billing, trial, playground, provisioning tracking
}

Tenant Tiers

Key Design Principles

State machine-driven orchestration. Every long-running operation (provisioning, upgrades, migrations, tier changes) is modeled as a state machine with explicit transitions, guards, and actions. This provides clear visibility into operation status and enables reliable recovery from failures.

Two-tier separation. Control plane operations (metadata, configuration, billing) are separated from data plane operations (Kubernetes resources, Helm releases, infrastructure). This separation enables the control plane to remain responsive even when data plane operations are slow or failing.

Idempotent provisioning. Every provisioning step is designed to be safely re-executed. If a step fails midway, the orchestrator can retry from the current state without duplicating resources. Each step carries an idempotency key formed as {tenantId}-{stepType}.

Tenant isolation at every layer. Database queries are scoped by tenant ID. Kubernetes resources are deployed to tenant-specific namespaces. DNS zones are isolated per tenant. Network policies enforce pod-level isolation.

How This Chapter Connects

The tenant service is the hub of the control plane. It consumes the IAM service (Chapter 6) for user creation during provisioning. It drives the deployment of all data plane services documented in Chapters 9-14. It coordinates with the platform services (Chapter 8) for configuration management, notifications, audit logging, and billing. The Kubernetes deployment topology documented in Chapter 17 is orchestrated by the provisioning phases described in this chapter.

Prerequisites

To get the most from this chapter, you should be familiar with:

• Multi-tenant SaaS architecture patterns
• Kubernetes namespaces, RBAC, and network policies
• Helm chart deployment and release management
• DNS zone delegation and record types
• Azure Resource Manager concepts (for DNS and AKS sections)
• State machine patterns for workflow orchestration

Begin with the Tenant Service Architecture for a comprehensive view of the service internals, or jump to Tenant Management to start with the CRUD operations.