Before meeting quotas, we need to understand why a shared cluster can go wrong.

One cluster, many teams

Running a separate cluster for every team is expensive and hard to manage. Most companies therefore let many teams share one cluster, giving each its own section called a namespace. This is efficient, because the computers are used fully rather than sitting idle in separate silos.

The catch is that Kubernetes, by default, does not limit how much any one namespace may use. If a team asks for a hundred copies of a heavy application, the cluster will happily try to provide them, even if that leaves nothing for anyone else.

Three common ways things go wrong

A quick tour of the building blocks that quotas talk about.

The important idea is that the namespace is the natural boundary for sharing. Each team or project lives in its own namespace, and the quota is the limit attached to that boundary.

Quotas count two numbers that every container can declare. You need to know them first.

Requests

A request is the amount of processor power and memory a container asks for as its normal need. The scheduler uses requests to decide where to place a pod. If a node does not have that much unclaimed room, the pod is placed elsewhere or waits. A request is a promise the cluster makes to the container.

Limits

A limit is the maximum a container is allowed to use. If it tries to use more processor power than its limit, it is slowed down. If it tries to use more memory than its limit, it is stopped. A limit is a ceiling the container must respect.

A plain definition, and what makes it special.

The definition

A resource quota is a Kubernetes object that sets a combined limit on how much a whole namespace may consume. It can cap the total processor power and memory, the total storage, and the number of objects such as pods, services and secrets. Once the namespace reaches its limit, any request to create more is refused.

What makes it special

Quotas fall into three broad families, depending on what they limit.

Compute quotas in detail

Compute quotas are the most common. You can limit the total of requested processor power, the total of requested memory, the total of processor limits and the total of memory limits. Some clusters also limit temporary disk space used by pods. Together, these stop a namespace from claiming an unfair share of the machines.

Storage quotas in detail

Storage quotas limit how much persistent disk space a namespace may request in total, and how many storage claims it may create. Administrators can go further and set different limits for each storage class, for example allowing plenty of standard storage but very little of the expensive fast kind.

Object count quotas in detail

Object counts protect the cluster’s central database and its network resources. You can limit the number of pods, services, secrets and settings objects. You can even limit special kinds of services that create costly cloud load balancers, or that reserve a port on every node.

Let us follow one request to create a pod through the quota check.

Step one: the request arrives

Someone, or some controller, asks the API server to create a pod in a namespace. The server checks who is asking and whether they have permission. If so, the request continues to a stage called admission, where a series of checks and adjustments happen before anything is stored.

Step two: the quota check

One of the admission steps is the quota check. The server looks up the quota objects in that namespace, reads how much has already been used, and adds what the new pod would need. If the sum stays within every limit, the request passes. If any limit would be exceeded, the request is rejected at once with a message saying which limit was hit.

Step three: usage is recorded

When a request is accepted, the server updates the recorded usage of the quota. A background controller also recalculates usage regularly, to fix any drift, and to account for resources being deleted or finishing their work.

sequenceDiagram
    participant U as User or Controller
    participant API as API Server
    participant Q as Quota check in admission
    participant DB as Cluster database
    U->>API: Create a pod in a namespace
    API->>API: Authenticate and authorise
    API->>Q: Would this fit within the namespace quota?
    Q->>Q: Current usage plus new request compared with limits
    alt Within all limits
        Q-->>API: Allowed
        API->>DB: Store pod and update recorded usage
        API-->>U: Created
    else Any limit exceeded
        Q-->>API: Denied
        API-->>U: Forbidden, exceeded quota
    end
        

The behaviour differs depending on who is creating the object, and this surprises many beginners.

Creating a pod directly

If a person creates a pod directly and the quota is exceeded, the command fails on the spot with a clear “forbidden” message naming the exceeded quota. This is easy to see and understand.

Creating through a Deployment

Most applications are created through a Deployment. The Deployment itself is accepted, because a Deployment is only a description, and does not count as a pod. The trouble appears later, when the Deployment’s helper, the ReplicaSet, tries to create the pods and the quota check rejects them. The Deployment exists, but fewer pods than expected are running, and the reason appears only in the events of the ReplicaSet.

