Routing setup

Use Gloo Mesh Gateway’s suite of traffic management custom resources to serve traffic along different routes. Review the following diagram for an overview by persona of how you might set up routing within your environment.

Figure: Overview of routing setup with Gloo by persona
  1. A client makes a request to your service along a certain host and route.
  2. For requests that come in from outside your cluster environment, the request passes through an ingress gateway (north-south traffic). You can configure ingress gateways with a virtual gateway custom resource that your operator sets up. You have a few gateway setup options:
    • One gateway per host for the most control. In this scenario, make sure to specify the host to listen on in your virtual gateway configuration.
    • One gateway for multiple hosts. You might omit the host in your virtual gateway configuration, and let the route tables configure the host.
    • For internal requests (east-west traffic), you might not use a virtual gateway. If the client request originates in the same cluster, the request goes to the host as configured in a route table, a virtual destination, or the backing service itself. If the client request originates in a different cluster, the request first goes through the Istio east-west gateway and then to the host as configured in a route table, a virtual destination, or the backing service itself.
  3. Your operators create policies that select routes or destinations to shift, secure, and otherwise control traffic to your apps. Your developers might also use select policies as part of app development, such as fault injection or retries. Either the ingress gateway or the Istio sidecar enforces the policy, depending on whether the policy is client- or server-side.
  4. Your operators and developers collaborate on a route table that defines how traffic is routed for the host. Operators might configure sections such as hosts, while developers determine routing actions, backing destinations, and route names that match APIs. The route table defines several important aspects, including:
    • The host to listen for traffic requests on
    • The routes on the host to serve requests
    • The routing actions to take for each route, such as forwarding to a backing destination
    • The destination that fulfills the request, such as a Kubernetes service or Gloo virtual destination
    • Route weights, delegation, and specificity to control order
  5. Your developers define service destinations that back the routes, such as grouping together multiple services with Gloo’s intelligent, multicluster virtual destinations.
  6. Your developers deploy the application workloads that back the service destinations to respond to traffic requests along the route.

For more information about how routing works, see the following routing scenarios:

Supported route types and features

Gloo supports the following route types:

  • HTTP routes: The most common use case for traffic at the Layer 7 application level of the OSI model. HTTP typically uses TCP to establish a connection, but then adds capabilities such as headers, queries, and methods. These extra capabilities let you perform advanced traffic management with Gloo routing actions and policies. For more information about HTTP, you can review docs such as the mdn web docs.
  • TCP routes (Gloo Mesh Enterprise license required): A lower-level, Layer 4 connection-oriented protocol used for basic client-server traffic within your environment. A common example use case is to establish a low-latency connection to a local database. Gloo supports TCP routes only for Gloo Mesh Enterprise service mesh traffic within your cluster setup (east-west), not for Gloo Mesh Gateway ingress traffic (north-south). For more information about TCP, you can review docs such as the mdn web docs.
  • TLS routes (Gloo Mesh Gateway license required): TLS is based on top of the TCP protocol and is responsible to encrypt traffic and authenticate requests on Layer 7, such as for HTTP requests, by using TLS certificates. With TLS routes, you can inspect the SNI field that is presented during the TLS handshake and set up custom routing to TLS services in the cluster based on that SNI. TLS routes require a TLS listener to be configured on the gateway that enables TLS passthrough. Note that because TLS traffic is not terminated at the gateway, the targeted destination must be capable of handling TLS traffic. For more information about TLS routes, see TLS passthrough for a host.

To understand Gloo’s advanced routing capabilities by protocol, review the following table. For more information, see the RouteTable API documentation.

AreaHTTP routesTCP routes (Gloo Mesh Enterprise license required)TLS routes (Gloo Mesh Gateway license required)
Gloo product
  • Gloo Mesh Gateway for ingress traffic (north-south)
  • Gloo Mesh Enterprise for service mesh traffic (east-west)
  • Gloo Mesh Enterprise for service mesh traffic (east-west)
  • Gloo Mesh Gateway for ingress traffic (north-south)
Route metadata
  • Route name
  • Route labels
Request matchingIncoming request matching for HTTP traffic, including to match on the URI path, header, query, and HTTP methodIncoming request matching for TCP trafficIncoming request matching on SNI host names
Routing actionsAll routing actions:Select routing actions:Select routing actions:
Supported destinationsAll destinations:
  • Kubernetes service
  • Gloo virtual destination
  • Gloo external service
  • Gloo cloud provider (such as for AWS Lambdas)
Select destinations:
  • Kubernetes service
  • Gloo virtual destination
Select destinations:
  • Kubernetes service
