Skip to main content

Words these pages use

These pages assume you know web services and what an API gateway does. The words below are the ones G8 gives its own objects and pages. Each entry says what the word means here and links the page that explains it. What G8 is shows how the pieces fit together.

Where things run​

Environment​

One gateway cluster that G8 manages, Development or Production for example; one installation manages several. Everything you open in the console belongs to the environment chosen in the switcher, and every change you save goes to that environment alone. See Environments.

Gateway host​

The host name of the gateway, the address your clients call, api.example.com in these pages' examples. In the console it is the first part of the Address line on a route's Overview tab. HTTPS answers on the gateway's port 9443 until whoever runs the gateway publishes HTTPS on 443. Plain HTTP answers on the gateway's HTTP port. See What G8 is.

Address line​

The Address line on a route's Overview tab. It shows the environment's Gateway URL followed by each of the route's paths, with Copy address beside each one. Its first part is the gateway host. Without a Gateway URL, routes show no address. See How G8 handles a request.

Gateway URL​

The setting of an environment that holds the address clients call, Gateway URL in the environment's settings. The hint under it says: The address API consumers call. Shown on every route and checked by the connection test. A Platform administrator sets it, and the Address line of every route is built from it. See Environment settings.

Engine​

The console and the reference pages call the gateway software the engine, as on the Engine card of the Overview. These pages say the gateway. See What G8 is.

Gateway node​

One machine or container of the environment's gateway cluster. Your clients' requests go to the gateway nodes, which run your routes and plugins, and Analytics shows each gateway node with its share of the requests. See How G8 handles a request and Analytics.

Data plane​

The gateway nodes as your clients reach them, at the Gateway URL, as opposed to the Admin API. The connection test of an environment's settings checks both, and shows the clients' side as Data plane. See Add an environment.

Admin API​

The gateway's administration interface, where G8 reads and writes the gateway's objects. The console and the installation guides call it the Admin API. An environment's settings hold its address as Admin API URL, with the admin key beside it. See Install G8 and a gateway cluster.

Admin key​

The key G8 sends to the Admin API of an environment's gateway with every read and write. The hint under the field says: Sent as X-API-KEY. Stored sealed; not shown again after you save. See The admin key and the other secrets.

Slug​

The short name of an environment, dev for example, set when it is created. The hint under the field says: 3–32 lowercase letters, digits and hyphens. Part of every address and cannot change once created. The addresses it is part of are those of the environment's pages in the console and of the server's API calls for it. G8 also builds the names of the environment's data in the shared stores from it. See The slug.

Protected environment​

An environment marked protected in its settings. The setting is described in these words: Destructive actions in this environment ask for the resource name before they run. Nothing else changes. A protected environment also cannot be removed until it is unprotected. See Environment settings.

Setup token​

A token the server prints in its log at its first start, while G8 has no users. You type it in the console once, to create the first Platform administrator, and it is used up. See Install G8 itself.

Log store​

The Elasticsearch or OpenSearch where the gateway writes an environment's request records, and where G8 reads them. Several environments can share one. See Where request records go.

Ingest pipeline and index template​

Two things G8 ships for the log store, both named g8-access, which the installation guides apply. The ingest pipeline sets each record's id to its request id, so a record delivered twice is stored once. The index template says how each field of a record is stored and searched, and sends every record through the pipeline. See What G8 ships to the store.

Prometheus label​

The label that marks an environment's numbers in Prometheus, g8_environment="dev" for the slug dev. G8 reads each environment's numbers only under its own label. See Where the numbers come from.

What you create​

Route​

Says which requests the gateway takes, by path, method and host, and where it sends them. The orders API's route orders-api takes /orders and everything under it. See Route and Route requests to a backend.

Target​

The Target section of a route, which says where the requests the route takes are sent. It names an upstream or a service, lists nodes on the route itself, or names no backend. See How G8 handles a request.

Priority​

Two different numbers carry this name. A route's Priority orders the routes that share a path and a host, and the higher one is tried first. A plugin's priority orders the plugins of one phase, and the higher one runs earlier. See How G8 handles a request.

Service​

Holds the upstream and the plugins that several routes share. A route on a service takes both from it and can add plugins of its own. See Service.

Upstream and node​

An upstream is a backend that routes and services send requests to, written once and shared. Each of its nodes is one backend node, a host and port with a weight, 10.0.1.10:8080 for example. See Upstream and Share a backend between routes.

Consumer​

One client of your APIs, known to the gateway by its username, mobile-app for example. Its credentials live under it. See Authentication.

Credential​

What a consumer signs in with. A key-auth credential holds a key, a basic-auth credential a username and password. Each credential belongs to one consumer, and a consumer can hold several. See Authentication.

Consumer group​

A named set of consumers that share the plugins the group carries, a limit for the group partners for example. A consumer belongs to at most one group, chosen on the consumer. See Authentication.

Plugin​

What happens to a request on its way: a key check, a limit, a rewrite, a record. You add a plugin to an object that carries plugins, a route or a global rule for example. HTTP plugins act on HTTP requests. Stream plugins act on the connections of stream routes, and an HTTP plugin is refused there. See Plugins and Where a plugin runs.

Phase​

One stage of the gateway's work on a request, the rewrite phase before the access phase for example. A plugin runs in the phases it needs, and a plugin of an earlier phase runs first whatever its priority. See Where a plugin runs.

Global rule​

Plugins that run on every request of the environment, whatever the route. No global rule runs on a stream route. See Global rule and Apply a plugin to every request.

