Concepts


Overview

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

Gateways

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-proxy       61s
gateway-proxy-ssl   61s

A single gateway definition looks like the following:

apiVersion: gateway.solo.io/v1
kind: Gateway
metadata:
  annotations:
    helm.sh/hook: pre-install
    helm.sh/hook-weight: "5"
  labels:
    app: gloo
    installationId: mJJVFfg3zbihCY9msXdM
  name: gateway-proxy-ssl
  namespace: gloo-system
spec:
  bindAddress: '::'
  bindPort: 8443
  httpGateway: {}
  proxyNames:
  - gateway-proxy
  ssl: true
  useProxyProto: false

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 matchers, which specify 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:

apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: default
  namespace: gloo-system
spec:
  virtualHost:
    domains:
    - '*'
    routes:
    - matchers:
      - prefix: /
      routeAction:
        single:
          upstream:
            name: my-upstream
            namespace: gloo-system

Note that we could have omitted domains, which would default to ‘*‘. This virtual service will act as the default virtual service, matching all domains. We could have also omitted matchers here, which would default to the / prefix matcher, which matches all requests.

Routes

Routes are the primary building block of the virtual service. A route contains a list of matchers and one of:

In short, a route is essentially a rule which tells Gloo: if the request matches a matcher on the route, 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

Matchers currently support two types of requests:

Destinations

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

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:

apiVersion: gloo.solo.io/v1
kind: Upstream
metadata: 
  labels:
    discovered_by: kubernetesplugin
  name: default-redis-6379
  namespace: gloo-system
spec:
  discoveryMetadata: {}
  kube:
    selector:
      gloo: redis
    serviceName: redis
    serviceNamespace: gloo-system
    servicePort: 6379
status:
  reported_by: gloo
  state: 1 # Accepted

Functions

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:

apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: default
  namespace: default
spec:
  virtualHost:
    domains:
    - '*'
    routes:
    - matchers:
       - prefix: /petstore/findWithId
      routeAction:
        single:
          destinationSpec:
            rest:
              functionName: findPetById
              parameters:
                headers:
                  :path: /petstore/findWithId/{id}
          upstream:
            name: petstore
            namespace: gloo-system
      options:
        prefixRewrite: /api/pets

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.

Secrets

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.