Skip to content
Nantian Gateway

Data Plane Configuration

The data plane configuration file is located at dataplane/configs/dataplane/config.yaml. It controls every aspect of the data plane process: node identity, control plane connection, logging, access logging, runtime behavior, performance tuning, protection limits, TLS, and feature flags.

Node Identity

Section titled “Node Identity”
ParameterTypeDefaultDescription
node_idstringdp-localUnique identifier for this data plane instance
clusterstringdefaultLogical cluster name this instance belongs to

The node_id must be unique across all data plane instances connected to the same control plane. In Kubernetes, the Helm chart sets this to the pod name automatically. The cluster field groups data planes into logical clusters for multi-cluster deployments.

Control Plane Connection

Section titled “Control Plane Connection”
ParameterTypeDefaultDescription
control_plane_addrstringhttp://127.0.0.1:18080Address of the control plane gRPC server
admin_addrstring127.0.0.1:19080Address for the data plane’s own admin HTTP server

The control_plane_addr is the gRPC endpoint where the data plane connects to receive configuration snapshots. Use https:// when TLS is enabled on the control plane’s gRPC server.

The admin_addr is the data plane’s own admin HTTP server, used by the control plane for health checks and aggregation.

Logging

Section titled “Logging”

The data plane uses Rust’s tracing framework with fine-grained per-module control:

ParameterTypeDefaultDescription
log.levelstringinfo,nantian_core::connectors=offTracing filter directives
log.formatstringjsonOutput format: json or text
log.add_sourceboolfalseInclude source file and line number
log.include_targetboolfalseInclude the tracing target (Rust module path)
log.include_thread_idsboolfalseInclude thread IDs
log.include_thread_namesboolfalseInclude thread names
log.non_blockingbooltrueUse non-blocking log output
log.non_blocking_buffered_linesint65536Ring buffer capacity for non-blocking logging
log.drop_when_fullbooltrueDrop logs when the buffer is full

The level field accepts tracing filter syntax for per-module granularity: info,hyper=warn,tower=debug.

OpenTelemetry Log Export

Section titled “OpenTelemetry Log Export”
ParameterTypeDefaultDescription
log.open_telemetry.enabledboolfalseExport logs via OpenTelemetry
log.open_telemetry.endpointstring""OTLP collector endpoint
log.open_telemetry.protocolstringgrpcOTLP protocol: grpc or http
log.open_telemetry.timeoutMsint3000Export timeout in milliseconds
log.open_telemetry.insecureboolfalseUse insecure connection to the collector
log.open_telemetry.sampleRatiofloat1.0Sampling ratio (0.0 to 1.0)
log.open_telemetry.serviceNamestringnantian-dataplaneService name in exported data
log.open_telemetry.serviceNamespacestring""Service namespace in exported data

Admin Authentication

Section titled “Admin Authentication”
ParameterTypeDefaultDescription
admin_auth.bearer_tokenstring""Static bearer token for admin API authentication
admin_auth.bearer_token_filestring""Path to a file containing the bearer token

Access Logging

Section titled “Access Logging”

Access logs record every request processed by the data plane:

ParameterTypeDefaultDescription
access_log.enabledboolfalseEnable access logging
access_log.pathstringstdoutOutput path (stdout, stderr, or file path)
access_log.formatstring(see below)Log format string with placeholders
access_log.modestringjsonOutput mode: json or text
access_log.sample_ratefloat0.01Sampling rate (0.0 to 1.0)
access_log.routeAnnotationPrefixstringgateway.nantian.dev/access-log-Annotation prefix for per-route log configuration

Available format placeholders: %TIMESTAMP%, %EVENT%, %PROTOCOL%, %LISTENER%, %CLIENT_IP%, %HOST%, %METHOD%, %PATH%, %REQUEST_ID%, %ROUTE_NAMESPACE%, %ROUTE_NAME%, %BACKEND%, %STATUS%, %LATENCY_MS%, %BYTES_RECEIVED%, %BYTES_SENT%, %SNAPSHOT_VERSION%, %RETRY_ATTEMPTS%, %RESPONSE_FLAGS%.

Response Flags

Section titled “Response Flags”

The %RESPONSE_FLAGS% placeholder expands to a comma-separated list of flags indicating why a request was handled the way it was. An empty value or none means the request completed normally.

HTTP flags:

