TrafficPolicy

Use a TrafficPolicy resource to attach policies to one, multiple, or all routes in an HTTPRoute resource, or all the routes that a Gateway serves.

Policy attachment

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

All HTTPRoute routes

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

The following example TrafficPolicy resource specifies transformation rules that are applied to all routes in the httpbin HTTPRoute resource.

apiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata:
  name: transformation
  namespace: httpbin
spec:
  targetRefs: 
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: httpbin
  transformation:
    response:
      set:
      - name: x-kgateway-response
        value: '{{ request_header("x-kgateway-request") }}' 

Individual route

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 TrafficPolicy resource that defines a transformation rule. Note that the spec.targetRef field is not set. Because of that, the TrafficPolicy policy does not apply until it is referenced in an HTTPRoute by using the ExtensionRef filter.

apiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata:
  name: transformation
  namespace: httpbin
spec:
  transformation:
    response:
      set:
      - name: x-kgateway-response
        value: '{{ request_header("x-kgateway-request") }}' 

To apply the policy to a particular route, you use the ExtensionRef filter on the desired HTTPRoute route. In the following example, the TrafficPolicy 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-policy
  namespace: httpbin
spec:
  parentRefs:
  - name: http
    namespace: kgateway-system
  hostnames:
    - TrafficPolicy.example
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /anything/path1
    filters:
      - type: ExtensionRef
        extensionRef:
          group: gateway.kgateway.dev
          kind: TrafficPolicy
          name: transformation
    backendRefs:
    - name: httpbin
      port: 8000
  - matches:
    - path:
        type: PathPrefix
        value: /anything/path2
    backendRefs:
      - name: httpbin
        port: 8000

HTTPRoute rule

Instead of using the extensionRef filter to apply a policy to a specific route, you can attach a TrafficPolicy to an HTTPRoute rule by using the TrafficPolicy’s targetRefs.sectionName option.

You can also use this attachment option alongside the extensionRef filter. However, policies that are attached via the extensionRef filter take precedence over policies that are attached via the targetRefs.sectionName option. For more information, see Conflicting policies and merging rules.

The following HTTPRoute defines two HTTPRoute rules that both route traffic to the httpbin app.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin
  namespace: httpbin
spec:
  parentRefs:
  - name: http
    namespace: kgateway-system
  hostnames:
    - TrafficPolicy.example
  rules:
  - name: rule0
    matches:
    - path:
        type: PathPrefix
        value: /anything/path1
    backendRefs:
    - name: httpbin
      port: 8000
  - name: rule1
    matches:
    - path:
        type: PathPrefix
        value: /anything/path2
    backendRefs:
      - name: httpbin
        port: 8000
EOF

To apply a TrafficPolicy to a specific HTTPRoute rule (rule1), use the TrafficPolicy’s targetRefs.sectionName option as shown in the following example.

kubectl apply -f- <<EOF
apiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata:
  name: local-ratelimit
  namespace: kgateway-system
spec:
  targetRefs: 
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: httpbin
    sectionName: rule1
  rateLimit:
    local:
      tokenBucket:
        maxTokens: 1
        tokensPerFill: 1
        fillInterval: 100s
EOF

Gateway

Some policies, such as a local rate limiting policy, can be applied to all the routes that the Gateway serves. This way, you can apply gateway-level rules and do not have to keep track of new HTTPRoutes that are attached to the Gateway in your environment.

To attach a TrafficPolicy to a Gateway, you simply use the targetRefs section in the TrafficPolicy to reference the Gateway you want the policy to apply to as shown in the following example.

apiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata:
  name: local-ratelimit
  namespace: kgateway-system
spec:
  targetRefs: 
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: http
  rateLimit:
    local:
      tokenBucket:
        maxTokens: 1
        tokensPerFill: 1
        fillInterval: 100s

Gateway listener

Instead of applying a TrafficPolicy to all the routes that the Gateway serves, you can select specific Gateway listeners by using the targetRefs.sectionName option.

The following Gateway resource defines two listeners, an HTTP (http) and HTTPS (https) listener.

kind: Gateway
apiVersion: gateway.networking.k8s.io/v1
metadata:
  name: http
  namespace: kgateway-system
