RGW quotas: user, bucket, and defaults

Intermediate⏱ ~16 minradosgw-admin

What you'll learn

Set user, bucket, and default quotas
Explain the enforcement mechanism and its lag
Monitor quota consumption
Design a quota policy for a multi-tenant service

Prerequisites

None — start here.

Verified against Ceph Tentacle 20.2.x · Ceph Squid 19.2.x (supported previous) · cephadm matches the verified Ceph release · podman 4.x · csi-rbd and csi-cephfs current · RBD / CephFS / RGW current (matches Ceph release) · Linux kernel 5.15+ (5.10 minimum) · Ubuntu 24.04 LTS (Ceph host baseline) · Debian 12 (Bookworm) (Ceph host baseline) · Rocky Linux / RHEL / AlmaLinux 9.x (Ceph host baseline) · Proxmox VE 9.x (cross-course integration) · Kubernetes 1.31+ (cross-course integration) · 2026-08-18

Why this matters in production

Quotas are what stop one customer consuming the capacity you sold to everyone else. They work, and they work approximately — understanding the approximation is what lets you set them at values that hold rather than values that are exceeded.

The three levels

User quota — total across all of a user’s buckets:

radosgw-admin quota set --uid=alice --quota-scope=user \
    --max-size=10T --max-objects=5000000
radosgw-admin quota enable --uid=alice --quota-scope=user

Bucket quota — per individual bucket:

radosgw-admin quota set --uid=alice --bucket=logs --quota-scope=bucket \
    --max-size=2T
radosgw-admin quota enable --uid=alice --bucket=logs --quota-scope=bucket

Defaults — applied to users and buckets created afterwards:

radosgw-admin global quota set --quota-scope=user --max-size=1T
radosgw-admin global quota enable --quota-scope=user

Defaults matter: without them, a new user is unlimited until someone remembers to set a quota, and that gap is where capacity incidents come from.

Checking

radosgw-admin quota show --uid=alice --quota-scope=user
radosgw-admin user stats --uid=alice --sync-stats
radosgw-admin bucket stats --bucket=logs

--sync-stats forces a recalculation from the bucket index. Without it, the figures are whatever the cached statistics say, which is the source of the lag described below.

The lag, and the overshoot

RGW checks quota against cached usage statistics that are updated asynchronously. The consequence:

A user can exceed their quota before the gateway notices
The overshoot is proportional to the write rate and the update interval
Multiple gateways each hold their own cached view, so parallel uploads across gateways can each be under the cached limit while their sum is over

ceph config get client.rgw rgw_bucket_quota_ttl
ceph config get client.rgw rgw_user_quota_bucket_sync_interval

Lowering these tightens enforcement at the cost of more metadata traffic.

Designing a policy

Set a global default so nothing is unlimited by accident
Set user quotas as the contractual limit
Set bucket quotas only where a specific bucket needs bounding
Leave headroom in your capacity plan for the overshoot
Alert before the quota, at perhaps 80%, so the customer can act

Quiz

Knowledge check · 4 questions

Q1. Why can an RGW user exceed their quota before writes are refused?

Quotas in RGW are advisory, and are enforced only when a bucket policy explicitly references the quota condition key The monitors override RGW quotas as soon as the data pool passes its own nearfull ratio, letting the writes continue Only bucket quotas are enforced by the gateway; user quotas are recorded for reporting and never block a write Enforcement uses cached usage statistics refreshed on a timer, so there is a window before the gateway notices
Q2. The quotas you issue can add up to more than the cluster can hold, and nothing in RGW or Ceph will say so.

True False
Q3. Design a quota policy for a new object service.

A new S3 service will host 40 external customers on a cluster with 400 TB of usable capacity after EC overhead and fill headroom. Contracts specify per-customer capacity. Several customers will run high-rate ingest pipelines.
Q4. What is the cost of lowering the quota refresh interval to tighten enforcement?

Passing score: 75%. Answers are checked in this browser.

Production discipline

Set a global default quota before onboarding anyone, so the unlimited-by-default gap never exists. Track the sum of issued quotas against usable capacity as an explicit planning metric, and communicate to customers that enforcement permits a small overshoot so it is not reported as a fault.

Cross-course references

Kubernetes: ResourceQuota admission has similar eventual-consistency characteristics
Linux: filesystem quotas with grace periods behave the same way for the same reasons