Static configuration

All fields under the config key — global settings read once at startup including logging, tracing, DNS, sessions, and XDS.

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

config.adminAddr · string

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"

config.statsAddr · string

Address for the stats and metrics server in ip:port format. Exposes Prometheus-compatible metrics.

Example: "0.0.0.0:15020"

config.readinessAddr · string

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"

config.workerThreads · number

Number of worker threads for handling requests. Defaults to the number of logical CPUs when not set.

config.enableIpv6 · boolean

Enable IPv6 support. When true, the DNS resolver defaults to querying both IPv4 and IPv6 address families. See also config.dns.lookupFamily.

config.localXdsPath · string

Override the path used for local XDS configuration. When not set, the current configuration file is used as the local XDS source.

config.connectionTerminationDeadline · string

Maximum time to wait for in-flight connections to finish draining on shutdown.

config.connectionMinTerminationDeadline · string

Minimum time to wait before forcing connection termination during shutdown.

DNS settings

config.dns · object

DNS resolver configuration.

Show config.dns fields

config.dns.lookupFamily · string

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.

config.dns.edns0 · boolean

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

config.session · object

Configuration for stateful session management.

Show config.session fields

config.session.key · string

The AES-256-GCM key used to encrypt and sign session tokens. When not set, sessions are not encrypted.

Generate a key with:

openssl rand -hex 32

Keep this value secret. Anyone with this key can forge valid session tokens.

Logging

config.logging · object

Controls log output format, verbosity, and field customization.

Show config.logging fields

config.logging.level · string

Minimum log level to emit. Accepted values: trace, debug, info, warn, error.

Defaults to info.

config.logging.format · string

Log output format. Accepted values:

• text — Human-readable format. Default.
• json — Structured JSON, suitable for log aggregation pipelines.

config.logging.filter · string

Fine-grained log filter expression. Follows the tracing crate’s filter directive syntax, allowing per-module level control.

Example: "agentgateway=debug,tower=warn"

config.logging.fields · object

Customize the fields included in each log entry.

Show config.logging.fields

config.logging.fields.remove · string[]

List of field names to remove from log output.

config.logging.fields.add · object

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.

config.tracing · object

OpenTelemetry tracing configuration.

Show config.tracing fields

config.tracing.otlpEndpoint · string

The OTLP exporter endpoint to send traces to.

Example: "http://otel-collector:4317"

config.tracing.otlpProtocol · string

The OTLP transport protocol. Accepted values: grpc, http/protobuf, http/json.

config.tracing.path · string

OTLP HTTP path for trace export. Defaults to /v1/traces.

config.tracing.randomSampling · string

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 · string

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

config.tracing.headers · object

Additional HTTP headers to send with OTLP export requests. Useful for authentication with managed observability backends.

config.tracing.fields · object

Customize trace span attributes.

Show config.tracing.fields

config.tracing.fields.remove · string[]

Attribute names to remove from all spans.

config.tracing.fields.add · object

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

config.metrics · object

Prometheus metrics configuration.

Show config.metrics fields

config.metrics.remove · string[]

Names of metric series to remove from the metrics output entirely.

config.metrics.fields · object

Customize metric label fields.

Show config.metrics.fields

config.metrics.fields.add · object

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.

config.backend · object

Global backend connection settings.

Show config.backend fields

config.backend.connectTimeout · string

Maximum time to wait when establishing a new connection to an upstream backend. Formatted as a duration string.

Example: "10s"

config.backend.poolIdleTimeout · string

Maximum duration to keep an idle connection alive in the pool before closing it.

config.backend.poolMaxSize · number

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 · object

TCP keepalive settings for backend connections.

Show config.backend.keepalives fields

config.backend.keepalives.enabled · boolean

Enable TCP keepalives on backend connections.

config.backend.keepalives.time · string

Time a connection must be idle before sending the first keepalive probe.

config.backend.keepalives.interval · string

Time between successive keepalive probes.

config.backend.keepalives.retries · number

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.

config.hbone · object

HBONE HTTP/2 tunnel settings.

Show config.hbone fields

config.hbone.windowSize · number

HTTP/2 stream-level flow control window size in bytes.

config.hbone.connectionWindowSize · number

HTTP/2 connection-level flow control window size in bytes.

config.hbone.frameSize · number

Maximum HTTP/2 frame size in bytes.

config.hbone.poolMaxStreamsPerConn · number

Maximum number of concurrent HTTP/2 streams per HBONE connection.

config.hbone.poolUnusedReleaseTimeout · string

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.

config.xdsAddress · string

Address of the XDS control plane server.

Example: "grpc://xds-server:15010"

config.xdsAuthToken · string

Authentication token sent to the XDS server.

config.caAddress · string

Address of the certificate authority (CA) server for mTLS certificate issuance.

config.caAuthToken · string

Authentication token for the CA server.

config.namespace · string

Kubernetes namespace the gateway is running in. Used by the XDS and CA integrations.

config.serviceAccount · string

Kubernetes service account name. Used for identity in XDS and CA requests.

config.trustDomain · string

SPIFFE trust domain for workload identity.

config.clusterId · string

Cluster identifier reported to the XDS control plane.

config.network · string

Network identifier reported to the XDS control plane.

config.gateway · string

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