Static configuration lives under the top-level config key in your YAML or JSON file. These fields are read exactly once when the process starts. Changing them requires a restart — they are not dynamically reloaded.
config : adminAddr : "0.0.0.0:15000" statsAddr : "0.0.0.0:15020" readinessAddr : "0.0.0.0:15021" workerThreads : 4 logging : level : info format : json tracing : otlpEndpoint : http://otel-collector:4317 randomSampling : "0.1" dns : lookupFamily : Auto
Top-level fields Address for the admin UI server in ip:port format. The admin interface exposes runtime diagnostics and configuration inspection. Example: "0.0.0.0:15000"
Address for the stats and metrics server in ip:port format. Exposes Prometheus-compatible metrics. Example: "0.0.0.0:15020"
Address for the readiness probe server in ip:port format. Returns HTTP 200 when the gateway is ready to serve traffic. Example: "0.0.0.0:15021"
Number of worker threads for handling requests. Defaults to the number of logical CPUs when not set.
Enable IPv6 support. When true, the DNS resolver defaults to querying both IPv4 and IPv6 address families. See also config.dns.lookupFamily.
Override the path used for local XDS configuration. When not set, the current configuration file is used as the local XDS source.
config.connectionTerminationDeadline
Maximum time to wait for in-flight connections to finish draining on shutdown.
config.connectionMinTerminationDeadline
Minimum time to wait before forcing connection termination during shutdown.
DNS settings DNS resolver configuration. Controls which IP address families the DNS resolver queries for upstream connections. Accepted values:
Auto — IPv4 only when enableIpv6 is false, both when true. Default. All — Query both IPv4 and IPv6.V4Preferred — Prefer IPv4, fall back to IPv6.V4Only — Only query IPv4.V6Only — Only query IPv6. Whether to enable EDNS0 (Extension Mechanisms for DNS) in the resolver. When not set, the system-provided resolver setting is preserved. Can also be set via the DNS_EDNS0 environment variable.
Session management Configuration for stateful session management. Show config.session fields
The AES-256-GCM key used to encrypt and sign session tokens. When not set, sessions are not encrypted. Generate a key with: Keep this value secret. Anyone with this key can forge valid session tokens.
Logging Controls log output format, verbosity, and field customization. Show config.logging fields
Minimum log level to emit. Accepted values: trace, debug, info, warn, error. Defaults to info.
Log output format. Accepted values:
text — Human-readable format. Default. json — Structured JSON, suitable for log aggregation pipelines. Fine-grained log filter expression. Follows the tracing crate’s filter directive syntax, allowing per-module level control. Example: "agentgateway=debug,tower=warn"
Customize the fields included in each log entry. Show config.logging.fields
config.logging.fields.remove
List of field names to remove from log output.
config.logging.fields.add
Key-value pairs to add as static fields to every log entry.
Example: config : logging : level : debug format : json filter : "agentgateway=debug,tower=info" fields : add : environment : production region : us-east-1 remove : - thread_id
Tracing Agentgateway supports distributed tracing via OpenTelemetry. Configure the OTLP exporter and sampling behavior under config.tracing.
OpenTelemetry tracing configuration. Show config.tracing fields
config.tracing.otlpEndpoint
The OTLP exporter endpoint to send traces to. Example: "http://otel-collector:4317"
config.tracing.otlpProtocol
The OTLP transport protocol. Accepted values: grpc, http/protobuf, http/json.
OTLP HTTP path for trace export. Defaults to /v1/traces.
config.tracing.randomSampling
Controls random sampling — whether to start a new trace span when the incoming request does not already carry a trace. Accepts a float between 0.0 and 1.0 (representing 0–100%) or true/false. Defaults to false (no new traces initiated for untraced requests).
config.tracing.clientSampling
Controls client sampling — whether to start a new trace span when the incoming request does already carry a trace. Accepts a float between 0.0 and 1.0 or true/false. Defaults to true (always propagate existing traces).
Additional HTTP headers to send with OTLP export requests. Useful for authentication with managed observability backends.
Customize trace span attributes. Show config.tracing.fields
config.tracing.fields.remove
Attribute names to remove from all spans.
config.tracing.fields.add
Static key-value attributes to add to all spans.
Example: config : tracing : otlpEndpoint : http://otel-collector:4317 otlpProtocol : grpc randomSampling : "0.1" clientSampling : "true" fields : add : deployment.environment : production
Metrics Prometheus metrics configuration. Show config.metrics fields
Names of metric series to remove from the metrics output entirely.
Customize metric label fields. Show config.metrics.fields
config.metrics.fields.add
Static label key-value pairs to attach to all metrics.
Backend connection pooling These settings control how the gateway manages TCP connections to upstream backends.
Global backend connection settings. Show config.backend fields
config.backend.connectTimeout
Maximum time to wait when establishing a new connection to an upstream backend. Formatted as a duration string. Example: "10s"
config.backend.poolIdleTimeout
Maximum duration to keep an idle connection alive in the pool before closing it.
config.backend.poolMaxSize
Maximum number of connections kept in the pool per hostname. Excess connections are still created when needed but are not pooled after use. When not set, there is no limit.
config.backend.keepalives
TCP keepalive settings for backend connections. Show config.backend.keepalives fields
config.backend.keepalives.enabled
Enable TCP keepalives on backend connections.
config.backend.keepalives.time
Time a connection must be idle before sending the first keepalive probe.
config.backend.keepalives.interval
Time between successive keepalive probes.
config.backend.keepalives.retries
Number of failed keepalive probes before the connection is declared dead.
Example: config : backend : connectTimeout : 10s poolIdleTimeout : 90s poolMaxSize : 100 keepalives : enabled : true time : 30s interval : 5s retries : 3
HBONE settings HBONE (HTTP-Based Overlay Network Encapsulation) is used for encrypted tunneling between proxies.
HBONE HTTP/2 tunnel settings. HTTP/2 stream-level flow control window size in bytes.
config.hbone.connectionWindowSize
HTTP/2 connection-level flow control window size in bytes.
Maximum HTTP/2 frame size in bytes.
config.hbone.poolMaxStreamsPerConn
Maximum number of concurrent HTTP/2 streams per HBONE connection.
config.hbone.poolUnusedReleaseTimeout
How long to wait before releasing an unused HBONE connection from the pool.
XDS control plane connection Connect Agentgateway to a remote XDS control plane for centralized dynamic configuration.
Address of the XDS control plane server. Example: "grpc://xds-server:15010"
Authentication token sent to the XDS server.
Address of the certificate authority (CA) server for mTLS certificate issuance.
Authentication token for the CA server.
Kubernetes namespace the gateway is running in. Used by the XDS and CA integrations.
Kubernetes service account name. Used for identity in XDS and CA requests.
SPIFFE trust domain for workload identity.
Cluster identifier reported to the XDS control plane.
Network identifier reported to the XDS control plane.
Gateway name reported to the XDS control plane.
Example — connecting to an XDS control plane: config : xdsAddress : grpc://xds-server:15010 xdsAuthToken : my-secret-token caAddress : grpc://istiod:15012 namespace : default serviceAccount : agentgateway trustDomain : cluster.local clusterId : my-cluster
