Routing overview
Use Gloo Platform'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.
- A client makes a request to your service along a certain host and route.
- 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.
- 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.
- 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
- Your developers define service destinations that back the routes, such as grouping together multiple services with Gloo's intelligent, multicluster virtual destinations.
- 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:
- Multicluster routing
- Routing to external services that live outside your cluster environment
- Federated services
Supported route types and features
Gloo Platform 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: 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 service mesh traffic within your cluster setup (east-west), not for Gloo Gateway ingress traffic (north-south). For more information about TCP, you can review docs such as the mdn web docs.
- TLS routes: 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.
To understand Gloo Platform's advanced routing capabilities by protocol, review the following table. For more information, see the Route table API documentation.
| Area | HTTP routes | TCP routes | TLS routes |
|---|---|---|---|
| Gloo product |
|
|
|
| Route metadata |
|
None | None |
| Request matching | Incoming request matching for HTTP traffic, including to match on the URI path, header, query, and HTTP method | Incoming request matching for TCP traffic | Incoming request matching on SNI host names |
| Routing actions | All routing actions: | Select routing actions: | Select routing actions: |
| Supported destinations | All destinations:
|
Select destinations:
|
Select destinations:
|
| Supported hosts |
|
|
|
| Multicluster support |
|
|
|
| Supported policies | All routing policies | None | None |
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 option | What it refers to | When to use it | Delegation scenarios | More considerations |
|---|---|---|---|---|
virtualGateway |
A 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. |
workloadSelectors |
The 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). For workloads in ambient mode, use applyToDestinations instead. |
To restrict the traffic that gets routed to the selected workloads. For example, you might want a route table that defines rules for www.example.com only for workloads that are owned by team foo, and another www.example.com 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. |
applyToDestinations |
A destination in an Istio service mesh with ambient mode. In ambient mode, a stand-alone waypoint proxy is used to route L7 traffic, instead of each workload having its own sidecar. For destinations with their own sidecars, use workloadSelectors instead. |
To apply this route table's policies for any ingress or mesh traffic to the selected ambient destination. | Specify the destinations on the parent route table only. Do not include this field in delegated child route tables. | This option is an alpha feature and subject to change. External workloads, external services, and destinations with sidecars are 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 action | Description |
|---|---|
| Route to a destination | Directly forward the request to a destination within the service mesh. The destination can be one of the following:
|
| Direct response | Rather 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 response | The 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 table | The 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. |
| GraphQL | Expose your backing API services with route-level customization logic by using Gloo Gateway as a GraphQL server. For more information, see the Gloo Gateway GraphQL docs. |
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 Gateway cannot correctly process and forward traffic requests to routes in this case.
Handling of misconfigured routes
Gloo Gateway offers different route table failure modes that determine how a route table handles misconfigured routes. For more information, see Route table failure modes.