spec:
  gatewayClassName: kgateway
  listeners:
  - name: http
    protocol: HTTP
    port: 8080
    allowedRoutes:
      namespaces:
        from: All
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
        - name: https
          kind: Secret
    allowedRoutes:
      namespaces:
        from: All

To apply the policy to only the https listener, you specify the listener name in the spec.targetRefs.sectionName field in the TrafficPolicy resource as shown in the following example.

apiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata:
  name: local-ratelimit
  namespace: kgateway-system
spec:
  targetRefs: 
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: http
    sectionName: https
  rateLimit:
    local:
      tokenBucket:
        maxTokens: 1
        tokensPerFill: 1
        fillInterval: 100s

Policy priority and merging rules

If you apply multiple TrafficPolicies by using different attachment options, policies are merged based on specificy and priority. The following rules apply:

• If you apply multiple TrafficPolicies that define the same top-level policy, the policies are not merged and only the oldest policy is enforced. Policies with a later timestamp are ignored.
• TrafficPolicies that define different top-level policies are merged and are enforced in combination.
• In addition to the timestamp, the attachment option of a policy determines the policy priority. In general, more specific policy targets have higher priority and take precedence over less specific policies. For example, a policy targeting an individual route has higher priority than a policy targeting all the routes in an HTTPRoute resource. However, keep in mind that these rules might be different in a route delegation setup. For more information, see Policy inheritance and overrides in delegation setups.
• Lower priority policies can augment higher priority policies by defining other top-level policies. For example, if you already attached a local rate limiting policy to a Gateway listener by using the targetRefs.sectionName option, you can add another TrafficPolicy that defines a transformation policy and apply that policy to the entire Gateway.
• Native Kubernetes Gateway API policies have higher priority than any kgateway policies that must be attached via the targetRefs or extensionRef option.

Priority order

Review the following Gateway and HTTPRoute policy priorities, sorted from highest to lowest.

Gateway:

HTTPRoute:

Policy inheritance and overrides in delegation setups

The way policies are inherited along the route delegation chain depends on the type of policy that you want to apply.

Native Gateway API policies

Kubernetes Gateway API policies that can be defined on an HTTPRoute, such as timeouts and retries, are inherited as follows:

• Policies that are defined on a parent HTTPRoute are automatically inherited by all child or grandchild HTTPRoutes.
• If the child or grandchild HTTPRoute defines a policy, this policy takes precedence and overrides the policy that is set on the parent.

For an example, see the policy inheritance guide for Native Gateway API policies.

kgateway policies

The following policy inheritance and override rules apply for TrafficPolicies:

• Policies that are defined in a TrafficPolicy resource and applied to a parent HTTPRoute resource are automatically inherited by all child and grandchild HTTPRoutes along the route delegation chain.
• If the TrafficPolicy applies to a child or grandchild HTTPRoute and defines a top-level policy that is different from the policy that is defined on the parent, the policies are merged and both the parent and child/grandchild policies are applied. For example, if the parent applies a rate limiting policy and the child applies a transformation policy, both policies are applied.
• If the TrafficPolicy applies to a child or grandchild HTTPRoute and defines the same top-level policy, the policy of the parent takes precedence and the policy on the child/grandchild is ignored. Note that you can add the delegation.kgateway.dev/inherited-policy-priority: PreferChild annotation to the parent HTTPRoute to allow a child/grandchild HTTPRoute to override the same top-level policies. In such cases, the child policy takes precedence and the parent policy is ignored.
• If you used multiple attachment options to apply a TrafficPolicy with the same top-level policy to a parent or child HTTPRoute, only the policy with the highest priority is applied. The priority is determined by the attachment option that you chose. The following options are sorted from highest to lowest.
  • Policy defined in a TrafficPolicy and attached to an HTTPRoute via the HTTPRoute’s extensionRef filter
  • Policy defined in a TrafficPolicy resource and attached to an HTTPRouteRule via the targetRef.sectionName option
  • Policy defined in a TrafficPolicy resource and attached to an HTTPRoute via the targetRef option

For an example, see the policy inheritance guide for kgateway policies.