Tenant Resource Quotas User Guide

Overview

Per-tenant resource quotas limit CPU, memory, storage, and IOPS to ensure fair resource sharing and prevent noisy neighbor problems.

Benefits

Fair resource allocation
Prevent resource exhaustion
QoS tiers (bronze/silver/gold)
Usage tracking and billing

Prerequisites

HeliosDB v3.2+ with multi-tenancy
Resource accounting enabled
Tenant isolation configured

Configuration

quotas:
  enabled: true
  enforcement_mode: strict  # Or: soft, advisory

  default_limits:
    cpu_percent: 10
    memory_mb: 1024
    storage_gb: 10
    iops: 1000
    connections: 100

SQL Examples

Set Tenant Quotas

-- Create quota profile
CREATE QUOTA PROFILE gold_tier
    CPU_PERCENT = 50
    MEMORY_MB = 8192
    STORAGE_GB = 500
    IOPS = 10000
    CONNECTIONS = 1000;

-- Assign to tenant
ALTER SCHEMA tenant_acme SET quota_profile = 'gold_tier';

Monitor Usage

-- Check quota usage
SELECT
    tenant_name,
    resource_type,
    quota_limit,
    current_usage,
    usage_percent
FROM heliosdb.quota_usage
WHERE tenant_name = 'tenant_acme';

-- Usage over time
SELECT
    DATE_TRUNC('hour', timestamp) as hour,
    AVG(cpu_percent) as avg_cpu,
    MAX(memory_mb) as peak_memory
FROM heliosdb.quota_history
WHERE tenant_name = 'tenant_acme'
  AND timestamp > now() - interval '24 hours'
GROUP BY hour;

QoS Tiers

-- Bronze tier (budget)
CREATE QUOTA PROFILE bronze
    CPU_PERCENT = 10, MEMORY_MB = 1024,
    STORAGE_GB = 10, IOPS = 1000, PRIORITY = 1;

-- Silver tier (standard)
CREATE QUOTA PROFILE silver
    CPU_PERCENT = 25, MEMORY_MB = 4096,
    STORAGE_GB = 100, IOPS = 5000, PRIORITY = 5;

-- Gold tier (premium)
CREATE QUOTA PROFILE gold
    CPU_PERCENT = 50, MEMORY_MB = 16384,
    STORAGE_GB = 1000, IOPS = 20000, PRIORITY = 10;

Enforcement Modes

Strict

enforcement_mode: strict
# Hard limits, queries fail when quota exceeded

Soft

enforcement_mode: soft
# Allows temporary overages, throttles gradually

Advisory

enforcement_mode: advisory
# Monitors only, no enforcement (for testing)

Troubleshooting

Quota Exceeded

-- Check which resource hit limit
SELECT * FROM heliosdb.quota_violations
WHERE tenant_name = 'tenant_acme'
  AND timestamp > now() - interval '1 hour';

-- Temporary increase
ALTER SCHEMA tenant_acme
    SET cpu_percent_limit = 30  -- Increase from 10
    VALID FOR interval '2 hours';

Best Practices

Start with generous quotas
Monitor usage patterns
Adjust based on data
Set alerts for near-limits
Review quotas quarterly
Use soft mode initially

For more: /docs/multi-tenancy/quotas.md