RouteOption

Use a RouteOption resource to attach policies to one, multiple, or all routes in an HTTPRoute resource.

Policy attachment

You can apply RouteOption policies to all routes in an HTTPRoute resource or only to specific routes.

Option 1: Attach the policy to all HTTPRoute routes (targetRefs)

You can use the spec.targetRefs section in the RouteOption resource to apply policies to all the routes that are specified in a particular HTTPRoute resource.

The following example RouteOption resource specifies header manipulation rules. Because the my-httproute HTTPRoute resource is referenced in the spec.targetRefs section, the header manipulation rules are applied to all routes in that HTTPRoute resource.

apiVersion: gateway.kgateway.dev/v1alpha1
kind: RouteOption
metadata:
  name: parent-remove-header
  namespace: kgateway-system
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: my-httproute
  options:
    headerManipulation:
      responseHeadersToAdd:
      - header:
          key: test
          value: bar

Option 2: Attach the policy to an individual route (ExtensionRef)

Instead of applying the policy to all routes that are defined in an HTTPRoute resource, you can apply them to specific routes by using the ExtensionRef filter in the HTTPRoute resource.

The following example shows a RouteOption resource that defines a host rewrite rule. Note that the spec.targetRefs field is not set. Because of that, the RouteOption policy does not apply until it is referenced in an HTTPRoute by using the ExtensionRef filter.

apiVersion: gateway.kgateway.dev/v1alpha1
kind: RouteOption
metadata:
  name: rewrite
  namespace: httpbin
spec:
  options:
    hostRewrite: 'www.example.com'

To apply the policies to a particular route, you use the ExtensionRef filter on the desired HTTPRoute route. In the following example, the RouteOption policy is applied to the /anything/path1 route. However, it is not applied to the /anything/path2 path.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-rewrite
  namespace: httpbin
spec:
  parentRefs:
  - name: http
    namespace: kgateway-system
  hostnames:
    - rewrite.example
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /anything/path1
    filters:
      - type: ExtensionRef
        extensionRef:
          group: gateway.solo.io
          kind: RouteOption
          name: rewrite
    backendRefs:
    - name: httpbin
      port: 8000
  - matches:
    - path:
        type: PathPrefix
        value: /anything/path2
      backendRefs:
        - name: httpbin
          port: 8000

You can also add multiple ExtensionRef filters to the same route as shown in the following example.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-rewrite
  namespace: httpbin
spec:
  parentRefs:
  - name: http
    namespace: kgateway-system
  hostnames:
    - rewrite.example
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /anything/path1
    filters:
      - type: ExtensionRef
        extensionRef:
          group: gateway.solo.io
          kind: RouteOption
          name: rewrite
      - type: ExtensionRef
        extensionRef:
          group: gateway.solo.io
          kind: RouteOption
          name: faultinjection
    backendRefs:
    - name: httpbin
      port: 8000
  - matches:
    - path:
        type: PathPrefix
        value: /anything/path2
      backendRefs:
        - name: httpbin
          port: 8000

Conflicting policies and merging rules

Review how policies are merged if you apply multiple RouteOption resources to the same route.

ExtensionRef vs. targetRefs

If you apply two RouteOption resources that both specify the same top-level policy type and you attach one RouteOption via the extensionRef filter and one via the targetRefs section, only the RouteOption resource that is attached via the extensionRef filter is applied. The policy that is attached via targetRefs is ignored.

Note that the targetRefs RouteOption resource can augment the extensionRef RouteOption if it specifies different top-level policies. For example, the extensionRef RouteOption might define a policy that adds request headers. While you cannot specify additional or other request header rules in the targetRefs RouteOption, you can define different policies, such as response headers or fault injection policies.

In the following image, you have three RouteOption resources that each define a kgateway policy. One CORS policy (policy 1) is applied to all routes in an HTTPRoute resource via the targetRefs section. Another CORS policy (policy 2) and a fault injection policy (policy 3) are applied to only route A by using the extensionRef filter in the HTTPRoute resource.

Because policies that are attached via extensionRef take precedence over policies that are attached via targetRefs, the CORS policy 2 is attached to route A. In addition, the fault injection policy is attached to route A. Route B does not attach any extensionRef RouteOptions. Because of that, the CORS policy 1 from the targetRefs RouteOption is attached to route B.

Multiple targetRefs RouteOptions

If you create multiple RouteOption resources and attach them to the same route by using the targetRefs option, only the RouteOption that was first created is applied.

In the following image, you attach two RouteOption resources to route A. One adds request headers and the other one a fault injection policy. Because only one RouteOption can be applied to a route via targetRefs at any given time, only the policy that is created first is enforced (policy 1).

Multiple ExtensionRef RouteOptions

If you attach multiple RouteOption resources to an HTTPRoute by using the ExtensionRef filter, the RouteOptions are merged as follows:

• RouteOptions that define different top-level policies, such as a rewrite and a fault injection policy, are merged and applied to the route.
• RouteOptions that define the same top-level policies, such as two header manipulation policies, are not merged. Instead, the RouteOption that is referenced first is applied to the route. The same top-level policies if specified in subsequent RouteOptions are ignored.

In the following image, you have an HTTPRoute that defines two routes (route A and route B). Route A attaches two RouteOption resources via the ExtensionRef filter that specify the same top-level header manipulation policy. For route B, two RouteOption resources with different top-level policies (fault injection and CORS) are applied via the ExtensionRef filter.

Because you cannot apply two ExtensionRef RouteOptions with the same top-level policies, only the policy that is referenced first (policy 1, request header foo) is enforced. The request header bar in policy 2 is ignored. For route B, both the CORS and fault injection policies are applied, because these RouteOption resources define different top-level 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.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.