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:

config

You 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.backendTLS

You can configure the following fields:

Field	Type	Description
`alpn`	array
`cert`	string
`hostname`	string
`insecure`	boolean
`insecureHost`	boolean
`key`	string
`keyExchangeGroups`	array of `KeyExchangeGroup`	Key exchange groups allowed for negotiating TLS.
`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[].policies

You 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`	`LocalExplicitOrConditional`	Directly respond to the request with a static response.
`extAuthz`	`LocalExplicitOrConditional3`	Authenticate incoming requests by calling an external authorization server.
`extProc`	`LocalExplicitOrConditional4`	Extend agentgateway with an external processor
`jwtAuth`	`LocalJwtConfig`	Authenticate incoming JWT requests.
`localRateLimit`	`LocalRateLimitPolicy`	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`	`LocalExplicitOrConditional2`	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`	`LocalExplicitOrConditional5`	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.cors

You 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.oidc

Browser-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:

frontendPolicies

You 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:

llm

You 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[].params

You 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:

mcp

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`.
`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.mcpAuthentication

You 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.tracing

Configuration 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.

Was this page helpful?

Configuration schema

Global Config

Binds & Listeners

Listener

Route

Backends

Backend TLS

Policies

Policy & Filter Fields

CORS

Rate Limiting

OIDC Authentication

Frontend Policies

LLM Gateway

LLM Models

LLM Parameters

MCP Gateway

MCP Backend

MCP Authentication

Tracing

What could be improved?