flowchart TD
    A["Create a Deployment"] --> B["Deployment accepted and stored"]
    B --> C["ReplicaSet tries to create pods"]
    C --> D{"Quota check"}
    D -- "Within limits" --> E["Pods created and running"]
    D -- "Exceeded" --> F["Pod creation refused"]
    F --> G["Deployment shows fewer ready pods"]
    G --> H["Reason appears in ReplicaSet events"]
        

The declared-requests rule

If a namespace has a quota on requests or limits, then every new pod must state its own requests and limits. A pod that says nothing is refused, because the quota cannot count what is not declared. This rule surprises many teams the first time a quota is applied to an existing namespace.

A quota limits the namespace as a whole. A limit range shapes the individual containers inside it.

A limit range is another namespace-level object. Where a quota sets a ceiling on totals, a limit range sets rules for each individual pod or container. It can set minimum and maximum sizes, and it can supply default requests and limits for containers that do not declare their own.

Sometimes you want a quota to apply only to certain kinds of pods. Scopes make that possible.

A scope narrows a quota so that it counts only the pods matching a certain condition. This lets you build several quotas in one namespace, each governing a different category of workload.

flowchart LR
    NS["One namespace"] --> Q1["Quota A: long-running services"]
    NS --> Q2["Quota B: short-lived batch jobs"]
    NS --> Q3["Quota C: high-priority pods"]
    Q1 --> R1["Counts only matching pods"]
    Q2 --> R2["Counts only matching pods"]
    Q3 --> R3["Counts only matching pods"]
        

One of the most misunderstood facts about quotas.

A quota says “this namespace may use up to this much”. It does not say “this namespace will always have this much available”. Quotas are ceilings, not reservations. The cluster still has a finite amount of real capacity, and quotas do not create more.

In fact, the sum of all namespace quotas is often larger than the cluster’s real capacity, on purpose. Administrators assume that not all teams will use their full share at the same moment, so they allow the total of the ceilings to exceed the real capacity. This is called overcommitting, and it is the reason a pod can be refused by the scheduler even when the namespace is well within its quota.

flowchart TD
    A["Pod creation request"] --> B{"Quota check: within namespace ceiling?"}
    B -- "No" --> X["Refused by quota"]
    B -- "Yes" --> C["Pod accepted"]
    C --> D{"Scheduler: is there real free room on a node?"}
    D -- "No" --> W["Pod waits as pending"]
    D -- "Yes" --> R["Pod runs"]
        

Quotas are set up, watched, adjusted and eventually retired. Good teams plan each stage.

Many organisations do the first three stages well and forget the last three. Over time, quotas set years ago no longer match reality: some are far too large and waste capacity, others are too small and quietly slow teams down.

Choosing numbers is part science and part conversation.

Start from real usage

The best starting point is what teams actually use today. Look at their current totals of requests and limits, add reasonable headroom for growth and spikes, and use that as the first quota. Guessing without data leads to quotas that are either uselessly large or painfully small.

Leave room for rolling updates

When an application is updated, Kubernetes often starts new pods before stopping old ones. During that period, the namespace briefly uses more resources than usual. A quota set exactly at the steady-state usage will block updates. Always leave headroom, often thirty to fifty percent, for such surges.

Use tiers instead of custom numbers

Rather than inventing a unique quota for every team, offer a small menu of sizes. It makes requests simpler, keeps the platform easy to manage and makes fairness easier to explain.

Quotas are not just about fairness. They are also a safety mechanism.

Defence against runaway or malicious usage

If an attacker gains access to one namespace, they may try to launch huge numbers of pods, for example to mine cryptocurrency at your expense. A quota puts a hard ceiling on the damage they can do from that namespace. It is not a full defence, but it limits the blast radius and the bill.

Protecting the control plane

Object count quotas protect the cluster’s central database and the API server from being flooded. Limiting the number of settings objects, secrets and pods per namespace stops any single team from slowing the control plane for everyone.

Who may change quotas

