Lesson 1

One route set, three different answers

Envoy, Kong and OpenResty all take a list of routes and pick one per request. It sounds like the same job, but the three define “matches” differently and order their priorities differently. This lesson builds one set of five routes on all three, sends the same seven paths through, and records which route wins.

The rig

Four containers on one Docker network. The backend is an nginx that echoes the path it received, so every route is configured to rewrite the path into its own marker — reading the response tells you which route won.

server {
  listen 8080;
  default_type text/plain;
  location / { return 200 "$request_uri\n"; }
}

All three gateways get the same five routes:

Kong has no notion of an exact match, so r2 on Kong is a regex anchored at both ends. Versions measured: Envoy 1.31.10, Kong 3.9.3 running DB-less, OpenResty 1.31.1.1.

“Regex” means three different things

Before priority order there is a deeper difference: the same pattern string does not match the same set of paths. Measured with a single regex route /b$ plus a catch-all:

Those six rows are enough to read off three rules:

• Envoy — safe_regex must match the whole path. The pattern /b does not match /b/c.
• Kong — the pattern after ~ is anchored at the start. /b matches /b/c but not /a/b.
• OpenResty — like nginx, the regex is searched anywhere in the path. /b$ matches /a/b too.

Envoy sorts nothing

In Envoy the winner is the first route that matches, in written order. There is no sorting step at all. Writing the same five routes in three different orders gives three quite different tables:

The second column is the worst case: writing the catch-all first makes the other four routes dead, and Envoy starts normally without a single warning. The last column is subtler: only because the prefix /a/b/c is written before the .png regex does /a/b/c/x.png end up somewhere else.

The same experiment on Kong and OpenResty: written forwards or backwards, the table is identical. Both reorder the list before serving.

How Kong and nginx sort

With the five routes above, Kong and OpenResty agree row for row:

The second-to-last row is the one worth keeping: a regex beats a prefix however long the prefix is. Measured separately on Kong with the prefix /a/b/c/d/e against the regex /a/.*\.png$: /a/b/c/d/e/x.png goes to the regex, and only /a/b/c/d/e/x.txt falls back to the prefix. nginx behaves the same, except that nginx has ^~ to suppress the regex step — Kong and Envoy have no equivalent.

Two identical routes

Write two routes with the same pattern /a, pointing at different backends:

That last row needs spelling out. Three pairs were measured: a route named k1 written before k2 gave k2; zz before aa gave zz; and reversing that to aa before zz still gave zz. So the winner follows the route name, not the written order — and nobody picks a name intending to decide priority with it. Only nginx refuses to start; the other two quietly choose one.

The lab

Type your own routes and the paths you want to try, then watch the three gateways answer. Any row where they disagree is highlighted. The algorithms are rewrites of all three and match 74 of 74 curl results from the rig above.

Takeaways

• “Regex” is three different things: Envoy matches the whole path, Kong anchors at the start, nginx searches anywhere.
• Envoy takes the first match in written order; Kong and nginx reorder, so written order does not matter to them.
• On Kong and nginx a regex beats a prefix, however long the prefix is.
• Between two regexes of equal regex_priority, Kong's choice cannot be derived — set regex_priority explicitly.
• Two routes with the same pattern: nginx refuses to start, Envoy serves the first written, Kong serves one chosen by name.

The next lesson asks the other half of the question: once a route has been chosen, what does the backend actually receive.