Route delegation

Documentation

Route delegation

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 automatically 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.targetRefs field 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.
Child RouteOption resources cannot override policies that are defined in a RouteOption resource that is applied to a parent HTTPRoute. If 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.
Child HTTPRoutes can augment the inherited settings by defining RouteOption fields that were not already set on the parent HTTPRoute.
Policies are inherited along the complete delegation chain, with parent policies having a higher priority than their respective children.

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


 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/.*.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


 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?
parent match on `/anything/team1` and delegate traffic to the `child` HTTPRoute header1: val1 query1=val1 child match on `/anything/team1/foo` and route traffic to the httpbin app header1: val1 headerX: valX query1=val1 queryX=valX	✅ 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.
parent match on `/anything/team1` and delegate traffic to the `child` HTTPRoute header1: val1 query1=val1 child match on `/anything/team1/foo` and route traffic to the httpbin app headerX: valX queryX=valX	❌ 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 K8sGateway 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.