Technical Insight How-to Guide

Kubernetes Resource Quotas and Limit Ranges: Multi-Tenant Governance

Design Kubernetes namespace resource governance with ResourceQuotas, LimitRanges, monitoring, and GitOps-ready policies for multi-tenant platforms.

Kubernetes Resource Quotas and Limit Ranges: Multi-Tenant Governance
On this page

Shared Kubernetes clusters are attractive because teams can reuse infrastructure, operational tooling, and platform services. But shared infrastructure also creates competition for finite CPU, memory, storage, and API resources.

Without resource governance, one team can exhaust namespace capacity, consume disproportionate scheduler resources, or create enough objects to complicate cluster operations. Kubernetes provides two complementary admission mechanisms: ResourceQuota controls aggregate namespace consumption, while LimitRange defines per-object defaults and boundaries.

Used together, they provide a foundation for predictable namespace onboarding. They do not, by themselves, guarantee fair runtime CPU distribution, storage performance, or tenant security isolation.

Two Controls, Different Responsibilities

MechanismScopeTypical purpose
ResourceQuotaAggregate usage within a namespaceCap requested CPU, memory, storage, and object counts
LimitRangeIndividual containers, pods, or PVCsSupply defaults and enforce minimum/maximum values
Requests and limitsIndividual workloadsInform scheduling and constrain runtime resource use

A quota is an admission-time accounting boundary. It can reject new workloads or expansions that would exceed the configured hard limit. A LimitRange can inject default resource values and reject objects that violate its constraints. Existing running workloads are not automatically resized when a quota changes.

For a production platform, quotas should be sized against real cluster capacity, system overhead, burst requirements, and anticipated rollout headroom—not copied from a generic template.

Set Namespace CPU and Memory Quotas

The following example caps the sum of CPU and memory requests and limits in a development namespace:

apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-quota
  namespace: development
spec:
  hard:
    requests.cpu: "10"
    requests.memory: 20Gi
    limits.cpu: "20"
    limits.memory: 40Gi
    pods: "50"

Apply and inspect it:

kubectl apply -f compute-quota.yaml
kubectl describe resourcequota compute-quota -n development
kubectl get resourcequota -n development -o yaml

Requests are scheduler reservations, not measurements of actual consumption. Limits define resource ceilings for individual containers; CPU is generally throttled at its limit, whereas memory-limit violations can lead to OOM termination. A quota on requests.cpu does not mean the namespace can never consume more than that CPU amount at runtime.

If a namespace has quota constraints on CPU or memory requests/limits, submitted pods must have the corresponding resource values, either explicitly or supplied through admission defaults.

Supply Safe Defaults with LimitRange

A namespace quota alone can produce confusing admission failures when applications omit resource specifications. A LimitRange can provide defaults while rejecting unusually small or large allocations.

apiVersion: v1
kind: LimitRange
metadata:
  name: container-defaults
  namespace: development
spec:
  limits:
    - type: Container
      default:
        cpu: 500m
        memory: 512Mi
      defaultRequest:
        cpu: 100m
        memory: 128Mi
      min:
        cpu: 50m
        memory: 64Mi
      max:
        cpu: "2"
        memory: 4Gi
      maxLimitRequestRatio:
        cpu: "10"
        memory: "4"

These are illustrative values, not universal recommendations. Test them against representative application profiles, including startup peaks, JVM workloads, batch jobs, and memory-intensive services.

Important: Defaults are applied during admission, not retroactively. If several LimitRanges define conflicting defaults in one namespace, behavior may be surprising; establish a single, centrally managed policy for each resource type.

Pod and PVC boundaries

A LimitRange can also constrain the total resources requested by a pod and the size of individual PVCs:

apiVersion: v1
kind: LimitRange
metadata:
  name: workload-boundaries
  namespace: development
spec:
  limits:
    - type: Pod
      max:
        cpu: "4"
        memory: 8Gi
    - type: PersistentVolumeClaim
      min:
        storage: 1Gi
      max:
        storage: 100Gi

Pod-level limits here are constraints on the aggregate container resource specifications, not a substitute for configuring container requests and limits.

Govern Storage and Object Counts