Supported hosts
  • Internal Kubernetes hosts (e.g., svc.cluster.local)
  • Ingress host (north-south traffic)
  • Mesh host (east-west traffic)
  • Internal Kubernetes hosts (e.g., svc.cluster.local)
  • Ingress host (north-south traffic)
Multicluster support
  • Gloo workspace-level federation
  • Gloo virtual destination groupings
  • Gloo workspace-level federation
  • Gloo virtual destination groupings
  • Gloo workspace-level federation
Supported policiesAll routing policiesNoneNone

Gateways to route traffic

You can select the gateway proxy that routes traffic to your apps along the routes that you configure in the route table. The gateway proxy can be a stand-alone gateway, such as your Istio ingress gateway, or the sidecar proxy of a workload. For more information, see the API docs.

Configuration optionWhat it refers toWhen to use itDelegation scenariosMore considerations
virtualGatewayA Gloo VirtualGateway resource that you create to configure a gateway, such as the Istio ingress gateway.To route traffic through a gateway. You must use this option for ingress traffic. For a mesh-only scenario, you can set virtualGateway to null in your route table and use workloadSelectors instead.Specify the virtual gateway on the parent route table only. Do not include this field in delegated child route tables.You must define at least one host for the virtual gateway to listen on. If you omit this field, the route table uses the sidecars of your workloads as specified in the workloadSelectors field.
workloadSelectorsThe sidecar proxy of a workload that you deployed. Note that this workload must run in the mesh. You cannot currently select an external workload, such as in a virtual machine (VM).To restrict the traffic that gets routed to the selected workloads. For example, you might want a route table that defines rules for only for workloads that are owned by team foo, and another route table with a different priority for workloads that are owned by team bar.Delegated child route tables inherit the workload selectors of the parent route table, such as ‘value:foo’. The delegated child route table can also have its own workload selectors, such as ‘env:prod’. These workload selectors are logically AND’d together. As a result, the child route table routes traffic only to workloads with both ‘value:foo’ and ‘env:prod’ labels. Note that the child route table cannot override the parent’s workload selectors, such as by setting ‘value:bar’. In that case, the child route gets an error until the conflict is resolved.You must have a Gloo Mesh Enterprise license to use workload selectors. You must define at least one host for the workload sidecar proxy to listen on. If you omit this field, all workloads are selected by default. You can select workloads by using labels only. Selecting workloads by using other references, such as the name, namespace, or cluster is not supported.

Routing actions

To perform a routing action on an incoming request, you must first match the request on certain characteristics, such as headers, methods, URIs, or request paths. After the request is matched, you can configure the following actions routing actions.

Type of actionDescription
Route to a destinationDirectly forward the request to a destination within the service mesh. The destination can be one of the following:
  • Gloo virtual destination: Used to route incoming requests across multiple clusters based on locality.
  • Gloo external service: Used to route incoming requests to a service that is hosted outside the service mesh. Available only for HTTP routes.
  • Gloo cloud provider: Used to route the request to a serverless function in a cloud provider, such as AWS Lambda. Available only with a Gloo Mesh Gateway license and for HTTP routes.
  • Kubernetes service: Used to route the request directly to a service in a specified cluster. In most cases, however, you create a virtual destination that is backed by Kubernetes services.
Direct responseRather than routing the request to the upstream service within your service mesh, you send back a pre-defined body and HTTP status response to the client. If necessary, headers can be specified using the Header Modification feature in the enclosing route. Available only for HTTP routes.
Redirect responseThe request is not routed to the upstream service within the service mesh. Instead, you send back a location header containing the alternate URL you want your client to redirect to. Available only for HTTP routes.
Delegate to a route tableThe decision for what to do with an incoming request is delegated to one or more route tables. This can be very useful when the number of routes configured on a given gateway starts to become large, and multiple teams need to make route edits. Available only for HTTP routes.
GraphQLExpose your backing API services with route-level customization logic by using Gloo Mesh Gateway as a GraphQL server.

Applying overlapping route configuration

In some cases, you might have overlapping route configuration in or across route tables. For example, within a single route table, you might define multiple types of matchers for a single route or host. Or for delegated route tables, you might define multiple methods of matching for the same route or host. However, in these cases, you can use weight and specificity values to indicate which routes should be applied in which order of priority. For example, see the specificity rules for routing to delegated tables. Incoming requests are matched to the highest-priority matchers in these cases.

Route table conflicts occur only when all three of the following conditions are met between two or more route tables:

  • Each route table selects the same virtual gateway or workload.
  • Each route table selects the same host.
  • The route tables define conflicting route matchers.

Do not configure two or more route tables according to these conditions. Gloo cannot correctly process and forward traffic requests to routes in this case.

Handling of misconfigured routes

Gloo offers different route table failure modes that determine how a route table handles misconfigured routes. For more information, see Route table failure modes.