Docs
Documentation
About
Policies
Policy merging

Policy merging

Kgateway lets you define how policies are merged when they are applied to a parent and child resource.

About

Parent-child hierarchies might be:

  • Resources that target or serve other resources, such as Gateway > ListenerSet > HTTPRoute > Route rule.
  • Routes that are delegated, such as Parent HTTPRoute A > Child HTTPRoute B > Grandchild HTTPRoute C.

Policy merging applies to the following policies:

  • Native Kubernetes Gateway API policies, such as rewrites, timeouts, or retries.
  • Kgateway TrafficPolicy.

Resources that are higher in the parent-child hierarchy can use a special annotation to define how child resources inherit policies. This way, parent resources such as a Gateway or HTTPRoute can decide whether child resources can override the parent policies or not.

Merging annotation

The annotation on the parent resource is: kgateway.dev/inherited-policy-priority.

You can use the following values for the annotation:

  • ShallowMergePreferChild (default): Child policies take precedence over parent policies and the policies are shallow merged.
  • ShallowMergePreferParent: Parent policies take precedence over child policies and the policies are shallow merged.

Shallow merging means that the policies are merged at the top level. Only the top-level fields of the policies are considered for merging. If a field is present in both parent and child policies, the value from the higher priority policy is used. Priority is typically determined by specificity and creation time. The more specific (such as HTTPRoute rule over all the routes in the HTTPRoute) and older (created-first) policy takes precedence. Consider the following shallow merge scenario:

  • Parent policy adds a x-season=summer header.
  • Child policy adds x-season=winter and x-holiday=christmas headers.
  • Merging annotation is the default value, ShallowMergePreferChild.

Resulting merged policy: The parent’s x-season header is not included in the merged policy because the strategy is ShallowMergePreferChild.

Header Value Source
x-season winter Child
x-holiday christmas Child

Merging examples

For more information, check out the following guides:

TrafficPolicy