How G8 handles a request
A request your clients send passes through a few objects you create in the console: the environment's address, a route, the plugins that act on it, often a consumer with its credential, and the target that holds your backend. This page follows one request of the orders API through them and links each object's own page.
G8 is the console and the server behind it. It writes the routes, plugins and consumers you save to each environment's gateway cluster through the cluster's administration interface. Your clients' requests go to the gateway nodes of the cluster, not to G8.
The address: an environment's Gateway URL
An environment is one gateway cluster that G8 manages, Development or Production for example; see Environments. Its Gateway URL is the address your clients call, and its host name is the gateway host. Once an administrator has set it, the Overview of every route shows it under Address, followed by each of the route's paths, with Copy address beside each line. Without it, routes show no address.
Everything you open in the console belongs to the environment chosen in the switcher. Every change you save goes to that environment's gateway cluster and to no other.
The route: which requests the gateway takes
A route says which requests the gateway takes and where it sends them. A request is taken by a route when every rule under Matching holds. Its path is one of the route's Paths. Its method is one of the Methods, or any method when none is checked. Its host is one of the Hosts, or any host when the list is empty. Its client address is one of the Client addresses, or any address when the list is empty; behind a load balancer, that is the load balancer's address. Rules on a header, a query argument or a cookie go under Conditions; see Conditions on request variables.
A trailing * in a path takes everything under the path but not the path itself. A route for /orders and everything under it therefore lists two paths, /orders and /orders/*. With /orders/* alone, the route does not take a request to /orders.
When more than one route holds, the gateway decides in this order:
- A route that lists hosts comes before one that does not. Among those, a route that names the request's host exactly comes before one that matches it through a leading
*. - Then a route whose path is the request path exactly comes before one with a trailing
*, and a longer path before a shorter one. - Only among routes on the same path that name the host the same way does the higher Priority go first.
- A route whose other rules fail, its methods for example, is passed over for the next.
A request that no route takes is answered 404 by the gateway itself.
The plugins: what happens to a request the route took
A plugin acts on the requests that reach it. key-auth asks for an API key, limit-count counts requests, proxy-rewrite changes the path your backend receives. A plugin lives on the object it was added to, in that object's Plugins tab, and that object decides which requests it acts on: a route, a service, a plugin config, a global rule, a consumer or a consumer group. Where a plugin runs explains each and says which copy wins when two carry the same plugin.
The plugins of the route, its service, its plugin config and its consumer run as one list, ordered by priority: a higher number runs earlier. Each plugin page states its priority. The gateway works through a request in phases, stages of its work that follow each other, the rewrite phase before the access phase for example. Priority orders plugins within one phase only, and a plugin of an earlier phase runs first. A plugin's priority has nothing to do with a route's Priority, which only orders routes. A global rule's plugins run before the route's plugins of the same phase, whatever their priority. The route itself is chosen before any plugin runs. A route's Plugins tab shows the list for that route under Request path.
On a route that carries key-auth together with consumer-restriction, acl or a limit-count whose key is consumer_name, key-auth names the caller first. The others then let it through, refuse it or count it under that name.
Who is calling: consumers and credentials
A consumer is one client of your APIs, the mobile app for example, and its credentials are the keys or passwords it signs in with. key-auth on the route finds the credential that holds the key a request carries. From then on the request belongs to that consumer: your backend receives its username in X-Consumer-Username, and the consumer's own plugins join the list. A request with no key, or with a key no credential holds, is answered 401 by key-auth.
Authentication explains consumers, credentials and consumer groups one by one.
The backend: upstream, service or nodes on the route
Under Target a route says where the requests it takes are sent:
- Upstream: a shared upstream, which several routes can name.
- Service: a service, whose upstream and plugins the route inherits.
- Nodes on this route: nodes listed on the route itself and shared with nothing.
- None: no backend; the route serves its plugins alone.
Each node is a host and a port with a Weight. Nodes with the same weight share the traffic: repeated requests to the orders route are answered by both of its backend nodes. A node with weight 0 stays in the list and receives no traffic. While one of two backend nodes is stopped, requests are still answered by the other: a request the stopped node refuses is tried on the other one.
A backend that has not answered within the route's Read timeout is given up on. A GET then goes to the next node when there is one, a POST is not sent again, and the gateway answers the client 504 once no node has answered in time. Without an Active health check under Health checks, every node stays in rotation regardless of its state. With one, a node is taken out of rotation once its probes fail. When you run two backend nodes so that one can stop, turn the check on.
What the client gets back
Most answers come from your backend. These are the ones the gateway or one of its plugins gives itself. Each plugin page lists its own under What you will see.
| Answer | Given by | When |
|---|---|---|
| 401 | key-auth | The request carries no key, or a key no credential holds. |
| 403 | consumer-restriction or acl | The consumer is known but not allowed on this route. |
| 404 | the gateway | No route takes the request. |
| 429, or 503 when no code is set | limit-count | The request is over the count; the code is the Rejected code you set. |
| 504 | the gateway | The chosen node did not answer within the route's Read timeout. Analytics counts it under Unreachable, because no node answered. |
Related
- Where a plugin runs: which object a plugin sits on, and which copy wins.
- Authentication: consumers and credentials, consumer groups included.
- Where the numbers come from: how the answers are counted.
- Route and Route requests to a backend.