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.

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

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. Because the httpbin HTTPRoute resource is referenced in the spec.targetRefs section, the transformation rules are applied to all routes in that 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-solo-response
        value: '{{ request_header("x-solo-request") }}' 

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 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-solo-response
        value: '{{ request_header("x-solo-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

Option 3: Attach the policy to a Gateway (#attach-to-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.

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: Gateway
    name: http
  rateLimit:
    local:
      tokenBucket:
        maxTokens: 1
        tokensPerFill: 1
        fillInterval: 100s
EOF

Conflicting policies and merging rules

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

ExtensionRef vs. targetRefs

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

Note that the targetRefs TrafficPolicy resource can augment the extensionRef TrafficPolicy if it specifies different top-level policies.

Multiple targetRefs TrafficPolicies

If you create multiple TrafficPolicy resources and attach them to the same HTTPRoute by using the targetRefs option, only the TrafficPolicy that was last created is applied. To apply multiple policies to the same route, define the rules in the same TrafficPolicy.

If you create multiple TrafficPolicy resources and attach one to a Gateway and one to an HTTPRoute, the policy is applied as follows:

• The TrafficPolicy that is applied to the HTTPRoute takes precedence over the TrafficPolicy that is applied to the Gateway. This means that the HTTPRoutes routes are not affected by the gateway-level policy.
• The TrafficPolicy that is applied to the Gateway is applied to all other routes that the Gateway serves.

Multiple ExtensionRef TrafficPolicies

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

• TrafficPolicies that define different top-level policies are merged and applied to the route.
• TrafficPolicies that define the same top-level policies, such as two transformation policies, are not merged. Instead, the TrafficPolicy that is referenced last is applied to the route.