FlagHTTP StatusDescription
none—Request completed normally with no errors
NR500No route matched the request
UH503No healthy backend available
CB503Circuit breaker is open for the upstream
IB500BackendRefs configuration is invalid
UF500Route references an unsupported/unknown filter
UT504Upstream connection or response timed out
DC499Client closed the connection before response
IT408Downstream idle timeout before request completed
UC502Upstream connection closed unexpectedly
OL503Global overload protection rejected the request
RL429Global rate limiter rejected the request
RH431Request headers exceeded maxRequestHeaderBytes
RB413Request body exceeded maxRequestBodyBytes
MA—Connection closed due to httpMaxConnectionAgeMs

TCP/TLS stream flags:

FlagDescription
NEGeneric network-level error
UEUpstream connection error
DEDownstream connection error
MCConnection closed due to max connections

Runtime

Section titled “Runtime”

Core runtime settings for the data plane proxy:

ParameterTypeDefaultDescription
runtime.http_listen_addrstring0.0.0.0:80Address for the HTTP listener
runtime.enable_ipv6booltrueEnable IPv6 support
runtime.enable_http3boolfalseEnable HTTP/3 (QUIC) support
runtime.tls_min_versionstring1.2Minimum TLS version accepted
runtime.tls_max_versionstring1.3Maximum TLS version offered
runtime.tlsAssetDirstring""Directory for TLS certificate assets

Runtime Tuning

Section titled “Runtime Tuning”

Performance tuning parameters for the data plane:

ParameterTypeDefaultDescription
runtime_tuning.httpReloadRetryIntervalMsint1000Retry interval for HTTP listener reload (ms)
runtime_tuning.streamReloadRetryIntervalMsint1000Retry interval for stream listener reload (ms)
runtime_tuning.downstreamReadTimeoutMsint60000Timeout for reading from downstream clients (ms)
runtime_tuning.httpMaxConnectionAgeMsint0Maximum HTTP connection age (0 = unlimited)
runtime_tuning.httpKeepaliveRequestLimitint0Maximum requests per keepalive connection (0 = unlimited)
runtime_tuning.upstream_connection_timeout_msint5000Timeout for establishing upstream connections (ms)
runtime_tuning.upstream_read_timeout_msint30000Timeout for reading from upstream services (ms)
runtime_tuning.upstream_idle_timeout_msint60000Idle timeout for upstream connections (ms)

HTTP Capacity

Section titled “HTTP Capacity”
ParameterTypeDefaultDescription
runtime_tuning.http_capacity.workerThreadsint0Worker thread count (0 = CPU count)
runtime_tuning.http_capacity.acceptConcurrencyint16Concurrent TCP accept operations
runtime_tuning.http_capacity.upstreamKeepalivePoolSizeint32768Maximum idle connections in the upstream pool
runtime_tuning.http_capacity.reusePortboolnullEnable SO_REUSEPORT (null = auto-detect)

Request Mirroring

Section titled “Request Mirroring”
ParameterTypeDefaultDescription
runtime_tuning.requestMirrorMaxConcurrencyint1024Maximum concurrent mirrored requests

UDP

Section titled “UDP”
ParameterTypeDefaultDescription
runtime_tuning.udpResponseIdleTimeoutMsint500Idle timeout for UDP responses (ms)

TCP Proxy

Section titled “TCP Proxy”
ParameterTypeDefaultDescription
runtime_tuning.tcpProxyBufferBytesint16384Buffer size for TCP proxy connections
runtime_tuning.tcpSessionIdleTimeoutMsint0TCP session idle timeout (0 = unlimited)
runtime_tuning.tcpMaxConnectionAgeMsint0Maximum TCP connection age (0 = unlimited)

Retry Budget

Section titled “Retry Budget”
ParameterTypeDefaultDescription
runtime_tuning.retryBudgetEnabledbooltrueEnable retry budget for circuit breaking
runtime_tuning.retryBudgetRatioPercentint20Ratio of retries to total requests (%)
runtime_tuning.retryBudgetBurstint16Maximum burst of retries allowed

Stream Connection Pool

Section titled “Stream Connection Pool”
ParameterTypeDefaultDescription
runtime_tuning.streamUpstreamPoolSizeint128Maximum idle stream connections in the upstream pool
runtime_tuning.streamUpstreamPoolIdleTimeoutMsint30000Idle timeout for stream upstream connections (ms)

Work Stealing

