ENGINEERING NOTES / API GATEWAYS
Introducing Tollgate: API Keys, Quotas and Cluster-Wide Rate Limits for KrakenD CE
KrakenD CE counts rate limits per node and has no API keys, plans or quotas. Tollgate is our CE 2.13 plugin that adds them, with Valkey as shared state.

KrakenD Community Edition can rate-limit an endpoint, but each gateway node counts only its own traffic and the counters reset on every deploy. CE also has no API key store, no plans and no usage quotas. Tollgate is a plugin for KrakenD CE that fills those gaps. It adds hashed API keys managed at runtime, plans with rate limits and daily or monthly quotas, and rate and concurrency limits that hold across every gateway node, because a shared Valkey makes the decisions.
CloudGuys builds and licenses Tollgate, so read this as a product introduction. What I say about Tollgate comes from its source code, documentation and load-test results. What I say about KrakenD links to KrakenD’s own documentation, checked on 8 November 2026.
The short answer
- You run one KrakenD node and only need a crude per-IP limit: KrakenD CE’s built-in rate limit is enough. You do not need Tollgate.
- You run several KrakenD CE nodes and a limit must mean the same thing on all of them: Tollgate evaluates every limit atomically in Valkey, so ten nodes enforce one budget, not ten.
- You sell or meter API access and need per-customer keys, plans and quotas on CE: that is the gap Tollgate was built for.
- You are on KrakenD CE 3.x: Tollgate will not load. KrakenD removed Go plugin support from CE in 3.0, so Tollgate runs on the CE 2.13 line.
- You want to try it first: build and check a full configuration in the free Tollgate config studio. Running the plugin needs a licence.
What does KrakenD CE leave out?
KrakenD CE’s rate limits are local to each node and are not persisted. The CE rate-limit documentation says the limiter stores “the counters in-memory. On a cluster, each machine sees and counts only its passing traffic,” and that “the counters reset every time you deploy the configuration.”
Two things follow. A limit of 100 requests a minute behind four nodes and a round-robin load balancer is really about 400 a minute. And a daily or monthly allowance is impractical, because every deploy resets the count.
Identity is the second gap. The CE authorization documentation covers JWT validation and signing and mutual TLS. It does not list API key authentication, and CE documents no plans or usage quotas. If you sell API access by key and tier, CE gives you nothing to hang the key, the tier or the allowance on.
That is not a flaw in CE. It is a fast, stateless gateway, and per-node limits are the natural default for one. Shared limits need shared state, and that is the part Tollgate adds.
What Tollgate adds
Tollgate is a KrakenD HTTP server plugin: a Go .so file that KrakenD loads at startup and runs in front of its router. Each stage is optional and has its own configuration block. Here they are, grouped by job:
| Group | Feature | What it does |
|---|---|---|
| Identity | API keys | Keys stored as SHA-256 hashes in Valkey, issued, re-planned and revoked at runtime with tollgatectl, no redeploy |
| Identity | Plans | Per-plan rate limits, per-route overrides, daily and monthly quotas, concurrency caps |
| Identity | Client identity | API key ID, a named header, X-Forwarded-For counted from the right past N trusted proxies, or the remote address |
| Limits | Rate limits | Token bucket or sliding window per policy, evaluated atomically in Valkey |
| Limits | Quotas | Daily and monthly counters per UTC calendar period, checked and consumed in one script |
| Limits | Concurrency | Caps in-flight requests per client across every node |
| Limits | Body limit | Rejects oversized bodies with 413 |
| Protection | IP filter | Static allow and deny lists, a cluster-wide Valkey blocklist, and auto-ban of clients that keep hitting limits |
| Protection | Geo-IP | Allow or deny by country and ASN from GeoLite2 or GeoIP2 databases |
| Protection | Maintenance switch | Puts routes into maintenance from tollgatectl, no redeploy |
| Operations | Audit log | One JSON line per request with identity, decision and outcome |
| Operations | Request IDs | Correlation IDs on requests, responses, rejections and logs |
| Operations | Metrics and health | Prometheus /metrics and /healthz on a separate admin port |
| Operations | Resilience | Per-policy fail-open or fail-closed, a circuit breaker and a local deny cache |
Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Reset and, on a denial, Retry-After.
One identity detail deserves a closer look. The leftmost X-Forwarded-For entry is written by the client, so anyone can claim a fresh IP on every request and get a fresh bucket. Tollgate’s forwarded-for:N source counts N entries from the right instead, which gives you the address your outermost trusted proxy saw. We covered the same problem from the other side in finding the real client IP behind an Istio ambient gateway.
How does a request move through Tollgate?
Each request passes the stages in a fixed order, outermost first:
Maintenance windows, the IP filter and the blocklist sit in memory and sync from Valkey in the background, so they cost no round trip. Each node caches API key lookups for 30 seconds by default. The rate limit, quota and concurrency stages each run one Lua script in Valkey. Quota runs only after the rate limit has allowed the request, so throttled requests never spend quota. Concurrency runs last, so only requests that will be proxied hold a slot.
A rejection has one status code per cause: 400 for an unreadable body or a rejected path, 401 for a missing or invalid API key, 403 for the IP filter or geo-IP, 413 for the body limit, 429 for a rate limit, quota or concurrency limit, and 503 for maintenance, an invalid Tollgate config, an unreachable key store, or Valkey down on a policy set to fail closed.
Why Valkey, and why Lua scripts?
A limit that holds across nodes needs one place that decides. Tollgate makes each per-request decision with a single Lua script in Valkey, and the Valkey scripting documentation says “Valkey guarantees the script’s atomic execution.” No other command runs between the script’s read and its write, so two nodes hitting the same bucket at the same instant can never both take the last token.
The scripts also read the clock from Valkey with TIME, not from the gateway node, so clock skew between nodes cannot stretch or shrink anyone’s budget. Each rate-limit script touches one key and the quota keys share a hash tag, which keeps the scripts valid on Valkey Cluster.
What does Tollgate cost per request?
With Valkey on the same network as the gateway, rate limiting added about 19 µs per request and every feature together about 75 µs in our Go benchmarks of the real handler chain. Rate limiting makes one Valkey round trip; every feature on makes four (rate limit, quota and concurrency lease on the request path, then the lease release after the response). The API key lookup was served from the cache: 0.000 lookups per request.
These numbers come from loadtest/RESULTS.md in the Tollgate repository. I took them at commit 62ae778 on 26 October 2026, on one Apple M4 Pro machine. KrakenD 2.13.2 ran as linux/amd64 under emulation, because KrakenD’s builder only produces amd64 plugins. Two more results from the same run:
- Through KrakenD at a fixed 5,000 requests a second, rate limiting moved the median latency by +0.07 to +0.08 ms and every feature by +0.16 to +0.18 ms. Every run had zero errors and zero fail-open responses.
- Tollgate’s own Go code was about 4% of the chain’s CPU in a profile. The rest is waiting on Valkey, so the cost of a request is roughly round trips × network round-trip time + Valkey CPU time.
Do not read these as production throughput. KrakenD ran emulated and everything shared one 8-CPU VM. We will not quote gateway throughput until we have run the same test on native amd64 hardware.
Which KrakenD versions does Tollgate run on?
Tollgate runs on KrakenD CE 2.13. We build it with KrakenD’s own builder image, so the Go toolchain and shared module versions match the gateway exactly, as Go plugins require. Every KrakenD upgrade means a Tollgate rebuild.
It does not run on CE 3.x. KrakenD announced on 4 June 2026 that “Starting with version 3.0, the Community Edition of KrakenD and the Lura Project will no longer support Go plugins”, and the CE 3.0 upgrade notes confirm it. If you are planning a move to CE 3.x, Tollgate is the wrong tool, and we would rather say so here than after a call.
KrakenD CE alone or with Tollgate
The left column is from KrakenD’s CE documentation, checked 8 November 2026. We did not test CE’s own limiter beyond the baseline scenario of our load test.
| Need | KrakenD CE 2.13 on its own | KrakenD CE 2.13 with Tollgate |
|---|---|---|
| Rate limit shared across nodes | No: counters are per node, in memory | Yes: one atomic script in Valkey per decision |
| Limits survive a deploy | No: counters reset on deploy | Yes: state lives in Valkey with TTLs |
| Per-client limit | Yes: by IP, header or URL parameter | Yes: by API key ID, header, trusted X-Forwarded-For hop or remote address |
| API keys | Not documented for CE | Hashed in Valkey, managed at runtime with tollgatectl |
| Plans and quotas | Not documented for CE | Per-plan limits, daily and monthly quotas |
| Concurrency cap per client | Not documented for CE | Yes, across nodes |
| Behaviour when shared state is down | Not applicable | Per-policy fail-open or fail-closed, circuit breaker |
| Extra moving part | None | A Valkey you run next to the gateways |
| Price | Free | Commercial licence |
The last two rows are the real cost of Tollgate: another stateful service to operate, and a licence.
What does the configuration look like?
Tollgate is configured inside krakend.json, under KrakenD’s plugin/http-server block. A minimal setup with one strict policy for logins:
"plugin/http-server": {
"name": ["tollgate"],
"tollgate": {
"valkey": { "address": "valkey:6379" },
"identity": { "sources": ["forwarded-for:1", "remote-addr"] },
"defaults": { "algorithm": "token_bucket", "capacity": 20, "refill_per_sec": 5, "fail_mode": "open" },
"policies": [
{
"name": "login",
"match": { "path_prefix": "/v1/login", "method": "POST" },
"capacity": 5,
"refill_per_sec": 0.0833,
"fail_mode": "closed"
}
]
}
}
Unmatched routes share the default policy: a burst of 20, then 5 a second per client. The login policy allows a burst of 5, then one attempt every 12 seconds. If Valkey is down, it refuses logins with 503 instead of letting them through unlimited.
Tollgate validates the whole block when KrakenD starts. An invalid config does not fall back to “no plugin”. Tollgate answers every request with 503 {"error":"gateway misconfigured"} and logs why, because a gateway that silently drops its API keys and limits is worse than one that stops. That is why the config studio exists. It runs in your browser, covers every block and applies the same validation rules the plugin applies when it loads, so you can paste in the snippet above and see what it accepts before anything reaches a gateway.
How is Tollgate licensed?
Tollgate is sold under a commercial licence agreed with each customer. There is no public download or public repository, and it is not open source. The config studio is free for anyone.
The product page at /products/tollgate has the short version and will list every Tollgate guide as we publish them.
FAQ
Does Tollgate work with KrakenD CE 3.x? No. KrakenD removed Go plugin support from CE in 3.0, and Tollgate is a Go plugin. It runs on the CE 2.13 line.
Does the KrakenD CE rate limit work across several nodes? Not as one shared limit. CE counters live in each node’s memory, so a limit of 100 a minute behind four nodes is about 400 a minute.
What happens if Valkey goes down?
Each policy chooses. A fail-open policy lets requests through, a fail-closed policy answers 503, and a circuit breaker and local deny cache limit how often the gateway waits on Valkey.
Can I try the configuration before buying a licence? Yes. The config studio is free and runs in your browser. Running the plugin itself needs a licence.
Try it on your gateway
If you run KrakenD CE 2.13 and need API keys, quotas or limits that hold across every node, email [email protected] with the subject “Tollgate licence”. Tell us how many gateway nodes you run and which features you need, and we will set up an evaluation on your gateway.
BUILT AND OPERATED BY CLOUDGUYS
Tollgate: api gateway plugin
API keys, quotas and cluster-wide rate limits for KrakenD Community Edition.
A KrakenD CE plugin that adds the edge features the Community Edition lacks: hashed API keys with plans and quotas, token-bucket or sliding-window rate limits and concurrency caps that hold across every gateway node, IP and geo-IP filtering, a maintenance switch, an audit log and Prometheus metrics. Valkey keeps the shared state.
Ask about a licence ↗ About Tollgate ↗