Namespaces can consume cluster resources through more than CPU and memory. PersistentVolumeClaims, Services, Secrets, Jobs, and other objects also need guardrails.

apiVersion: v1
kind: ResourceQuota
metadata:
  name: namespace-objects
  namespace: development
spec:
  hard:
    requests.storage: 200Gi
    persistentvolumeclaims: "20"
    services: "20"
    secrets: "100"
    configmaps: "100"
    count/deployments.apps: "30"
    count/jobs.batch: "50"
    count/cronjobs.batch: "20"
    services.loadbalancers: "2"

StorageClass-specific quotas are also possible, using keys such as:

spec:
  hard:
    fast.storageclass.storage.k8s.io/requests.storage: 100Gi

The StorageClass name must exist in your environment. Storage quota tracks requested PVC capacity; it does not replace storage-backend capacity planning, performance isolation, or snapshot/backup accounting.

For ephemeral storage, Kubernetes supports requests.ephemeral-storage and limits.ephemeral-storage quotas. Actual enforcement and eviction behavior depend on kubelet accounting and node configuration.

Build a Namespace Onboarding Package

A multi-tenant platform should deliver namespace policy as a standard, version-controlled package. The following example combines namespace metadata, compute quota, and defaults:

apiVersion: v1
kind: Namespace
metadata:
  name: team-frontend
  labels:
    team: frontend
    environment: development
---
apiVersion: v1
kind: ResourceQuota
metadata:
  name: team-quota
  namespace: team-frontend
spec:
  hard:
    requests.cpu: "20"
    requests.memory: 40Gi
    limits.cpu: "40"
    limits.memory: 80Gi
    pods: "100"
    persistentvolumeclaims: "20"
    requests.storage: 200Gi
---
apiVersion: v1
kind: LimitRange
metadata:
  name: team-defaults
  namespace: team-frontend
spec:
  limits:
    - type: Container
      default:
        cpu: 500m
        memory: 512Mi
      defaultRequest:
        cpu: 100m
        memory: 128Mi
      min:
        cpu: 50m
        memory: 64Mi
      max:
        cpu: "4"
        memory: 8Gi

In a GitOps workflow, apply namespace governance before application workloads. Argo CD sync waves or separate platform/application Argo CD Applications can establish the required ordering.

The package should also include RBAC, NetworkPolicies, Pod Security Admission settings or OpenShift SCC considerations, and ownership metadata. Quotas are a resource-governance control, not a tenant-isolation boundary.

Allocate Resources by Environment and Workload Class

A development namespace may tolerate smaller defaults and tighter ceilings than a production namespace. But quota design should be based on measured workload demand rather than arbitrary multipliers.

A practical allocation process is:

  1. Measure historical CPU and memory consumption, including peaks and startup behavior.
  2. Determine workload requests and limits, taking application-specific behavior into account.
  3. Reserve headroom for rolling deployments, autoscaling, and recovery after node failure.
  4. Allocate namespace quotas within an explicit cluster capacity budget.
  5. Revisit allocations when workload characteristics or team ownership change.

For example, a Deployment with ten replicas requesting 500m CPU each consumes 5 CPU of request quota. A rollout using maxSurge: 2 can temporarily create two additional pods, requiring 1 CPU of additional request quota. Without headroom, the rollout may stall even though the existing replicas are healthy.

Priority-based quota scopes

ResourceQuota can use scopes and scopeSelector to account for selected pods, including pods associated with specific PriorityClasses:

apiVersion: v1
kind: ResourceQuota
metadata:
  name: high-priority-quota
  namespace: production
spec:
  hard:
    pods: "20"
    requests.cpu: "20"
    requests.memory: 40Gi
  scopeSelector:
    matchExpressions:
      - scopeName: PriorityClass
        operator: In
        values:
          - high

PriorityClasses affect scheduling and preemption behavior; quotas scoped by priority should therefore be part of a broader capacity and admission design.

Monitor Quota Headroom

Inspect quota status directly:

kubectl get resourcequota -A
kubectl describe resourcequota -n development
kubectl get limitrange -n development

Where kube-state-metrics exposes kube_resourcequota, Prometheus can calculate request-quota utilization:

kube_resourcequota{type="used",resource="requests.cpu"}
/
ignoring(type)
kube_resourcequota{type="hard",resource="requests.cpu"}

