The two top-level concepts in Gloo are Virtual Services and Upstreams.


Gateway definitions set up the protocols and ports on which Gloo listens for traffic. For example, by default Gloo will have a gateway configured for HTTP and HTTPS traffic:

$  kubectl get gateway -n gloo-system 

NAME          AGE
gateway       2m
gateway-ssl   2m

A single gateway definition looks like the following:

kind: Gateway
    origin: default
  name: gateway-ssl
  namespace: gloo-system
  bindAddress: '::'
  bindPort: 8443
  gatewayProxyName: gateway-proxy-v2
  httpGateway: {}
  ssl: true
  useProxyProto: false
status: {}

In this case, we are setting up an HTTP listener on port 8443. When VirtualServices define a TLS context, they’ll automatically bind to this Gateway. You can explicitly configure the Gateway to which a VirtualService binds. In addition, you can also create TCP gateways that allow for binary traffic.

Virtual Services

Virtual Services define a set of route rules, an optional SNI configuration for a given domain or set of domains.

Gloo will select the appropriate virtual service (set of routes) based on the domain specified in a request’s Host header (in HTTP 1.1) or :authority header (HTTP 2.0).

Virtual Services support wildcard domains (starting with *).

Gloo will create a default virtual service for the user if the user does not provide one. The default virtual service matches the * domain, which will serve routes for any request that does not include a Host/:authority header, or a request that requests a domain that does not match another virtual service.

The each domain specified for a virtualservice must be unique across the set of all virtual services provided to Gloo.

For many use cases, it may be sufficient to let all routes live on a single virtual service. In this scenario, Gloo will use the same set of route rules to for requests, regardless of their Host or :authority header.

Route rules consist of a matcher, which specifies the kind of function calls to match (requests and events, are currently supported), and the name of the destination (or destinations, for load balancing) to route them to.

A simple virtual service with a single route might look like this:

name: my-app
- request_matcher:
    path_prefix: /
      name: my-upstream

Note that domains is empty (not specified). That means this virtual service will act as the default virtual service, matching all domains.


Routes are the primary building block of the virtual service. A route contains a single matcher and one of: a single destination, or a list of weighted destinations.

In short, a route is essentially a rule which tells Gloo: if the request matches this matcher, then route it to this destination.

Because multiple matchers can match a single request, the order of routes in the virtual service matters. Gloo will select the first route which matches the request when making routing decisions. It is therefore important to place fallback routes (e.g. matching any request for path / with a custom 404 page) towards the bottom of the route list.


Matchers currently support two types of requests:


Destinations specify where to route a request once a matching route has been selected. A route can point to a single destination, or it can split traffic for that route among a series of weighted destinations.

A destination can be either an upstream destination or a function destination.

Upstream Destinations are analogous to Envoy clusters. Requests routed to upstream destinations will be routed to a server which is expected to handle the request once it has been admitted (and possibly transformed) by Gloo.

Function Destinations allow requests to be routed directly to functions that live on various upstreams. A function can be a serverless function call (e.g. Lambda, Google Cloud Function, OpenFaaS function, etc.), an API call on a service (e.g. a REST API call, OpenAPI operation, XML/SOAP request etc.), or publishing to a message queue (e.g. NATS, AMQP, etc.). Function-level routing is enabled in Envoy by Gloo’s function-level filters. Gloo supports the addition of new upstream types as well as new function types through our plugin interface.


Upstreams define destinations for routes. Upstreams tell Gloo what to route to and how to route to them. Gloo determines how to handle routing for the upstream based on its spec field. Upstreams have a type-specific spec field which must be used to provide routing information to Gloo.

The most basic upstream type is the static upstream type , which tells Gloo a list of static hosts or dns names logically grouped together for an upstream. More sophisticated upstream types include the kubernetes upstream and the AWS Lambda upstream .

Let’s walk through an example of a kubernetes upstream in order to understand how this works.

Gloo reads in a configuration that looks like the following:

    app: redis
    discovered_by: kubernetesplugin
  name: default-redis-6379
  namespace: gloo-system
  resourceVersion: "7010"
  reportedBy: gloo
  state: Accepted
    gloo: redis
  serviceName: redis
  serviceNamespace: gloo-system
  servicePort: 6379


Some upstream types support functions. For example, we can add some HTTP functions to this upstream, and Gloo will be able to route to those functions, providing request transformation to format incoming requests to the parameters expected by the upstream service.

We can now route to the function in our virtual service. An example of a virtual service with a route to this upstream:

  name: default
  namespace: default
  resourceVersion: "7306"
  reportedBy: gateway
  state: Accepted
    '*v1.Proxy gloo-system gateway-proxy': {}
  - '*'
  - matcher:
      prefix: /
          name: gloo-system-redis-6379
          namespace: gloo-system
      prefixRewrite: {}

Note that it is necessary to specify parameters for this function invocation. Some function destinations require extensions to be specified on the route they belong to. Documentation for each plugin can be found in the Plugins section.


Certain plugins such as the AWS Lambda Plugin require the use of secrets for authentication, configuration of SSL Certificates, and other data that should not be stored in plaintext configuration.

Gloo runs an independent (goroutine) controller to monitor secrets. Secrets are stored in their own secret storage layer. Gloo can monitor secrets stored in the following secret storage services:

Secrets must adhere to a structure, specified by the plugin that requires them.