Policies
Learn more about the custom resources that you can use to apply policies in K8sGateway.
While the Kubernetes Gateway API allows you to do simple routing, such as to match, redirect, or rewrite requests, you might want additional capabilities in your API gateway, such as fault injection, direct responses, or header control. Policies allow you to apply intelligent traffic management, resiliency, and security standards to individual routes or all the routes that the gateway serves.
Policy CRDs
K8sGateway uses the following custom resources to attach policies to routes and gateway listeners.
Directly respond to incoming requests with a custom HTTP response code and body.
Attach policies to one, multiple, or all gateway listeners.
Apply policies to one, multiple, or all HTTP and HTTPS listeners.
Attach policies to one, multiple, or all routes in an HTTPRoute resource.
Attach policies to the hosts on one, multiple, or all gateway listeners.
Supported policies
Review the policies that you can configure in K8sGateway and the level at which you can apply them.
Traffic management policies
| Policy | Applied via | Precedence and merging rules |
|---|---|---|
| Connection buffer limits | ListenerOption | No cross-resource conflict. Policies can conflict only if applied in multiple ListenerOption resources. For more information, see Conflicting policies. |
| Direct response | DirectResponse | No cross-resource conflict. If multiple DirectResponse resources are applied to the same route, only the one that is referenced first is enforced. |
| Fault injection | RouteOption | No cross-resource conflict. Policies can conflict only if applied in multiple RouteOption resources. For more information, see Conflicting policies. |
| Header control |
|
Headers that are defined at the route and virtual host-level are merged as long as they do not conflict. If the same header is defined in both a RouteOption and VirtualHostOption resource, the RouteOption configuration takes precedence and the VirtualHostOption configuration is ignored. |
| Proxy protocol | ListenerOption | No cross-resource conflict. Policies can conflict only if applied in multiple ListenerOption resources. For more information, see Conflicting policies. |
| Rewrites | RouteOption | No cross-resource conflict. Policies can conflict only if applied in multiple RouteOption resources. For more information, see Conflicting policies. |
| Transformations |
|
RouteOption configuration takes precedence over VirtualHostOption configuration. Policies that are defined at different levels are not merged. |
Resiliency policies
| Policy | Applied to | Precedence and merging rules |
|---|---|---|
| Fault injection | RouteOption | No cross-resource conflict. Policies can conflict only if applied in multiple RouteOption resources. For more information, see Conflicting policies. |
| Retries |
|
RouteOption configuration takes precedence over VirtualHostOption configuration. Policies that are defined at different levels are not merged. |
| Shadowing | RouteOption | No cross-resource conflict. Policies can conflict only if applied in multiple RouteOption resources. For more information, see Conflicting policies. |
| Timeouts | RouteOption | No cross-resource conflict. Policies can conflict only if applied in multiple RouteOption resources. For more information, see Conflicting policies. |
Security policies
| Policy | Applied to | Precedence and merging rules |
|---|---|---|
| Access logging | ListenerOption | No cross-resource conflict. Policies can conflict only if applied in multiple ListenerOption resources. For more information, see Conflicting policies. |
| CORS |
|
By default, the configuration of the RouteOption takes precedence over the VirtualHostOption. However, you can change this behavior for the exposeHeaders CORS option by using the corsPolicyMergeSettings field in the VirtualHostOption. Currently, only exposeHeaders is configurable. You cannot merge other CORS options such as allowHeaders or allowOrigin. For more information about this option, see the CORS configuration options. |
| CSRF |
|
RouteOption configuration takes precedence over VirtualHostOption configuration, which takes precedence over HttpListenerOption configuration. Policies that are defined at different levels are not merged. |
| Local rate limiting | HttpListenerOption | No cross-resource conflict. Policies can conflict only if applied in multiple HttpListenerOption resources. For more information, see Conflicting policies. |
Policy inheritance rules when using route delegation
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.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. - 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.