A warning rule for CPU request quota above 80% could be:

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: namespace-quota-alerts
  namespace: monitoring
spec:
  groups:
    - name: namespace-quota
      rules:
        - alert: NamespaceCPURequestQuotaHigh
          expr: |
            (
              kube_resourcequota{type="used",resource="requests.cpu"}
              /
              ignoring(type)
              kube_resourcequota{type="hard",resource="requests.cpu"}
            ) > 0.8
          for: 10m
          labels:
            severity: warning
          annotations:
            summary: "CPU request quota above 80% in {{ $labels.namespace }}"

The example assumes kube-state-metrics and the Prometheus Operator are installed and the rule is selected by the monitoring stack. On OpenShift, confirm the target monitoring namespace and user-workload monitoring configuration before deploying the rule.

A quota reaching 100% is not automatically an outage: it indicates that further matching allocations may be rejected. Alert severity should reflect actual operational impact, especially if deployment or autoscaling operations are blocked.

Troubleshoot Admission Failures

Exceeded quota

A failed pod creation may report exceeded quota with the affected resource and the requested increment.

kubectl describe resourcequota -n development
kubectl get events -n development --sort-by=.lastTimestamp
kubectl get deployments -n development

Check the quota’s used and hard values, then examine pending rollout replicas, Jobs, and existing resource requests. kubectl top is useful for actual consumption, but it does not explain request-quota usage by itself.

LimitRange rejection

An error such as minimum cpu usage per Container is 50m means the submitted request violates the namespace policy.

kubectl describe limitrange -n development
kubectl get limitrange -n development -o yaml
kubectl apply --dry-run=server -f deployment.yaml

Adjust the workload’s resource specification or revise the policy through the platform governance process.

Missing requests or limits

If a quota requires requests or limits and a workload omits them, admission can fail. Ensure the workload declares the values or that the namespace has appropriate defaults. Avoid relying on defaults as a substitute for application profiling.

Rollout or autoscaling stalls

A deployment may be healthy at steady state but unable to create surge replicas. Likewise, an HPA may request additional replicas that cannot be admitted due to quota exhaustion.

Check controller events and quota headroom before changing cluster-wide capacity settings.

Common Design Mistakes

Treating requests as usage. A namespace request quota accounts for declared reservations, not observed CPU or memory consumption.

Setting quota equal to current demand. This leaves no room for rolling updates, autoscaling, or recovery.

Copying the same defaults to every application. A small API, a JVM service, and a batch processor can have very different resource profiles.

Ignoring object quotas. Large numbers of Jobs, Secrets, or Services can create operational pressure even when CPU and memory usage are modest.

Confusing quota with runtime isolation. Quotas do not guarantee fair storage I/O, network bandwidth, or noisy-neighbor protection.

Introducing quota without observability. Teams need visibility into remaining capacity and a clear process for requesting changes.

From YAML to Platform Governance

The sustainable solution is to make namespace resource policy part of the platform’s self-service interface.

Platform teams can publish resource tiers—for example, small development, standard production, and dedicated high-throughput—with documented request budgets, storage allowances, and object limits. These tiers should map to measured capacity and cost models, not merely arbitrary labels.

GitOps provides reviewable change history, while policy validation in CI/CD catches invalid or excessive resource specifications before deployment. Observability helps identify chronic over-allocation and approaching quota exhaustion.

For Kubernetes and OpenShift environments, this approach integrates naturally with namespace onboarding, RBAC, network segmentation, and application delivery standards.

Conclusion

ResourceQuota and LimitRange solve different but complementary problems. One governs total namespace allocations; the other standardizes individual workload resource specifications.

Together, they make shared clusters easier to operate, reduce accidental resource exhaustion, and give teams predictable boundaries. Their real value appears when they are treated as part of a broader platform contract: documented defaults, measured capacity, automated enforcement, and continuous review.

The objective is not to impose the tightest possible quotas. It is to make resource allocation explicit, observable, and sustainable as teams and workloads grow.

Related Articles

Stay ahead

Get the latest insights.

Insights on cloud, AI and open source — delivered to your inbox.

Email subscriptions are coming soon.