Section titled “Work Stealing”
ParameterTypeDefaultDescription
runtime_tuning.work_stealingbooltrueEnable Tokio work-stealing across worker threads

HTTP Cache

Section titled “HTTP Cache”
ParameterTypeDefaultDescription
runtime_tuning.http_cache.enabledboolfalseEnable HTTP response caching
runtime_tuning.http_cache.maxSizeMbint256Maximum cache size in megabytes
runtime_tuning.http_cache.defaultTtlSecondsint60Default cache TTL in seconds

Graceful Shutdown

Section titled “Graceful Shutdown”
ParameterTypeDefaultDescription
runtime_tuning.graceful_drain_period_msint0Grace period for draining connections on shutdown (ms)

Active Health Checks

Section titled “Active Health Checks”
ParameterTypeDefaultDescription
runtime_tuning.activeHealthCheckEnabledboolfalseEnable active health checking of backends
runtime_tuning.activeHealthCheckIntervalMsint5000Interval between health checks (ms)
runtime_tuning.activeHealthCheckTimeoutMsint1000Timeout for health check requests (ms)
runtime_tuning.activeHealthCheckUnhealthyThresholdint2Consecutive failures before marking unhealthy

TCP Keepalive

Section titled “TCP Keepalive”

Downstream (client-facing)

Section titled “Downstream (client-facing)”
ParameterTypeDefaultDescription
runtime_tuning.downstreamTcpKeepalive.enabledboolfalseEnable TCP keepalive for downstream connections
runtime_tuning.downstreamTcpKeepalive.idleMsint60000Idle time before sending keepalive probes (ms)
runtime_tuning.downstreamTcpKeepalive.intervalMsint15000Interval between keepalive probes (ms)
runtime_tuning.downstreamTcpKeepalive.probeCountint4Number of probes before declaring dead
runtime_tuning.downstreamTcpKeepalive.userTimeoutMsint0User timeout for keepalive (0 = OS default)

Upstream (backend-facing)

Section titled “Upstream (backend-facing)”
ParameterTypeDefaultDescription
runtime_tuning.upstream_tcp_keepalive.enabledbooltrueEnable TCP keepalive for upstream connections
runtime_tuning.upstream_tcp_keepalive.idleMsint60000Idle time before sending keepalive probes (ms)
runtime_tuning.upstream_tcp_keepalive.intervalMsint15000Interval between keepalive probes (ms)
runtime_tuning.upstream_tcp_keepalive.probeCountint4Number of probes before declaring dead
runtime_tuning.upstream_tcp_keepalive.userTimeoutMsint0User timeout for keepalive (0 = OS default)

TCP Optimizations

Section titled “TCP Optimizations”
ParameterTypeDefaultDescription
runtime_tuning.downstream_tcp_fastopenboolnullEnable TCP Fast Open for downstream (null = auto-detect)
runtime_tuning.downstream_dscpintnullDSCP marking for downstream connections (null = disabled)
runtime_tuning.upstream_tcp_recv_bufint0Upstream TCP receive buffer size in bytes (0 = OS default)
runtime_tuning.upstream_tcp_fast_openbooltrueEnable TCP Fast Open for upstream connections
runtime_tuning.upstream_dscpintnullDSCP marking for upstream connections (null = disabled)

TCP Fast Open reduces connection latency by allowing data to be sent during the initial TCP handshake. DSCP (Differentiated Services Code Point) marking enables QoS prioritization at the network level.

Runtime Protection

Section titled “Runtime Protection”

Protection limits to prevent overload and resource exhaustion:

Global Limits

Section titled “Global Limits”
ParameterTypeDefaultDescription
runtime_protection.httpGlobalInflightLimitint16384Maximum concurrent in-flight HTTP requests (0 = unlimited)
runtime_protection.httpGlobalRateLimitRequestsPerSecondint10000Global rate limit (requests/second, 0 = unlimited)
runtime_protection.httpGlobalRateLimitBurstint20000Burst allowance for global rate limit

Listener Limits

Section titled “Listener Limits”
ParameterTypeDefaultDescription
runtime_protection.httpListenerInflightLimitint8192Maximum concurrent requests per listener (0 = unlimited)
runtime_protection.httpListenerRateLimitRequestsPerSecondint5000Per-listener rate limit (0 = unlimited)
runtime_protection.httpListenerRateLimitBurstint10000Burst allowance for listener rate limit

