For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Targeting and merging
Learn how to target and merge policies when multiple policies apply to the same resource.
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.
targetRefs or targetSelectors must reference the same kind.Targeting rules
The following table shows which resource types each policy section can target.
| Policy section | Valid targets | sectionName | Notes |
|---|---|---|---|
frontend | Gateway | Not allowed | Applies to all listeners on the targeted Gateway. |
traffic | Gateway, HTTPRoute, GRPCRoute, ListenerSet | Optional | When targeting a Gateway, the sectionName selects a specific listener. When targeting an HTTPRoute or GRPCRoute, the sectionName selects a specific route rule. |
backend | Gateway, HTTPRoute, GRPCRoute, ListenerSet, Service, AgentgatewayBackend | Optional | When targeting a Service, the sectionName selects a specific port. When targeting an AgentgatewayBackend, the sectionName selects a specific sub-backend. |
Backend section restrictions
Some backend sub-fields have additional targeting restrictions.
| Field | Restriction |
|---|---|
backend.ai | Cannot target a Service. Use an AgentgatewayBackend instead. |
backend.mcp | Cannot target a Service. Use an AgentgatewayBackend instead. |
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). Each field is treated as an atomic unit. If two policies set the same field, the more specific policy takes precedence.
This field-level merge applies to all fields, including nested sub-fields. Each nested sub-field is treated as an atomic unit. For example, backend.ai.promptGuard and backend.ai.routes are separate atomic fields. If Policy A sets backend.ai.promptGuard and Policy B sets backend.ai.routes, both are included in the merged result. However, if both policies set the same nested sub-field such as backend.ai.promptGuard, only the higher-precedence policy’s entire value for that sub-field is used—no recursive merge occurs within nested fields.
Merge precedence
Conditional policies are selected first based on their conditions. Only the selected policies participate in merge precedence evaluation.
Each policy section follows a different precedence order based on the specificity of the target. The more specific the target, the higher the precedence.
| Section | Precedence order (lowest to highest) |
|---|---|
frontend | Field-level merge across policies that target the same Gateway. |
traffic | Gateway < Listener < Route < Route rule |
backend | Gateway < Listener < Route (targetRef) < Route rule (targetRef) < Backend (targetRef) < Backend (inline on the backend object) < Route backend ref (inline on the route) |
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.
