Policies

The AgentgatewayPolicy custom resource lets you apply traffic management, security, observability, and backend connection policies to your agentgateway resources.

Policy sections

Each AgentgatewayPolicy has three top-level sections in the spec field that control different stages of request processing. You can include one or more of these sections in a single policy.

Policy processing order

Agentgateway processes each request through four phases in the following order. You cannot change the phase order, but you can control which filters run in each phase by configuring the appropriate policy sections.

  graph LR
    frontend

    subgraph frontend ["Phase 1: Frontend"]
        fe_fields["tcp · tls · http<br/>accessLog · tracing"]
    end

    frontend --> prerouting

    subgraph prerouting ["Phase 2: PreRouting traffic"]
        pr["Auth (JWT, basic, API key)<br/>ExtAuth<br/>ExtProc<br/>Transformation"]
    end

    prerouting -->|route selection| postrouting

    subgraph postrouting ["Phase 3: PostRouting traffic"]
        po["CORS<br/>Auth (JWT, basic, API key)<br/>ExtAuth<br/>Rate limiting<br/>ExtProc<br/>Transformation<br/>CSRF<br/>Headers<br/>Host rewrite<br/>Direct response"]
    end

    postrouting --> backend

    subgraph backend ["Phase 4: Backend"]
        be_fields["tls · tcp · http · tunnel<br/>auth · transformation<br/>health · ai · mcp"]
    end

1. Frontend policies: Control how the gateway accepts incoming connections, including TLS settings, TCP configuration, and access logging. Frontend policies apply at the gateway level before any routing decisions.
2. PreRouting traffic policies: Run before route selection. Only a subset of traffic filters is available in the PreRouting phase. See PreRouting filters.
3. PostRouting traffic policies: Run after route selection. PostRouting is the default phase for traffic policies and supports all traffic filters.
4. Backend policies: Run when the gateway connects to the destination backend, including backend TLS, authentication, and health checking.

Within each phase, agentgateway merges all applicable policies with a shallow field-level merge. If two policies configure different fields, both apply. For example, if one policy sets transformation and another sets extAuth, both filters run. If two policies configure the same field, the higher-precedence policy takes effect. For details, see merge precedence.

Traffic filter execution order

Within the traffic phase (both PreRouting and PostRouting), filters execute in a fixed order. You cannot change this order.

PreRouting filters

The PreRouting phase supports only the following filters, in order of execution:

1. jwtAuthentication
2. basicAuthentication
3. apiKeyAuthentication
4. extAuth
5. extProc
6. transformation

To run a filter in the PreRouting phase, set phase: PreRouting on the traffic policy. PreRouting policies can only target a Gateway or ListenerSet.

Adjusting execution order with phases

You can use the PreRouting phase to run certain filters earlier in the request lifecycle. For example, to run external processing before rate limiting, configure an extProc policy with the PreRouting phase, and a separate rateLimit policy with the default PostRouting phase. External processing then runs during PreRouting (before route selection), and rate limiting runs during PostRouting (after route selection).

Policy targeting

Each policy section can only target specific Kubernetes resource types. If you set a targetRef or targetSelector to an invalid resource type for the policy section, the Kubernetes API server rejects the request with a validation error. Invalid targeting is not silently ignored.

Targeting rules

The following table shows which resource types each policy section can target.

Backend section restrictions

Some backend sub-fields have additional targeting restrictions.

Traffic phase restrictions

The traffic section supports an optional phase field that controls when the policy runs. When you set the phase to PreRouting, the policy runs before route selection. Because of this timing, PreRouting policies can only target a Gateway or ListenerSet.

For more information, see Policy processing order and PreRouting filters.

Policy merging

When multiple policies target the same resource, agentgateway merges the policy sections on a field level (shallow merge). If two policies set the same field, the more specific policy takes precedence.

Merge precedence

Each policy section follows a different precedence order based on the specificity of the target. The more specific the target, the higher the precedence.

For example, if a Gateway-level policy sets backend.tcp and backend.tls, and a Backend-level policy sets backend.tls, the effective policy uses tcp from the Gateway policy and tls from the Backend policy.

Example guides

Check out the following sections for policy examples.