Route Limits

Section titled “Route Limits”
ParameterTypeDefaultDescription
runtime_protection.httpRouteInflightLimitint4096Maximum concurrent requests per route (0 = unlimited)
runtime_protection.httpRouteRateLimitRequestsPerSecondint2000Per-route rate limit (0 = unlimited)
runtime_protection.httpRouteRateLimitBurstint4000Burst allowance for route rate limit

Backend Circuit Breaker

Section titled “Backend Circuit Breaker”
ParameterTypeDefaultDescription
runtime_protection.httpBackendCircuitBreakerMaxRequestsint4096Maximum concurrent requests per backend (0 = unlimited)

Request Size Limits

Section titled “Request Size Limits”
ParameterTypeDefaultDescription
runtime_protection.httpMaxRequestBodyBytesint10485760Maximum request body size in bytes (0 = unlimited)
runtime_protection.httpMaxRequestHeaderBytesint65536Maximum request header size in bytes (0 = unlimited)

TCP/UDP Limits

Section titled “TCP/UDP Limits”
ParameterTypeDefaultDescription
runtime_protection.tcpGlobalConnectionLimitint32768Maximum concurrent TCP connections (0 = unlimited)
runtime_protection.tcpListenerConnectionLimitint8192Maximum TCP connections per listener (0 = unlimited)
runtime_protection.udpGlobalDatagramLimitint100000Maximum concurrent UDP datagrams (0 = unlimited)
runtime_protection.udpListenerDatagramLimitint50000Maximum UDP datagrams per listener (0 = unlimited)

Session Persistence

Section titled “Session Persistence”
ParameterTypeDefaultDescription
session_persistence.secret_keystring""Secret key for session cookie signing
session_persistence.secret_key_filestring""Path to file containing the secret key

xDS TLS

Section titled “xDS TLS”

TLS configuration for the xDS connection to the control plane:

ParameterTypeDefaultDescription
xds_tls.enabledboolfalseEnable TLS for the xDS connection
xds_tls.ca_pathstring""Path to the CA certificate for verifying the control plane
xds_tls.cert_pathstring""Path to the client certificate (for mTLS)
xds_tls.key_pathstring""Path to the client private key (for mTLS)
xds_tls.domain_namestring""Expected server name for certificate validation

xDS Transport

Section titled “xDS Transport”
ParameterTypeDefaultDescription
xdsTransport.connect_timeout_msint5000Timeout for establishing the xDS connection (ms)
xdsTransport.keepalive_interval_msint10000Interval for xDS keepalive pings (ms)
xdsTransport.keepaliveTimeoutMsint5000Timeout for xDS keepalive ping responses (ms)
xdsTransport.initialReconnectBackoffMsint2000Initial backoff for xDS reconnection (ms)
xdsTransport.maxReconnectBackoffMsint30000Maximum backoff for xDS reconnection (ms)
xdsTransport.applyTimeoutMsint3000Timeout for applying a received configuration snapshot (ms)
xdsTransport.applyPollIntervalMsint100Polling interval when waiting for snapshot application (ms)
xdsTransport.staleStreamTimeoutMsint30000Time before considering a stale xDS stream as failed (ms)
xdsTransport.snapshotFreshnessTimeoutMsint90000Time before considering the current snapshot as stale (ms)

Feature Flags

Section titled “Feature Flags”
ParameterTypeDefaultDescription
experimental.enableExperimentalGatewayboolfalseEnable experimental Gateway API features
experimental.enableAiGatewayboolfalseEnable the built-in AI gateway module

Complete Example

Section titled “Complete Example”

The following is a complete data plane configuration with all available options:

node_id: "dp-local"
cluster: "default"
control_plane_addr: "http://127.0.0.1:18080"
admin_addr: "127.0.0.1:19080"


log:
  level: "info,nantian_core::connectors=off"
  format: "json"
  add_source: false
  include_target: false
  include_thread_ids: false
  include_thread_names: false
  non_blocking: true
  non_blocking_buffered_lines: 65536
  drop_when_full: true
  open_telemetry:
    enabled: false
    endpoint: ""
    protocol: "grpc"
    timeoutMs: 3000
    insecure: false
    sampleRatio: 1.0
    serviceName: "nantian-dataplane"
    serviceNamespace: ""


admin_auth:
  bearer_token: ""
  bearer_token_file: ""


