Skip to main content

Gateway Internal Entries

An internal entry is an entry of the organization's Gateway that exists only inside a network. It has a name on the network — api.zero.internal — and leads each path to a service: /v1 to one, /v2 to another. They are the same path routes as the public Gateway, with no internet address.

Use an internal entry when several services need to look like a single API to the other projects in the network, or when callers should not depend on which service answers each path.

Before You Start​

  • The entry is created by whoever administers the organization, in Connectivity, and the organization needs a Gateway.
  • Each Gateway has one internal entry per network, and there is a limit of entries per organization.
  • The destination services must be in environments of the same network.

Step by Step​

1. Create the Entry​

In Connectivity, Internal entries, click New internal entry: pick the network and the Name on the network. The entry is born with no paths and nobody allowed to call it — until then, it answers "not found" to everything.

2. Connect Paths to Services​

In Routes, create a route choosing the internal entry as the address. As with public routes:

  • the path is a prefix (/v1 covers everything below it) or exact;
  • Strip the route prefix makes the service receive /orders when the call was to /v1/orders; without it, the service receives the whole path.

The path follows the same rules as the public route: it starts with /, has up to 256 characters, contains no .., // or *, and a prefix other than / does not end with a slash.

3. Say Who Can Call​

Under Who can call this entry, use Authorize project and pick the Calling project. It must have an environment in the same network. The permission covers the whole entry — all of its paths — and goes through the same states as a service permission.

Whoever can call the entry does not get direct access to the services behind it: it only gets there through the paths the routes open. And a direct permission on a service does not go through the entry. They are different doors, and each one is revoked on its own.

With the CLI​

zero entries create api --network payments
zero entries add-route api --service <orders-service> --path /v1 --strip-prefix
zero entries add-route api --service <billing-service> --path /v2
zero entries grant api --from <checkout-project> --wait

And the authorized project calls:

curl http://api.zero.internal/v1/orders

What the Entry Does With Each Call​

SituationResponse
Path with no route404
Path that tries to leave the route, such as /v1/../admin404 — nothing escapes the route
Headers above 60 KiB431
The service does not start answering within 15 seconds504
More than 1024 simultaneous calls to the same service503
Upgrade request to cleartext HTTP/2 (h2c)403

WebSocket and streamed responses work, with no total deadline: the 15 seconds apply until the service starts answering. A long connection with no traffic for 5 minutes is closed.

The service receives X-Forwarded-For with the caller's address, plus X-Forwarded-Host and X-Forwarded-Proto. Forwarding and identity headers sent by the caller — Forwarded, X-Real-IP, the X-Forwarded-* — are dropped before reaching the service: it never receives a forged origin.

Revoking, Removing a Path, Deleting the Entry​

  • Revoking an entry permission blocks new calls and closes the long connections of everyone calling the entry, not only those of the revoked project. Those still authorized reconnect.
  • Removing a path makes callers of it receive 404, and the connections opened through it are closed when the platform applies the change.
  • Deleting the entry removes the paths, revokes the permissions, and releases the name on the network.

Limits​

  • HTTP only, without TLS, and only inside the network.
  • No route policy: API keys, JWT, rate limiting and CORS belong to the public Gateway. Whoever has permission on the entry calls any path the routes open.
  • Long connections may be closed when the platform is updated. Callers should know how to reconnect.

Common Errors​

SymptomCauseWhat to do
"This gateway already has an internal entry in this network"Each Gateway has one entry per networkAdd paths to the existing entry
"The organization has reached the limit of internal entries"The organization's limit was reachedRemove an entry that is no longer used
"That name is already in use"A service or another entry in the network uses the namePick another name
"This project can already call the internal entry"The permission already existsThere is no need to create another
"Internal entries cannot be created right now"The capability is not available in this installationThe action belongs to whoever administers the platform
404 on every pathThe entry has no route yetCreate a route in Routes, choosing the entry as the address
The connection does not completeThe calling project has no permission on the entryAsk for the project to be authorized under Who can call this entry

Next Steps​