Plugin config​

A named set of plugins that several routes refer to. It carries no target, the part of a route that says where requests go, so each route that names it keeps its own upstream, service or nodes. See Plugin config and Share plugins between routes.

Environment-wide settings​

Settings of one plugin shared by every use of that plugin in the environment, edited on the plugin's page. A plugin that has them keeps one document of them per environment, which every route, service, plugin config and global rule that runs the plugin reads. This is the console's name; the API calls them plugin metadata. See Environment-wide settings.

Cost decoration​

A weight on one field or type of the GraphQL schema a service fronts, stored under that service. The graphql-limit-count plugin reads the weights. See Cost decoration.

Stream route​

Forwards plain TCP or UDP connections that arrive at one port of the gateway to an upstream, with no HTTP in between. See Forward a TCP port.

Certificate​

Lets the gateway serve HTTPS for the host names the certificate covers. See Serve HTTPS with your certificate.

Secret​

Tells the gateway where a secret manager, Vault for example, keeps values that plugins refer to, so the value itself is not written into the plugin. Resource kinds lists the secret managers, and Environments explains what each environment keeps.

Seeing what happened​

Request records​

A record of each request the gateway handled: what came in, what went out and how long it took. The gateway writes them to the environment's log store. See Where request records go.

Logger​

A plugin that sends a record of each request somewhere, elasticsearch-logger or kafka-logger for example. Without a name, the logger on these pages is the copy of elasticsearch-logger on the global rule g8-request-records, which G8 writes when logging is turned on. See The rule G8 writes.

Traffic Explorer​

The console page that lists the request records of an environment, under Traffic Explorer in the menu. See Request records.

Analytics​

Request counts and response times, read from the environment's Prometheus rather than from the request records. See Where the numbers come from.

Audit log​

Every change made through G8, with who made it, to which object and with what result, and the sign-ins. See Audit log and How the console writes to the gateway.

Channel and system alert​

A channel is where an alert's notifications go, a mail list or a webhook. A system alert watches the environment's setup rather than its traffic, a gateway that stops answering or a failed cleanup of request records for example. It needs no rule of your own. See Alerts.

Hold​

How long an alert rule's condition has to hold before the rule fires, and how long it has to clear before the rule resolves. See Alerts.

Episode​

One stretch of an alert rule's firing, listed on the History tab of Alerts. The tab explains it in these words: An episode starts when a rule fires and ends when the condition clears or the rule is changed, disabled or deleted. Episodes are kept for 90 days after they end. See Alerts.

Mail relay​

The mail server an environment's alerts are sent through, set on the Alerts page. Its password is sealed. See Alerts.

Working in the console​

Raw JSON​

A tab on an object's page that shows the whole object as the gateway stores it, as JSON you can edit. It is checked against the gateway's schema as you type. See Raw JSON and copy to environment.

Copy to environment​

Copy to environment… in an object's menu brings the object into another environment through that environment's Raw JSON tab. Nothing is written until you save there. See Copy an object to another environment.

Sealed​

Stored encrypted with the server's own key, G8_SECRETS_KEY, and never shown again. The admin key, the log store password, the directory's bind password, the mail relay password and the signing keys of webhooks are kept sealed. See The admin key and the other secrets.

Masked​

Shown or stored with its secret value replaced. A role that cannot manage an object sees its keys and passwords as ••••, the audit log masks them, and request records carry ******** in place of the values the masking settings name. See What a role sees masked.

Roles​

What a person may do, given in one environment or in all of them. Four are built in. A Viewer reads and changes nothing, with Raw JSON locked. An Editor manages routes, services, upstreams, consumers with their credentials, consumer groups, global rules, plugin configs, Environment-wide settings and stream routes, and adds plugins to them. The plugin catalog is read-only for an Editor as for every role, and certificates and secrets are read without being changed. An Environment administrator does everything in an environment, its audit log included. A Platform administrator does everything everywhere. See Users, roles and access and Custom roles.

Permission and custom role​

A permission pairs a kind of thing with view or manage, routes.manage for example; manage includes view. A custom role is a set of environment permissions you choose, beside the four built-in roles. See Custom roles.

Service account and token​

The console describes it in these words: Service accounts let CI pipelines and scripts call the API with a token instead of a person's session. A service account holds environment roles the way a person does, and each of its tokens acts with those roles. See Service accounts and the API.

Configuration store​

The store beside the gateway nodes that holds everything the console writes to an environment: routes, services, upstreams, consumers, plugins and certificates. Every node reads it and keeps serving from what it read. The cluster's installation guide installs and backs it up; see How an installation is laid out.

Engine​

The console's word for the gateway product behind an environment. Its name and version are shown under the environment's engine section and in the connection test; the pages of this site say "the gateway".

Unverified​

The mark the console puts on an environment whose gateway runs a version other than the one this release of G8 was verified against. Reading and writing continue; the forms are the verified version's. The switcher and the environment list carry it as Unverified.

Observe​

The part of the console's menu, Observe, that holds the request records, Analytics and Alerts of an environment. The Environment administrator sees it; the Editor and the Viewer do not.

Proto​

A protocol buffer definition stored on the gateway so a route can translate between gRPC and HTTP. One of the resource kinds; see Proto.

Installation guides​

The section of this site under Install: one guide per platform for the gateway cluster and the stores beside it, each saying what was run and marking what was not. G8 itself is installed as Install G8 on OKD or OpenShift describes.

G8 dev