access_log:
  enabled: false
  path: "stdout"
  format: "%TIMESTAMP% %EVENT% %PROTOCOL% %LISTENER% %CLIENT_IP% %HOST% %METHOD% %PATH% %REQUEST_ID% %ROUTE_NAMESPACE% %ROUTE_NAME% %BACKEND% %STATUS% %LATENCY_MS% %BYTES_RECEIVED% %BYTES_SENT% %SNAPSHOT_VERSION% %RETRY_ATTEMPTS% %RESPONSE_FLAGS%"
  mode: "json"
  sample_rate: 0.01
  routeAnnotationPrefix: "gateway.nantian.dev/access-log-"


runtime:
  http_listen_addr: "0.0.0.0:80"
  enable_ipv6: true
  enable_http3: false
  tls_min_version: "1.2"
  tls_max_version: "1.3"
  tlsAssetDir: ""


runtime_tuning:
  httpReloadRetryIntervalMs: 1000
  streamReloadRetryIntervalMs: 1000
  downstreamReadTimeoutMs: 60000
  httpMaxConnectionAgeMs: 0
  httpKeepaliveRequestLimit: 0
  upstream_connection_timeout_ms: 5000
  upstream_read_timeout_ms: 30000
  upstream_idle_timeout_ms: 60000
  http_capacity:
    workerThreads: 0
    acceptConcurrency: 16
    upstreamKeepalivePoolSize: 32768
    reusePort: null
  requestMirrorMaxConcurrency: 1024
  udpResponseIdleTimeoutMs: 500
  tcpProxyBufferBytes: 16384
  tcpSessionIdleTimeoutMs: 0
  tcpMaxConnectionAgeMs: 0
  retryBudgetEnabled: true
  retryBudgetRatioPercent: 20
  retryBudgetBurst: 16
  streamUpstreamPoolSize: 128
  streamUpstreamPoolIdleTimeoutMs: 30000
  work_stealing: true
  downstream_tcp_fastopen: null
  downstream_dscp: null
  upstream_tcp_recv_buf: 0
  upstream_tcp_fast_open: true
  upstream_dscp: null
  http_cache:
    enabled: false
    maxSizeMb: 256
    defaultTtlSeconds: 60
  graceful_drain_period_ms: 0
  activeHealthCheckEnabled: false
  activeHealthCheckIntervalMs: 5000
  activeHealthCheckTimeoutMs: 1000
  activeHealthCheckUnhealthyThreshold: 2
  downstreamTcpKeepalive:
    enabled: false
    idleMs: 60000
    intervalMs: 15000
    probeCount: 4
    userTimeoutMs: 0
  upstream_tcp_keepalive:
    enabled: true
    idleMs: 60000
    intervalMs: 15000
    probeCount: 4
    userTimeoutMs: 0


runtime_protection:
  httpGlobalInflightLimit: 16384
  httpListenerInflightLimit: 8192
  httpRouteInflightLimit: 4096
  httpBackendCircuitBreakerMaxRequests: 4096
  httpGlobalRateLimitRequestsPerSecond: 10000
  httpGlobalRateLimitBurst: 20000
  httpListenerRateLimitRequestsPerSecond: 5000
  httpListenerRateLimitBurst: 10000
  httpRouteRateLimitRequestsPerSecond: 2000
  httpRouteRateLimitBurst: 4000
  httpMaxRequestBodyBytes: 10485760
  httpMaxRequestHeaderBytes: 65536
  tcpGlobalConnectionLimit: 32768
  tcpListenerConnectionLimit: 8192
  udpGlobalDatagramLimit: 100000
  udpListenerDatagramLimit: 50000


session_persistence:
  secret_key: ""
  secret_key_file: ""


xds_tls:
  enabled: false
  ca_path: ""
  cert_path: ""
  key_path: ""
  domain_name: ""


xdsTransport:
  connect_timeout_ms: 5000
  keepalive_interval_ms: 10000
  keepaliveTimeoutMs: 5000
  initialReconnectBackoffMs: 2000
  maxReconnectBackoffMs: 30000
  applyTimeoutMs: 3000
  applyPollIntervalMs: 100
  staleStreamTimeoutMs: 30000
  snapshotFreshnessTimeoutMs: 90000


experimental:
  enableExperimentalGateway: false
  enableAiGateway: false

Next Steps

Section titled “Next Steps”