Per-Tenant Ingress

Each tenant in the MATIH platform receives a dedicated NGINX ingress controller with its own LoadBalancer IP address. This architecture provides complete network isolation between tenants at the ingress layer, enables per-tenant rate limiting, and supports tenant-specific TLS certificates and custom domains.

Ingress Architecture

Internet
    |
    v
Azure Load Balancer (20.85.123.45)
    |
    v
NGINX Ingress Controller (matih-acme namespace)
    |
    +--- Host: acme.matih.ai/api/* ---------> api-gateway:8080
    +--- Host: bi.acme.matih.ai/* -----------> bi-workbench:3000
    +--- Host: acme.matih.ai/ws/* -----------> ai-service:8000
    +--- Host: data.acme.matih.ai/* ---------> data-workbench:3002

Key Components

Dedicated Ingress Controller Deployment

The TenantIngressService.deployIngressController() method deploys a dedicated NGINX ingress controller per tenant using Helm:

Deployment Configuration

# Per-tenant NGINX ingress controller values
controller:
  ingressClassResource:
    name: nginx-acme                              # Unique IngressClass per tenant
    controllerValue: k8s.io/ingress-nginx-acme    # Unique controller identifier
  ingressClass: nginx-acme
  replicaCount: 2                                  # Based on tenant tier
  service:
    type: LoadBalancer
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: /healthz
  admissionWebhooks:
    enabled: false                                 # Disabled for tenant controllers
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 256Mi

IngressClass Isolation

Each tenant gets a unique IngressClass name following the pattern nginx-{tenant-slug}. This prevents one tenant's ingress controller from processing another tenant's Ingress resources:

Replica Scaling by Tier

The number of ingress controller replicas is determined by the tenant tier:

The method getTenantIngressReplicas(tenant) in TenantIngressService determines the replica count based on the tenant's tier.

LoadBalancer IP Assignment

After deploying the ingress controller, the TenantIngressService polls the Kubernetes API for the LoadBalancer's external IP:

Polling Logic

public String waitForLoadBalancerIp(String namespace, int maxWaitSeconds) {
    int pollInterval = properties.getIngress()
            .getLoadBalancerPollIntervalSeconds();
    int maxAttempts = maxWaitSeconds / pollInterval;
 
    for (int attempt = 1; attempt <= maxAttempts; attempt++) {
        ServiceList services = kubernetesClient.services()
                .inNamespace(namespace)
                .withLabel("app.kubernetes.io/name", "ingress-nginx")
                .list();
 
        for (Service svc : services.getItems()) {
            List<LoadBalancerIngress> ingresses =
                svc.getStatus().getLoadBalancer().getIngress();
            if (ingresses != null && !ingresses.isEmpty()) {
                String ip = ingresses.get(0).getIp();
                if (ip != null && !ip.isBlank()) {
                    return ip;
                }
            }
        }
 
        Thread.sleep(pollInterval * 1000L);
    }
 
    throw new RuntimeException(
        "LoadBalancer IP not assigned within " + maxWaitSeconds + " seconds");
}

Timeout Configuration

Ingress Resource Creation

After the ingress controller is running and has an IP, the service creates Kubernetes Ingress resources that define routing rules.

Standard Routing Rules

TLS Configuration

TLS is terminated at the ingress controller using certificates issued by cert-manager:

spec:
  tls:
    - hosts:
        - acme.matih.ai
        - "*.acme.matih.ai"
      secretName: acme-tls-certificate

The TLS certificate covers both the root domain and all subdomains via a wildcard SAN.

NGINX Configuration Tuning

The per-tenant NGINX ingress controller is configured with production-grade settings:

Timeouts and Buffers

WebSocket Support

The AI service uses WebSocket connections for streaming responses. The ingress controller is configured to support WebSocket upgrades:

annotations:
  nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
  nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
  nginx.ingress.kubernetes.io/upstream-hash-by: "$remote_addr"

Rate Limiting

Per-tenant rate limiting is configured at the ingress level:

Ingress Health Monitoring

The ingress controller exposes health endpoints that are monitored by the tenant monitoring stack:

Key Metrics

Cleanup on Tenant Deletion

When a tenant is deprovisioned, the ingress resources are cleaned up in order:

1. Delete Ingress resources (routing rules)
2. Delete TLS certificate and secret
3. Uninstall NGINX ingress controller Helm release
4. Azure releases the LoadBalancer IP
5. Delete IngressClass resource

Dev Environment Configuration

In development environments, per-tenant ingress is typically disabled to reduce resource consumption:

Troubleshooting

Validation Script

./scripts/tools/validate-tenant-ingress.sh --tenant acme

This script validates:

• Ingress controller pods are running
• LoadBalancer IP is assigned
• Ingress resources exist with correct rules
• TLS certificate is valid and not expiring
• Backend services are reachable through the ingress

Next Steps

• DNS Zone Management -- DNS records that point to the ingress
• Billing Integration -- how ingress usage affects billing
• API Reference -- ingress management endpoints