ResourceQuota: Namespace Resource Budgets

Why it exists

Kubernetes clusters are shared infrastructure. Without guardrails, one team or application can create unlimited pods, services, or persistent volume claims, exhausting node capacity or the control plane's object store. ResourceQuota was designed to give cluster administrators a policy lever to cap aggregate consumption at the namespace boundary, ensuring fair sharing and preventing resource starvation across tenants.

The mental model

Think of a namespace as a shared apartment and ResourceQuota as the lease agreement that sets maximums. It does not throttle running workloads; it blocks the front door. Once the cumulative resource requests or object counts in that namespace reach the ceiling, the API server refuses to admit anything new. It is a hard budget, not a speed limit.

How it works

A cluster administrator creates a ResourceQuota object in a target namespace. The object specifies hard limits for compute resources such as CPU and memory, storage resources like persistent volume claims, and object counts including pods, services, configmaps, secrets, and replication controllers. The ResourceQuota admission controller intercepts creation and update requests. If the action would cause the namespace to exceed any defined hard limit, the API server returns a 403 Forbidden status and the operation fails. Quotas are calculated using the resource requests and limits specified in pod and container specs, not observed utilization metrics.

When to use it

Use ResourceQuota in any multi-tenant or multi-team cluster where namespaces map to organizational boundaries. It is also valuable in development or sandbox environments to prevent runaway CI jobs or accidental infinite loops from provisioning thousands of objects. If you charge back infrastructure costs by namespace, quotas enforce the contractual spending limit.

When not to use it

Do not use ResourceQuota as a runtime performance throttle. It does not reduce CPU or memory for running pods when utilization spikes. It also cannot protect against actual node-level exhaustion if pods use far less than their requested limits; a node can still run out of physical memory even when the namespace quota is nowhere near its cap. For runtime throttling, use limits on containers or quality of service classes. Do not rely on ResourceQuota alone if your workloads frequently omit resource requests, because the admission controller may reject otherwise valid pods.

One canonical example

A platform team runs a cluster for three engineering groups, each with their own namespace. They create a ResourceQuota in the payments namespace that allows twenty pods, a total of forty CPU cores in requests, and one hundred gigabytes of memory in requests. A developer submits a deployment with a replica count of twenty-five. The first twenty pods are admitted, but the twenty-first pod is rejected by the API server with a forbidden error because the pod count hard limit was reached. The developer must either delete old pods or request a quota increase from the platform team.