If teams can edit their own quotas, the quotas mean nothing. Only platform administrators should be allowed to create, edit or delete quota objects. Role-based access control handles this: ordinary users receive read access to see their usage but no permission to change it.

Guarding against quota bypass

A team that can create new namespaces freely can simply make another namespace with its own fresh quota. Restrict namespace creation to administrators or an automated process that assigns a quota to every new namespace, so nobody escapes the rules by moving house.

flowchart TD
    A["Administrators own quota objects"] --> B["Namespaces created only through a controlled process"]
    B --> C["Every namespace receives a quota and a limit range"]
    C --> D["Teams have read-only access to quota status"]
    D --> E["Alerts warn when usage nears the ceiling"]
    E --> F["Changes to quotas are reviewed and audited"]
        

A quota that nobody watches is a trap waiting to spring.

Reading the quota’s own report

Every quota records two sets of numbers: the hard limits that were set, and the amounts currently used. Describing the quota object shows both side by side, which makes it easy to see which resource is close to its ceiling.

What to watch

Common problems and their usual causes

Patterns are proven habits. Anti-patterns are popular mistakes that keep costing teams.

Patterns worth adopting

Anti-patterns to avoid

An honest look at what quotas give you, and what they cost.

The lesson is that quotas bring order and predictability at the cost of some rigidity. A quota that is well sized and well watched is invisible. A quota that is set carelessly becomes a daily source of friction.

A checklist of habits that separate smooth clusters from frustrating ones.

Best practices

• Give every namespace a quota — no exceptions for test or tooling namespaces.
• Pair quotas with limit ranges — so containers get sensible defaults and are never refused for missing declarations.
• Size from real data — base numbers on observed usage plus headroom, not on guesses.
• Leave room for updates — rolling updates need temporary extra capacity.
• Limit costly objects — cap load balancer services, storage claims and expensive storage classes.
• Protect the control plane — cap object counts such as secrets, settings and pods.
• Alert before the ceiling — warn teams at around eighty percent so they can act calmly.
• Review regularly — adjust quotas as teams grow, shrink or retire.

Common mistakes

How quotas show up in everyday engineering.

A resource quota limits the total consumption of a whole namespace. A limit range sets rules for individual pods and containers, such as defaults, minimums and maximums. They work best together.

No. A quota is only a ceiling. The cluster’s real capacity is separate, and total quotas often exceed it on purpose. A pod can be within quota and still wait because no node has room.

When a namespace has a quota on those values, every pod must state them so the quota can count them. A limit range can supply defaults automatically so that pods are not refused.

The Deployment was accepted, but its ReplicaSet may be unable to create pods because the quota was exceeded. Check the ReplicaSet events and the quota’s used versus hard values.

Nothing. Existing pods keep running. The lower limit only blocks new creations until usage falls below the new ceiling.

Yes. This is common with scopes. A request must satisfy all of them, so the strictest one decides.

No. Each quota applies to a single namespace. Cluster-wide fairness comes from having a suitable quota in every namespace and watching the overall total.

Yes. They can cap total requested storage, the number of storage claims, and even the amount per storage class, which is useful for controlling costly fast disks.

During an update, new pods may start before old ones stop, temporarily needing extra capacity. If the quota has no headroom, the new pods are refused and the update stalls.

Measure current usage, add a limit range with sensible defaults, and then apply quotas with generous headroom. Set up alerts at around eighty percent before you tighten anything.

A resource quota is a namespace-level ceiling on how much of a shared cluster a team may use. It can cap compute, storage and the number of objects, and it is enforced at the front door: when a request would push the total past the limit, the API server refuses it with a clear message. Quotas work best alongside limit ranges, which give each container sensible defaults and sizes, and scopes let you divide a namespace’s budget between different kinds of workloads.

Remember that a quota is a promise of fairness, not of capacity, and that the scheduler still needs real room on a real node. Give every namespace a quota, size from real data with headroom, watch usage before the ceiling is reached, and let only administrators change the limits. Do that, and a shared cluster becomes a calm, fair and predictable place to work.