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”, “localhost:port”, “unix:/path/to/socket”, or “off”
`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”, “localhost:port”, “unix:/path/to/socket”, or “off”
`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”, “localhost:port”, “unix:/path/to/socket”, or “off”
`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	ALPN protocols to offer to the backend.
`cert`	string	Client certificate file to present to the backend.
`hostname`	string	Server name to use for TLS verification and SNI.
`insecure`	boolean	Skip certificate trust verification for the backend connection.
`insecureHost`	boolean	Skip hostname verification for the backend certificate.
`key`	string	Private key file for the client certificate.
`keyExchangeGroups`	array of `KeyExchangeGroup`	Key exchange groups allowed for negotiating TLS.
`root`	string	Root certificate bundle used to verify the backend certificate.
`subjectAltNames`	array	Additional subject alternative names accepted for the backend certificate.

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`	Policy name used when attaching this policy to a target.
`phase`	`PolicyPhase`	When the policy runs. Gateway policies run before route selection, while route policies run after route selection. Use route policies by default unless the policy needs to affect route selection. Default: `route`.
`policy`	`FilterOrPolicy`	Policy settings to apply to the selected target.
`target`	`PolicyTarget`	Gateway, listener, route, or backend that this policy attaches to.

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 with API keys.
`authorization`	`Authorization`	Authorization rules for incoming HTTP requests.
`backendAuth`	`BackendAuth`	Authentication credentials sent to the backend.
`backendTLS`	`LocalBackendTLS`	TLS settings used when connecting to the backend.
`backendTunnel`	`Tunnel`	Tunnel settings used when connecting to the backend.
`basicAuth`	`LocalBasicAuth`	Authenticate incoming requests with Basic Auth credentials from an htpasswd user database.
`buffer`	`Buffer`	Buffer request and response bodies.
`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`	Return a configured response instead of forwarding the request.
`extAuthz`	`LocalExplicitOrConditional3`	Authorize incoming requests by calling an external authorization service.
`extProc`	`LocalExplicitOrConditional4`	Send request and response data to an external processing service.
`jwtAuth`	`LocalJwtConfig`	Authenticate incoming requests with JWT bearer tokens.
`localRateLimit`	`LocalRateLimitPolicy`	Local rate limits for incoming requests.
`mcpAuthentication`	`LocalMcpAuthentication`	Authenticate MCP clients.
`mcpAuthorization`	`McpAuthorization`	Authorization rules for MCP requests.
`oidc`	`LocalOidcConfig`	Authenticate browser requests with OIDC authorization code flow.
`remoteRateLimit`	`LocalExplicitOrConditional2`	Remote rate limit checks for incoming requests.
`requestHeaderModifier`	`HeaderModifier`	Modify request headers before forwarding.
`requestMirror`	`RequestMirror`	Send a copy of matching requests to another backend.
`requestRedirect`	`RequestRedirect`	Return a redirect response instead of forwarding the request.
`responseHeaderModifier`	`HeaderModifier`	Modify response headers before returning to the client.
`retry`	`Policy3`	Retry matching failed upstream requests.
`timeout`	`Policy2`	Set request timeout limits.
`transformations`	`LocalExplicitOrConditional5`	Modify request and response headers, bodies, or metadata.
`urlRewrite`	`UrlRewrite`	Rewrite the request path or authority before forwarding.

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	Add `Access-Control-Allow-Credentials: true` on allowed CORS responses.
`allowHeaders`	array	Values to return in `Access-Control-Allow-Headers` for allowed preflight requests.
`allowMethods`	array	Values to return in `Access-Control-Allow-Methods` for allowed preflight requests.
`allowOrigins`	array	Request origins that receive CORS response headers. Use `*` to match any origin.
`exposeHeaders`	array	Values to return in `Access-Control-Expose-Headers` for allowed CORS responses.
`maxAge`	string	Value to return in `Access-Control-Max-Age` for allowed preflight requests.

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	How often the local bucket is refilled.
`maxTokens`	integer	Maximum number of tokens that can accumulate in the local bucket.
`tokensPerFill`	integer	Number of tokens added to the local bucket each fill interval.
`type`	`RateLimitType`	Whether this limit counts requests or LLM tokens. 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.
`connect`	`Connect`	Enable or disable downstream HTTP CONNECT handling.
`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`	Settings for exporting request traces.

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
`tls`	`LocalTLSServerConfig`

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
`auth`	`BackendAuth`	auth configures authentication 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
`passthrough`	`LocalLLMPassthrough`	passthrough controls how requests are handled. By default, requests will be parsed and translated as needed. With passthrough, they will be unmodified and optionally inspected (with `detect`). In this…
`promptCaching`	`PromptCachingConfig`	promptCaching configures cache point insertion for supported LLM providers.
`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.
`tls`	`LocalBackendTLS`	tls configures TLS when connecting to 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)
`baseUrl`	string	Base URL for the upstream provider. Expands to hostOverride, pathPrefix, and tls for https URLs.
`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`	`FailureMode5`	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`	`FailureMode5`	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	Accepted token audiences, matched against the JWT `aud` claim.
`authorizationLocation`	`AuthorizationLocation`	Where to read the JWT from in incoming MCP requests. Default: `map[header:map[name:authorization prefix:Bearer ]]`.
`clientId`	string	OAuth client ID advertised to MCP clients when needed.
`issuer`	string	Expected token issuer, matched against the JWT `iss` claim.
`jwks`	`FileInlineOrRemote`	JSON Web Key Set used to verify token signatures. Can be inline, from a file, or fetched remotely.
`jwtValidationOptions`	`JWTValidationOptions`	Claim requirements to enforce after the token signature is verified.
`mode`	`McpAuthenticationMode`	Controls whether MCP requests must include a valid JWT. Default: `strict`.
`provider`	`McpIDP`	Identity provider type used to derive MCP authorization metadata and default JWKS URLs.
`resourceMetadata`	`ResourceMetadata`	Protected resource metadata returned to MCP clients.

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	OTLP HTTP path used to export traces. Default: `/v1/traces`.
`policies`	`SimpleLocalBackendPolicies`	Backend policies used when exporting traces.
`protocol`	`TracingProtocol`	OTLP protocol used to export traces. Defaults to HTTP. 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.

Schema validation

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?