Skip to content

Tier Concepts

This section provides reference information about how the tier system works.

Tier Membership Mapping

MaaS and Kubernetes administrators can defined the subscription levels using the tier-to-group-mapping ConfigMap in the maas-api namespace:

tier-to-group-mapping.yaml ConfigMap example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tier-to-group-mapping
  namespace: maas-api
data:
  tiers: |
    - name: free
      description: Free tier for basic users
      level: 1
      groups:
      - system:authenticated
    - name: premium
      description: Premium tier
      level: 10
      groups:
      - premium-users
    - name: enterprise
      description: Enterprise tier
      level: 20
      groups:
      - enterprise-users

ConfigMap Field Breakdown

Field Purpose Default Value
name The tier identifier used throughout the system. Must be unique and matches tier names in rate limit policies. free, premium, enterprise
description Human-readable description of the tier's purpose and who it's intended for. Used for documentation and UI display. Free tier for basic users, Enterprise tier for high-volume customers
level Numeric hierarchy for tier precedence. Higher numbers indicate higher tiers.
When a user belongs to multiple groups, the highest level tier is selected.		 1 (lowest), 10 (medium), 20 (highest)
groups Kubernetes groups whose members are assigned to this tier.
Users must be members of at least one group in the list to get this tier.		 system:authenticated, premium-users, enterprise-users

Important Notes:

  • Users with multiple group memberships are assigned to the tier with the highest level number
  • The system:authenticated group includes all authenticated users, commonly used for the free tier
  • Group names must exist in your Kubernetes identity provider (LDAP, OIDC, etc.)
  • Tier name values are case-sensitive and must match exactly with rate limit policy predicates

Tier Rate Limits Configuration

MaaS and Kubernetes administrators can configure rate limits for each tier using the RateLimitPolicy custom resource.

RateLimitPolicy.yaml example:

apiVersion: kuadrant.io/v1beta2
kind: RateLimitPolicy
metadata:
  name: model-rate-limits
  namespace: llm

Tier Namespaces

Each tier gets a dedicated namespace following the pattern <instance-name>-tier-<tier-name>:

  • maas-default-gateway-tier-free
  • maas-default-gateway-tier-premium
  • maas-default-gateway-tier-enterprise

Tier Resolution Process

  1. User authenticates with JWT token
  2. Gateway extracts user groups from token
  3. MaaS API resolves tier based on group membership
  4. Tier information is cached for 5 minutes
  5. Access control and rate limiting are applied based on tier