Route delegation overview
Delegate routing decisions to another HTTPRoute resource.
What is route delegation
As your environment grows, your gateways manage traffic for more and more routes. These routes typically belong to many different apps that are owned by different individuals or teams. Managing the routing rules for all of these routes can be cumbersome and route updates can easily impact the behavior of other routes.
Route delegation allows you to split up big and complex routing configurations into smaller routing configurations that are easier to maintain. The ownership for these routing configurations are then delegated to the teams that own the app or domain.
For example, let’s assume you have three apps (app-a, app-b, and app-c) that are owned by three different teams (team-a, team-b, and team-c). Instead of creating one routing configuration that includes the routing rules for all apps, you create a routing configuration for each app and delegate ownership for this configuration to the team that is responsible for that app. Each team can then further delegate routing decisions to other teams.
Each set of routing rules is defined in a dedicated HTTPRoute resource. These HTTPRoute resources are then organized into a routing hierarchy that consists of the following elements:
| Element in routing hierarchy | Resource | Description |
|---|---|---|
| Parent | HTTPRoute | The parent HTTPRoute resource specifies the main domain under which all of the routes that are defined in the parent, child, or grandchild HTTPRoute resources are exposed on. The parent HTTPRoute resource also references the gateway that you want to use to fulfill the routing configuration in the parentRef section. To delegate traffic to a child HTTPRoute resource, a PathPrefix matcher must be used. |
| Child | HTTPRoute | The child HTTPRoute resource receives traffic from the parent HTTPRoute resource and can either forward traffic to the backing service, or delegate traffic decisions to grandchild HTTPRoute resources. To receive delegated traffic from a parent, the child HTTPRoute must match on a path that contains the path prefix for which the parent delegated traffic for. For example, if the parent delegates traffic for /route, the child must define a route that includes this prefix, such as /route/a. If traffic is further delegated to a grandchild HTTPRoute resource, a PathPrefix matcher must be used. |
| Grandchild | HTTPRoute | A grandchild HTTPRoute resource receives traffic from a child HTTPRoute resource and can either bind to a specific child by using the parentRef section or be selected by all child HTTPRoute resources that want to delegate traffic to this grandchild. To receive traffic from a child, the grandchild must match on a path that contains the path prefix for which the child delegated traffic for. For example, if the child delegates traffic for /route/a, the grandchild must define a route that includes this prefix, such as /route/a/myservice. If traffic is further delegated to a great-grandchild HTTPRoute resource, a PathPrefix matcher must be used. Note that great-grandchild or great-great-grandchild behave similar to a grandchild HTTPRoute resource. |
For an example route delegation setup with a parent, child, and grandchild HTTPRoute resource, see Multi-level delegation.
Benefits and use cases
Route delegation is often used as a security and risk mitigation strategy to allow multiple teams to own, add, remove, and update routes on a gateway without impacting the routing rules that other teams configured and requiring access to the entire routing configuration.
Review some of the benefits that you can achieve with route delegation:
| Benefit | Description |
|---|---|
| Organize routing rules by user groups | With route delegation, you can break up large routing configurations into smaller routing configurations which makes them easier to maintain and to assign ownership to. Each routing configuration in the routing hierarchy contains the routing rules and policies for only a subset of routes. |
| Restrict access to routing configuration | Because route delegation lets you break up large routing configurations into smaller, manageable pieces, you can easily assign ownership and restrict access to the smaller routing configurations to the individual or teams that are responsible for a specific app or domain. For example, the network administrator can configure the top level routing rules, such as the hostname and main route match, and delegate the individual routing rules to other teams. |
| Simplify blue-green route testing | To test new routing configuration, you can easily delegate a specific number of traffic to the new set of routes. |
| Optimize traffic flows | Route delegation can be used to distribute traffic load across multiple paths or nodes in the cluster, which can improve network performance and reliability. |
| Easier updates with limited blast radius | Individual teams can easily update the routing configuration for their apps and manage the policies for their routes. If errors are introduced, the blast radius is limited to the set of routes that were changed. |
Policy inheritance
Policies that are defined in a RouteOption resource and that are applied to a parent HTTPRoute resource are inherited by all the child or grandchild HTTPRoutes along the route delegation chain. The following rules apply:
- Only policies that are specified in a RouteOption resource can be inherited by a child HTTPRoute. For inheritance to take effect, you must use the
spec.targetRefsfield in the RouteOption resource to apply the RouteOption resource to the parent HTTPRoute resource. Any child or grandchild HTTPRoute that the parent delegates traffic to inherits these policies. - You can add the
delegation.gateway.solo.io/enable-policy-overridesannotation to a parent HTTPRoute to allow its immediate child HTTPRoutes to override the top-level policies that are defined on the parent. You have the option to allow overriding policies of all types (delegation.gateway.solo.io/enable-policy-overrides: "*") or to limit the type of policies that a child can override (delegation.gateway.solo.io/enable-policy-overrides: "faults,headerManipulation,cors"). - In a multi-level delegation chain with parent, child, and grandchild HTTPRoutes, the parent and the child HTTPRoutes must both set the
delegation.gateway.solo.io/enable-policy-overridesannotation for the grandchild to be able to override the top-level policies that were defined on the parent. - If no
delegation.gateway.solo.io/enable-policy-overridesannotation is set on the parent and the child HTTPRoute sets a policy that is already defined on the parent HTTPRoute, the setting on the parent HTTPRoute takes precedence and the setting on the child is ignored. For example, if the parent HTTPRoute defines a data loss prevention policy, the child HTTPRoute cannot change these settings or disable that policy. - If no
delegation.gateway.solo.io/enable-policy-overridesannotation is set on the parent HTTPRoute, child HTTPRoutes can augment the inherited settings by defining RouteOption fields that were not already set on the parent HTTPRoute.
For an example, see the Policy inheritance guide.
Limitations
The current route delegation model imposes a few restrictions on how routes can be delegated. If a rule is violated, the corresponding rule is removed from the route.
Hostnames
Only parent HTTPRoutes can specify the spec.hostnames field. All child and grandchild HTTPRoute resources inherit the parent’s hostname.
Route matchers
Parent HTTPRoute resources that delegate to child HTTPRoute resources must use PathPrefix matchers as shown in the following example:
rules:
- matches:
- path:
type: PathPrefix
value: /a
backendRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: "*"
namespace: abc
Child HTTPRoute resources can use prefix, exact, or regex path matchers in their matching rules as shown in the following example. Each path matcher must start with the prefix path that the parent HTTPRoute delegates traffic for, in this case /a. The child HTTPRoute in the following example defines three route matchers along the /a path: /1, /1/foo, and /1/.*.
rules:
- matches:
- path:
type: PathPrefix
value: /a/1
- path:
type: Exact
value: /a/1/foo
- path:
type: RegularExpression
value: /a/1/.*
backendRefs:
- name: svc-a
port: 8080
Keep in mind that if a child HTTPRoute delegates routing decisions to a grandchild or great-grandchild HTTPRoute, a PathPrefix matcher must be used for that route. Check out the Multi-level delegation guide for an example of how to set up route delegation between a parent, child, and grandchild HTTPRoute.
Headers, query parameters, HTTP methods
You can specify headers, query parameters, and HTTP method matchers on the parent HTTPRoute resource. However, any child HTTPRoute resource that you delegate traffic to must specify the same header, query parameters, or HTTP method matchers to be considered a valid configuration. You can optionally define additional header, query parameter, or HTTP method matchers on the child.
For example, let’s say you define the following parent and child HTTPRoute resources:
| Example configuration | Valid route delegation configuration? |
|---|---|
| ✅The headers and query parameters that are specified on the child HTTPRoute are a superset of the header and query parameters that are specified on the parent. |
| ❌The headers and query parameters that are specified on the child HTTPRoute do not include the header and query parameters that are specified on the parent. |
For an example route delegation setup that uses header and query parameters, see Header and query match.
Cyclic delegation
Cyclic route delegations, such as where HTTPRoute A delegates to B, B delegates to C, and C delegates back to A are not allowed in Gloo Gateway as no proper backend is specified that fulfills the request. If cyclic route delegation is detected, the route that is part of the cycle is ignored and reported as an error.