Configuration schema
Configuration reference for agentgateway configuration schema.
Generated from the agentgateway JSON schema.
Global Config
Top-level settings for DNS, admin, networking, observability, and session management.
Schema type: RawConfig
Global Config can be configured in the following sections:
configYou can configure the following fields:
| Field | Type | Description |
|---|---|---|
additionalTrustDomains | string | Comma-separated list of additional SPIFFE trust domains accepted on inbound HBONE connections. The local trust_domain is always implicitly included. |
adminAddr | string | Admin UI address in the format “ip:port” |
backend | BackendConfig | Default: map[connectTimeout:10s keepalives:map[enabled:true interval:3m0s retries:9 time:3m0s] poolIdleTimeout:1m30s poolMaxSize:<nil>]. |
caAddress | string | |
caAuthToken | string | |
clusterId | string | |
connectionMinTerminationDeadline | string | |
connectionTerminationDeadline | string | |
dns | RawDnsConfig | DNS resolver settings. |
enableIpv6 | boolean | |
gateway | string | |
hbone | RawHBONE | |
localXdsPath | string | Local XDS path. If not specified, the current configuration file will be used. |
logging | RawLogging | |
mcp | RawMcpConfig | MCP gateway settings. |
metrics | RawMetrics | |
namespace | string | |
network | string | |
readinessAddr | string | Readiness probe server address in the format “ip:port” |
serviceAccount | string | |
session | RawSession | Configuration for stateful session management |
skipValidateTrustDomain | boolean | When true, skip SPIFFE trust-domain verification on inbound HBONE connections. |
statsAddr | string | Stats/metrics server address in the format “ip:port” |
tracing | RawTracing | |
trustDomain | string | |
workerThreads | string | |
xdsAddress | string | |
xdsAuthToken | string |
Binds & Listeners
Configure ports, listeners, hostnames, TLS, and routing.
Schema type: LocalBind
Binds & Listeners can be configured in the following sections:
binds[]You can configure the following fields:
| Field | Type | Description |
|---|---|---|
listeners | array of LocalListener | |
port | integer | |
tunnelProtocol | TunnelProtocol | Default: direct. |
Listener
Configure a listener within a bind, including hostname, protocol, TLS, and routes.
Schema type: LocalListener
Listener can be configured in the following sections:
binds[].listeners[]You can configure the following fields:
| Field | Type | Description |
|---|---|---|
hostname | string | Can be a wildcard |
name | string | |
namespace | string | |
policies | LocalGatewayPolicy | |
protocol | LocalListenerProtocol | |
routes | array of LocalRoute | |
tcpRoutes | array of LocalTCPRoute | |
tls | LocalTLSServerConfig |
Route
Define an HTTP route with matching rules, backends, and inline policies.
Schema type: LocalRoute
Route can be configured in the following sections:
binds[].listeners[].routes[]
routeGroups[].routes[]You can configure the following fields:
| Field | Type | Description |
|---|---|---|
backends | array of LocalRouteBackend | |
hostnames | array | Can be a wildcard |
matches | array of RouteMatch | Default: [map[path:map[pathPrefix:/]]]. |
name | string | |
namespace | string | |
policies | FilterOrPolicy | |
ruleName | string |
Backends
Define backend targets including AI providers, static hosts, and load balancing.
Schema type: FullLocalBackend
Backends can be configured in the following sections:
backends[]You can configure the following fields:
| Field | Type | Description |
|---|---|---|
name | string | |
policies | LocalBackendPolicies |
Backend TLS
TLS settings for backend connections.
Schema type: LocalBackendTLS
Backend TLS can be configured in the following sections:
backends[].policies.backendTLS
binds[].listeners[].policies.extAuthz.policies.backendTLS
binds[].listeners[].policies.extProc.policies.backendTLS
binds[].listeners[].routes[].backends[].policies.backendTLS
binds[].listeners[].routes[].policies.backendTLS
binds[].listeners[].routes[].policies.extAuthz.policies.backendTLS
binds[].listeners[].routes[].policies.extProc.policies.backendTLS
binds[].listeners[].routes[].policies.remoteRateLimit.policies.backendTLS
binds[].listeners[].tcpRoutes[].backends[].policies.backendTLS
binds[].listeners[].tcpRoutes[].policies.backendTLS
frontendPolicies.accessLog.otlp.policies.backendTLS
frontendPolicies.tracing.policies.backendTLS
llm.models[].backendTLS
llm.policies.extAuthz.policies.backendTLS
llm.policies.extProc.policies.backendTLS
mcp.policies.backendTLS
mcp.policies.extAuthz.policies.backendTLS
mcp.policies.extProc.policies.backendTLS
mcp.policies.remoteRateLimit.policies.backendTLS
mcp.targets[].policies.backendTLS
policies[].policy.backendTLS
policies[].policy.extAuthz.policies.backendTLS
policies[].policy.extProc.policies.backendTLS
policies[].policy.remoteRateLimit.policies.backendTLS
routeGroups[].routes[].backends[].policies.backendTLS
routeGroups[].routes[].policies.backendTLS
routeGroups[].routes[].policies.extAuthz.policies.backendTLS
routeGroups[].routes[].policies.extProc.policies.backendTLS
routeGroups[].routes[].policies.remoteRateLimit.policies.backendTLSYou can configure the following fields:
| Field | Type | Description |
|---|---|---|
alpn | array | |
cert | string | |
hostname | string | |
insecure | boolean | |
insecureHost | boolean | |
key | string | |
root | string | |
subjectAltNames | array |
Policies
Attach reusable policies for authentication, rate limiting, authorization, and more.
Schema type: LocalPolicy
Policies can be configured in the following sections:
policies[]You can configure the following fields:
| Field | Type | Description |
|---|---|---|
name | ResourceName | |
phase | PolicyPhase | phase defines at what level the policy runs at. Gateway policies run pre-routing, while Route policies apply post-routing. Only a subset of policies are eligible as Gateway policies. In general, norma… Default: route. |
policy | FilterOrPolicy | |
target | PolicyTarget |
Policy & Filter Fields
All available policy and filter fields that can be used inline on routes, listeners, gateways, and backends.
Schema type: FilterOrPolicy
Policy & Filter Fields can be configured in the following sections:
binds[].listeners[].routes[].policies
mcp.policies
policies[].policy
routeGroups[].routes[].policiesYou can configure the following fields:
| Field | Type | Description |
|---|---|---|
a2a | A2aPolicy | Mark this traffic as A2A to enable A2A processing and telemetry. |
ai | Policy | Mark this as LLM traffic to enable LLM processing. |
apiKey | LocalAPIKeys | Authenticate incoming requests using API Keys |
authorization | Authorization | Authorization policies for HTTP access. |
backendAuth | BackendAuth | Authenticate to the backend. |
backendTLS | LocalBackendTLS | Send TLS to the backend. |
backendTunnel | Tunnel | Tunnel to the backend. |
basicAuth | LocalBasicAuth | Authenticate incoming requests using Basic Authentication with htpasswd. |
cors | CorsSerde | Handle CORS preflight requests and append configured CORS headers to applicable requests. |
csrf | Csrf | Handle CSRF protection by validating request origins against configured allowed origins. |
directResponse | DirectResponse | Directly respond to the request with a static response. |
extAuthz | ExtAuthz | Authenticate incoming requests by calling an external authorization server. |
extProc | ExtProc | Extend agentgateway with an external processor |
jwtAuth | LocalJwtConfig | Authenticate incoming JWT requests. |
localRateLimit | array of RateLimitSpec | Rate limit incoming requests. State is kept local. |
mcpAuthentication | LocalMcpAuthentication | Authentication for MCP clients. |
mcpAuthorization | McpAuthorization | Authorization policies for MCP access. |
oidc | LocalOidcConfig | Authenticate incoming browser requests with OIDC authorization code flow. |
remoteRateLimit | RemoteRateLimit | Rate limit incoming requests. State is managed by a remote server. |
requestHeaderModifier | HeaderModifier | Headers to be modified in the request. |
requestMirror | RequestMirror | Mirror incoming requests to another destination. |
requestRedirect | RequestRedirect | Directly respond to the request with a redirect. |
responseHeaderModifier | HeaderModifier | Headers to be modified in the response. |
retry | Policy3 | Retry matching requests. |
timeout | Policy2 | Timeout requests that exceed the configured duration. |
transformations | LocalTransformationConfig | Modify requests and responses |
urlRewrite | UrlRewrite | Modify the URL path or authority. |
CORS
Cross-Origin Resource Sharing (CORS) policy configuration.
Schema type: CorsSerde
CORS can be configured in the following sections:
binds[].listeners[].routes[].policies.cors
mcp.policies.cors
policies[].policy.cors
routeGroups[].routes[].policies.corsYou can configure the following fields:
| Field | Type | Description |
|---|---|---|
allowCredentials | boolean | |
allowHeaders | array | |
allowMethods | array | |
allowOrigins | array | |
exposeHeaders | array | |
maxAge | string |
Rate Limiting
Rate limit configuration for controlling request throughput.
Schema type: RateLimitSpec
Rate Limiting can be configured in the following sections:
binds[].listeners[].routes[].policies.localRateLimit[]
mcp.policies.localRateLimit[]
policies[].policy.localRateLimit[]
routeGroups[].routes[].policies.localRateLimit[]You can configure the following fields:
| Field | Type | Description |
|---|---|---|
fillInterval | string | |
maxTokens | integer | |
tokensPerFill | integer | |
type | RateLimitType | Default: requests. |
OIDC Authentication
Browser-based OIDC authentication policy using authorization code flow.
Schema type: LocalOidcConfig
OIDC Authentication can be configured in the following sections:
binds[].listeners[].policies.oidc
binds[].listeners[].routes[].policies.oidc
llm.policies.oidc
mcp.policies.oidc
policies[].policy.oidc
routeGroups[].routes[].policies.oidcBrowser-based OIDC authentication policy. Explicit mode is still OIDC: it supplies provider metadata manually instead of using discovery. Unauthenticated non-callback requests always redirect to the provider login flow. Routes that need non-redirect authentication behavior should use a different auth policy.
You can configure the following fields:
| Field | Type | Description |
|---|---|---|
authorizationEndpoint | string | Authorization endpoint used to start the browser login flow. |
clientId | string | OAuth2 client identifier used for authorization and token exchange. |
clientSecret | string | OAuth2 client secret used for token exchange. |
discovery | FileInlineOrRemote | Optional discovery document override. If omitted, discovery uses ${issuer}/.well-known/openid-configuration. |
issuer | string | Issuer used for discovery and ID token validation. |
jwks | FileInlineOrRemote | JWKS source used to validate returned ID tokens. |
redirectURI | string | Absolute callback URI handled by the gateway. This policy always redirects unauthenticated non-callback requests back through this login flow. |
scopes | array | Additional OAuth2 scopes to request. openid is always included. |
tokenEndpoint | string | Token endpoint used to exchange the authorization code. |
tokenEndpointAuth | TokenEndpointAuth | Token endpoint client authentication method for explicit provider configuration. Discovery mode derives this from provider metadata. Explicit mode defaults to clientSecretBasic when omitted. |
Frontend Policies
Gateway-wide policies applied to all incoming traffic.
Schema type: LocalFrontendPolicies
Frontend Policies can be configured in the following sections:
frontendPoliciesYou can configure the following fields:
| Field | Type | Description |
|---|---|---|
accessLog | LoggingPolicy | Settings for request access logs. |
http | HTTP2 | Settings for handling incoming HTTP requests. |
networkAuthorization | NetworkAuthorization | CEL authorization for downstream network connections. |
proxyProtocol | Proxy | Enable downstream PROXY protocol handling on this gateway or port, including version matching and whether PROXY headers are required or optional. |
tcp | TCP2 | Settings for handling incoming TCP connections. |
tls | TLS | Settings for handling incoming TLS connections. |
tracing | TracingConfig |
LLM Gateway
Configure the LLM gateway with models, providers, and prompt guards.
Schema type: LocalLLMConfig
LLM Gateway can be configured in the following sections:
llmYou can configure the following fields:
| Field | Type | Description |
|---|---|---|
models | array of LocalLLMModels | models defines the set of models that can be served by this gateway. The model name refers to the model in the users request that is matched; the model sent to the actual LLM can be overridden on a pe… |
policies | LocalLLMPolicy | policies defines policies for handling incoming requests, before a model is selected |
port | integer |
LLM Models
Configure an LLM model with provider, prompt guards, and caching.
Schema type: LocalLLMModels
LLM Models can be configured in the following sections:
llm.models[]You can configure the following fields:
| Field | Type | Description |
|---|---|---|
backendTLS | LocalBackendTLS | backendTLS configures TLS when connecting to the LLM provider. |
backendTunnel | Tunnel | backendTunnel configures tunneling when connecting to the LLM provider. |
defaults | object | defaults allows setting default values for the request. If these are not present in the request body, they will be set. To override even when set, use overrides. |
guardrails | PromptGuard | guardrails to apply to the request or response |
health | LocalHealthPolicy | health configures outlier detection for this model backend. |
matches | array of LLMRouteMatch | matches specifies the conditions under which this model should be used in addition to matching the model name. |
name | string | name is the name of the model we are matching from a users request. If params.model is set, that will be used in the request to the LLM provider. If not, the incoming model is used. |
overrides | object | overrides allows setting values for the request, overriding any existing values |
params | LocalLLMParams | params customizes parameters for the outgoing request |
provider | LocalModelAIProvider | provider of the LLM we are connecting too |
requestHeaders | HeaderModifier | requestHeaders modifies headers in requests to the LLM provider. |
responseHeaders | HeaderModifier | responseHeaders modifies headers in responses from the LLM provider. |
transformation | object | transformation allows setting values from CEL expressions for the request, overriding any existing values. |
LLM Parameters
Parameters for LLM model routing, failover, and spending limits.
Schema type: LocalLLMParams
LLM Parameters can be configured in the following sections:
llm.models[].paramsYou can configure the following fields:
| Field | Type | Description |
|---|---|---|
apiKey | SecretFromFile | An API key to attach to the request. If unset this will be automatically detected from the environment. |
awsRegion | string | |
azureApiVersion | string | For Azure: the API version to use |
azureProjectName | string | For Azure: the Foundry project name (required for foundry resource type) |
azureResourceName | string | For Azure: the resource name of the deployment |
azureResourceType | AzureResourceType | For Azure: the type of Azure endpoint (openAI or foundry) |
hostOverride | string | Override the upstream host for this provider. |
model | string | The model to send to the provider. If unset, the same model will be used from the request. |
pathOverride | string | Override the upstream path for this provider. |
pathPrefix | string | Override the default base path prefix for this provider. |
tokenize | boolean | Whether to tokenize the request before forwarding it upstream. |
vertexProject | string | |
vertexRegion | string |
MCP Gateway
Configure the MCP gateway with targets, authentication, and fan-out behavior.
Schema type: LocalSimpleMcpConfig
MCP Gateway can be configured in the following sections:
mcpYou can configure the following fields:
| Field | Type | Description |
|---|---|---|
failureMode | FailureMode4 | Behavior when one or more MCP targets fail to initialize or fail during fanout. Defaults to failClosed. |
policies | FilterOrPolicy | |
port | integer | |
prefixMode | McpPrefixMode | |
statefulMode | McpStatefulMode | |
targets | array of LocalMcpTarget |
MCP Backend
Configure an MCP backend target with transport and authentication.
Schema type: LocalMcpBackend
You can configure the following fields:
| Field | Type | Description |
|---|---|---|
failureMode | FailureMode4 | Behavior when one or more MCP targets fail to initialize or fail during fanout. Defaults to failClosed. |
prefixMode | McpPrefixMode | |
statefulMode | McpStatefulMode | |
targets | array of LocalMcpTarget |
MCP Authentication
Authentication settings for MCP clients using OAuth/OIDC.
Schema type: LocalMcpAuthentication
MCP Authentication can be configured in the following sections:
binds[].listeners[].routes[].policies.mcpAuthentication
mcp.policies.mcpAuthentication
policies[].policy.mcpAuthentication
routeGroups[].routes[].policies.mcpAuthenticationYou can configure the following fields:
| Field | Type | Description |
|---|---|---|
audiences | array | |
authorizationLocation | AuthorizationLocation | Default: map[header:map[name:authorization prefix:Bearer ]]. |
issuer | string | |
jwks | FileInlineOrRemote | |
jwtValidationOptions | JWTValidationOptions | |
mode | McpAuthenticationMode | Default: strict. |
provider | McpIDP | |
resourceMetadata | ResourceMetadata |
Tracing
Configuration for distributed tracing with OpenTelemetry.
Schema type: TracingConfig
Tracing can be configured in the following sections:
frontendPolicies.tracingConfiguration for dynamic tracing policy
You can configure the following fields:
| Field | Type | Description |
|---|---|---|
attributes | OrderedStringMap_Expression | Span attributes to add, keyed by attribute name. |
clientSampling | Expression | Optional per-policy override for client sampling. If set, overrides global config for requests that use this frontend policy. |
path | string | Default: /v1/traces. |
policies | SimpleLocalBackendPolicies | Policies to connect to the backend |
protocol | TracingProtocol | Default: grpc. |
randomSampling | Expression | Optional per-policy override for random sampling. If set, overrides global config for requests that use this frontend policy. |
remove | array | Attribute keys to remove from the emitted span attributes. This is applied before attributes are evaluated/added, so it can be used to drop default attributes or avoid duplication. |
resources | OrderedStringMap_Expression | Resource attributes to add to the tracer provider (OTel Resource). This can be used to set things like service.name dynamically. |
