Traffic management

Gloo Edge acts as the control plane to manage traffic flowing between downstream clients and upstream services. Traffic management can take many forms as a request flows through the Envoy proxies managed by Gloo Edge. Requests from clients can be transformed, redirected, routed, and shadowed, to cite just a few examples.


The primary components that deal with traffic management in Gloo Edge are as follows:

Additional information can be found in the Gloo Edge Core Concepts document.

Gloo Edge Configuration

Let’s see what underpins Gloo Edge routing with a high-level look at the layout of the Gloo Edge configuration. This can be seen as 3 layers: the Gateway listeners, Virtual Services, and Upstreams. Mostly, you’ll be interacting with Virtual Services, which allow you to configure the details of the API you wish to expose on the Gateway and how routing happens to the backends. Upstreams represent those backends. Gateway objects help you control the listeners for incoming traffic.

Figure: Example configuration of Gloo Edge gateway, virtual service, and upstream resources.

Route Rules

Routes are the primary building block of the Virtual Service. A route contains matchers and an upstream which could be a single destination, a list of weighted destinations, or an upstream group.

There are many types of matchers, including Path Matching, Header Matching, Query Parameter Matching, and HTTP Method Matching. Matchers can be combined in a single rule to further refine which requests will be matched against that rule.

Gloo Edge is capable of sending matching requests to many different types of Upstreams, including Single Upstream, Multiple Upstream, Upstream Groups, Kubernetes services, and Consul services. The ability to route a request to multiple Upstreams or Upstream Groups allows Gloo Edge to load balance requests and perform Canary Releases.

Figure: Sample of routing rules that are configured in a virtual service.

Configuring the routing engine is done with defined predicates that match on incoming requests. The contents of a request, such as headers, path, method, etc., are examined to see if they match the predicates of a route rule. If they do, the request is processed based on enabled routing features and routed to an Upstream destinations such as REST or gRPC services running in Kubernetes, EC2, etc. or Cloud Functions like Lambda. In the Traffic Management section we’ll dig into this process further.

Listener configuration

The Gateway component of Gloo Edge is what listens for incoming requests. An example configuration is shown below for an SSL Gateway. The spec portion defines the options for the Gateway.

kind: Gateway
    app: gloo
  name: gateway-proxy-ssl
  namespace: gloo-system
  bindAddress: '::'
  bindPort: 8443
  httpGateway: {}
  - gateway-proxy
  ssl: true
  useProxyProto: false

A full listing of configuration options is available in the API reference for Gateways.

The listeners on a gateway typically listen for HTTP requests coming in on a specific address and port as defined by bindAddress and bindPort. Additional options can be configured by including an options section in the spec. SSL for a gateway is enabled by setting the ssl property to true.

Gloo Edge can be configured to act as a gateway on layer 7 (HTTP/S) or layer 4 (TCP). The majority of services will likely be using HTTP, but there may be some cases where applications either do not use HTTP or should be presented as a TCP endpoint. When Gloo Edge operates as a TCP Proxy, the options for traffic management are greatly reduced. Gloo Edge currently supports standard routing, SSL, and Server Name Indication (SNI) domain matching. Applications not using HTTP can be configured using the TCP Proxy guide.

Gloo Edge is meant to serve as an abstraction layer, simplifying the configuration of the underlying Envoy proxy and adding new functionality. The advanced options on Envoy are not exposed by default, but they can be accessed by adding an httpGateway section to your listener configuration.

kind: Gateway

          verbose: true
            - path
            - origin

Some of the advanced options include enabling tracing, access log configuration, disabling gRPC Web transcoding, and fine-grained control over Websockets. More detail on how to perform advanced listener configuration can be found in the HTTP Connection Manager guide.

Traffic processing

Traffic that arrives at a listener is processed using one of the Virtual Services bound to the Gateway. The selection of a Virtual Service is based on the domain specified in the request. A Virtual Service contains rules regarding how a destination is selected and if the request should be altered in any way before sending it along.

