Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Kubernetes Namespaces, ResourceQuotas, and LimitRanges

A namespace is only a boundary when quota and limit range make it one. Aggregate caps, per-pod defaults, the admission errors they produce, and namespaces stuck Terminating.

~4 min readKubernetes
#Kubernetes#Namespace#ResourceQuota#LimitRange
3D illustration of namespace boxes with fill-level meters and a gate rejecting an oversized pod

Quick Summary

Namespaces partition a cluster's names. They do not, by themselves, partition resources, network, or permissions — that is the job of ResourceQuota, LimitRange, NetworkPolicy, and RBAC, each of which uses the namespace as its scope. Deleting a namespace deletes everything in it, asynchronously, and a namespace can sit in Terminating for a long time when a finalizer never resolves.

ResourceQuota caps aggregate consumption per namespace: total requests and limits, object counts, storage. It is enforced at admission, so a pod that would push the namespace past its quota is rejected with a message naming the exceeded resource. LimitRange sets the per-object defaults and bounds — a default requests/limits applied to containers that omit them, plus min/max and a request-to-limit ratio.

Together they close the classic gap: a quota on requests.cpu only works if every container declares a CPU request, so the namespace needs a LimitRange that supplies one, or pods without requests will be rejected at admission with must specify limits.cpu.

Basic Syntax & Core Signatures

yaml
apiVersion: v1 kind: Namespace metadata: name: shop labels: pod-security.kubernetes.io/enforce: restricted --- apiVersion: v1 kind: ResourceQuota metadata: name: shop-quota namespace: shop spec: hard: requests.cpu: "40" requests.memory: 80Gi limits.cpu: "80" limits.memory: 160Gi pods: "120" count/deployments.apps: "30" count/services: "20" services.loadbalancers: "2" persistentvolumeclaims: "25" requests.storage: 500Gi scopes: [] # or e.g. [BestEffort], [NotTerminating]
yaml
apiVersion: v1 kind: LimitRange metadata: name: shop-defaults namespace: shop spec: limits: - type: Container default: # applied when limits are omitted cpu: 500m memory: 512Mi defaultRequest: # applied when requests are omitted cpu: 100m memory: 128Mi min: { cpu: 50m, memory: 64Mi } max: { cpu: "4", memory: 8Gi } maxLimitRequestRatio: cpu: "10" # limit / request must be <= 10 - type: PersistentVolumeClaim min: { storage: 1Gi } max: { storage: 100Gi }
bash
kubectl create namespace shop --dry-run=client -o yaml | kubectl apply -f - kubectl -n shop describe quota shop-quota # Resource Used Hard # -------- ---- ---- # requests.cpu 12 40 # pods 14 120 kubectl -n shop describe limitrange shop-defaults kubectl -n shop get resourcequota -o jsonpath='{.items[*].status.used}{"\n"}'

Key Comparison Table

ObjectScopeApplied atEffect when missing
ResourceQuotaNamespace, aggregateAdmissionNo limit on consumption
LimitRangeNamespace, per objectAdmission (defaulting)Containers may have no requests
NetworkPolicyNamespace, per podCNI dataplaneAll traffic allowed
RoleBindingNamespaceAPI requestForbidden
PSA labelsNamespaceAdmission (pod security)No policy enforcement
Quota resource nameCountsNotes
requests.cpu, requests.memorySum of container requestsRequires requests on every container
limits.cpu, limits.memorySum of container limitsRequires limits on every container
podsPod objectsIncludes init containers' peak
count/<resource>.<group>Objects of that kinde.g. count/jobs.batch
requests.storageSum of PVC requestsPer storage class with <class>.storageclass.storage.k8s.io/requests.storage
services.nodeports, services.loadbalancersService typesCheap protection against accidental cost
SymptomMeaning
exceeded quota: ... requested: requests.cpu=500m, used: ..., limited: ...Aggregate cap reached
must specify limits.cpuQuota requires limits and the container has none
failed quota: ... must be specifiedSame, for requests
pods "x" is forbidden: maximum cpu usage per Container is 4LimitRange max
Namespace stuck TerminatingA finalizer on a resource inside it

Practical Edge Cases & Deep Dives

1. Quota on requests is meaningless without a LimitRange

bash
# Quota caps requests.cpu. A pod with no request is rejected: Error from server (Forbidden): pods "web" is forbidden: failed quota: shop-quota: must specify limits.cpu for: web; requests.cpu for: web

Two fixes exist and they are not equivalent. Adding a LimitRange with default/defaultRequest supplies values at admission, so pods with no resources still run and are counted. Removing requests.cpu from the quota lets those pods run uncounted — which quietly defeats the quota. The LimitRange is the one that preserves the cap.

2. Quota is admission-time: shrinking it does not shrink usage

Lower requests.cpu from 40 to 20 while 30 is in use and the quota object is accepted, the status shows used 30 / hard 20, and the next pod creation fails. Nothing is evicted. Quotas are a gate, not a reaper; reducing consumption means deleting workloads or lowering their requests.

The same applies to pods: "10" with 14 running — the namespace is over budget until pods exit naturally.

3. Scopes: BestEffort and the terminal pods

yaml
spec: hard: pods: "5" scopes: [BestEffort] # only pods with no requests and no limits

A quota with a scope only counts objects matching it, which lets one namespace have a tight BestEffort cap plus a generous general cap. NotTerminating and NotBestEffort are the other common scopes. In older API versions Terminating required activeDeadlineSeconds; that requirement is gone, and a scoped quota whose scope matches no object can look broken while behaving correctly.

4. LimitRange defaults, ratios, and the silent throttling they cause

defaultRequest.cpu: 100m on a namespace with 200 pods is a 20-core reservation the cluster must satisfy. Defaults are convenient and they accumulate: a JVM service that never declared a request now runs with 100m and is throttled at 10% of a core during start-up, which shows up as a slow first request rather than an error.

bash
kubectl -n shop get pods -o jsonpath=\ '{range .items[*]}{.metadata.name}{" "}{.spec.containers[*].resources.requests.cpu}{"\n"}{end}'

maxLimitRequestRatio is the guard against a pod requesting 100m and limiting 4 cores, which makes it a Burstable pod capable of starving neighbours. Setting cpu: "4" forces the request to be at least a quarter of the limit.

5. Namespace deletion, finalizers, and the Terminating trap

bash
kubectl get ns shop -o jsonpath='{.status.phase}{"\n"}' # Terminating kubectl get namespace shop -o json | jq '.status.conditions' # "message": "Some resources are remaining: ... apps.kubernetes.io/... finalizers"

A namespace deletes its contents and then waits for every finalizer. The usual culprits are an APIService that is unavailable (a broken metrics or custom-metrics server removes the API the finalizer needs), a PVC whose provisioner is gone, or an operator that never reconciles. kubectl api-resources --verbs=list --namespaced -o name piped through kubectl get -n shop --show-kind finds what remains. Editing the namespace's spec.finalizers to [] is a last resort that can orphan real resources.

Common Runtime & Configuration Mistakes

SymptomCauseFix
Pods rejected: must specify limits.cpuQuota needs limits on every containerAdd a LimitRange default
exceeded quota on deployAggregate cap reachedRaise the quota or lower requests
Quota shows over 100% usedCap lowered after usageDelete workloads; quotas do not evict
Pod rejected by maxLimitRange ceiling per containerLower the limit or raise max
Every pod throttled in a new namespaceLimitRange defaultRequest too smallSet realistic defaults or remove them
count/deployments.apps rejectedObject-count quota, not resourceRaise the count or consolidate
Namespace Terminating for hoursStuck finalizerFind the remaining resource, fix the API
PVC rejectedpersistentvolumeclaims or storage quotaRaise requests.storage
Service of type LoadBalancer deniedservices.loadbalancers quotaRaise it, or use NodePort
Two teams interfere on CPUNo quota at allQuota per namespace with LimitRange defaults

A namespace is a boundary only when you add the objects that make it one. Quota caps the total, LimitRange fixes the per-pod unit, and both are enforced at admission — which is why the right question after any rejection is which one refused, and what the used/hard numbers were at that moment.

Try matching browser tools

All tools

Small utilities that fit Kubernetes work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Kubernetes guides

More in Kubernetes

All Kubernetes guides

The guides filed next to this one in Kubernetes, in library order.