Skip to content

For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Page as Markdown 

    

  
  


          
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.
    • 

  • 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.
    • 



Authentication and authorization policies can be overridden by delegated child routes.


With the default ShallowMergePreferChild strategy, a delegated child route can override and effectively disable authentication and authorization policies inherited from the parent route. For example, a child route can set extAuth.disable: {} or jwtAuth.disable: {} in a TrafficPolicy to bypass the ext-authz or JWT authentication that the parent mandates. Because a tenant who owns a delegated child HTTPRoute can create TrafficPolicies in their own namespace without access to the parent route or platform namespace, this bypass requires no elevated permissions beyond the normal delegatee role.


If you are a platform operator who must enforce mandatory authentication or authorization across all delegated routes, set the kgateway.dev/inherited-policy-priority: ShallowMergePreferParent annotation on the parent HTTPRoute. This ensures that parent security policies take precedence and cannot be overridden by child routes.




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-seasonwinterChild
      

      
x-holidaychristmasChild
      

    
  





Merging examples
    
For more information, check out the following guides:




        

        

        
Global policy attachment

        

  

    Was this page helpful?