Destination selection

Routes are the primary building block of a Virtual Service. Routes contain matchers and an Upstream which could be a single destination, a list of weighted destinations, or an Upstream Group.

kind: VirtualService

      - ''
      - matchers:
         - prefix: /app/cart
              name: shopping-cart
              namespace: gloo-system

Matchers inspect information about a request and determine if the data in the request matches a value defined in the rule. The content inspected can include the request path, header, query, and method. Matchers can be combined in a single rule to further refine which requests will be matched against that rule. For instance, a request could be using the POST method and reference the path /app/cart. The combination of an HTTP Method matcher and a Path matcher could identify the request, and send it to a shopping cart Upstream.

More information on each type of matcher is available in the following guides.

Destination types

Once an incoming request has been matched by a route rule, the traffic can either be sent to a destination or processed locally. The most common destination for a route is a single Gloo Edge Upstream. It’s also possible to route to multiple Upstreams, by either specifying multiple destinations, or by configuring an Upstream Group. Finally, it’s possible to route directly to Kubernetes or Consul services, without needing to use Gloo Edge Upstreams or discovery.

Single Upstreams

Upstreams can be added manually, creating what are called Static Upstreams. Gloo Edge also has a discovery service that can monitor Kubernetes or Consul and automatically add new services as they are discovered. When routing to an Upstream, you can take advantage of Gloo Edge’s endpoint discovery system, and configure routes to specific functions, either on a REST or gRPC service, or on a cloud function.

Multiple Upstreams

There may be times you want to specify multiple Upstreams for a given route. Perhaps you are performing Blue/Green testing, and want to send a certain percentage of traffic to an alternate version of a service. You can specify multiple Upstream destinations in your route, create an Upstream Group for your route, or send traffic to a subset of pods in Kubernetes.

Gloo Edge can also use Upstream Groups to perform a canary release, by slowly and iteratively introducing a new destination for a percentage of the traffic on a Virtual Service. Gloo Edge can be used with Flagger to automatically change the percentages in an Upstream Group as part of a canary release.

In addition to static and discovered Upstreams, the following Upstreams can be created to map directly a specialty construct:

Route Delegation

While it is possible to have a single Virtual Service directly route all traffic for a domain in its main route configuration, that may not always be the best approach. Let’s say you have a domain called which runs a shopping cart API and a community forum. The shopping cart API is handled by one team and the community forum is handled by another. You want to enable each team to make updates on their routing rules, without stepping on each other toes or messing with the main Virtual Service for the domain. Sounds like a job for route delegation!

In a route delegation, a prefix of the main Virtual Service can be delegated to a Route Table. The Route Table is a collection of routes, just like in the main Virtual Service, but the permissions of the Route Table could be scoped to your shopping cart API team. In our example, you can create route delegations for the /api/cart prefix and the /community prefix to route tables managed by the respective teams. Now each team is free to manage their own set of routing rule, and you have the freedom to expand this model as new services are added to the domain. You can find out more in the route delegation guide.

Traffic processing

Gloo Edge can also alter requests before sending them to a destination, including transformations, fault injections, response header editing, and prefix rewrites. The ability to edit requests on the fly gives Gloo Edge the power to specify the proper parameters for a function or transform and error check incoming requests before passing them along.

For more information, see Traffic processing.

Configuration validation

When configuring an API gateway or edge proxy, invalid configurations can quickly lead to bugs, service outages, and security vulnerabilities. Whenever Gloo Edge configuration objects are updated, Gloo Edge validates and processes the new configuration. This is achieved through a four-step process:

  1. Admit or reject change with a Kubernetes Validating Webhook
  2. Process a batch of changes and report any errors
  3. Report the status on change
  4. Process the changes and apply to Envoy

More detail on the validation process and its settings can be found in the Configuration Validation guide.

Next Steps

Now that you have an understanding of how Gloo Edge handles traffic management we have a few suggested paths: