Configuration Overview

Nantian Gateway uses YAML configuration files rather than command-line flags or environment variables. The control plane and data plane each have their own configuration file, kept separate because they run as independent processes with distinct responsibilities.

This chapter covers every available configuration option for both components.

How configuration works

The control plane reads its configuration from a file you specify with the --config flag at startup. The default path depends on your deployment method: Helm charts mount a ConfigMap at /etc/nantian/config.yaml, while local development picks up configs/controlplane/config.yaml from the repository.

The data plane works the same way. Its configuration lives at configs/dataplane/config.yaml in the repo, or at a path you point to with --config.

Both files use standard YAML syntax with camelCase keys. Duration values follow Go’s duration format: 30s for thirty seconds, 2m for two minutes, 200ms for 200 milliseconds. Numeric values that end in Ms (like timeoutMs) use plain milliseconds without the Go suffix.

Configuration sources

All default values shown in this documentation come directly from the configuration loading code in gateway/internal/config/config.go. When a field is omitted from your YAML file, the gateway fills in the default listed in the tables below.

You can override any field by including it in your configuration file. Helm users should modify values.yaml rather than editing the config file directly, since the chart templated the ConfigMap from Helm values.

Validation

The gateway performs basic validation at startup. Malformed durations, missing required fields, or conflicting options will cause a fatal error before the process starts accepting connections. Always validate your config with a dry-run before rolling it out to production.

Chapter structure

Page	Covers
Control Plane	Server addresses, reconciler tuning, leader election, node drift detection, admin API
Data Plane	Proxy runtime, upstream connections, health checks, rate limiting, circuit breaking
TLS / mTLS	Admin TLS, gRPC TLS with mTLS, xDS transport security
gRPC xDS	Keepalive timers, connection management, snapshot lifecycle
Observability	Structured logging, Prometheus metrics, pprof, access logging, OpenTelemetry tracing
Performance Tuning	Buffer sizes, connection pool sizing, timeouts, protection limits

Key concepts

Before diving into individual pages, a few concepts show up repeatedly across the configuration:

Duration fields use Go duration strings. Common values include 1s, 500ms, 2m, 30s. Millisecond-valued fields (ending in Ms) use plain integers.

Address fields follow Go’s net.Listen format. Use :18080 to bind to all interfaces on port 18080, 127.0.0.1:6060 to bind to localhost only, or 0.0.0.0:10080 to explicitly bind to all interfaces.

Boolean fields default to false throughout unless noted otherwise. This is the safe default: features like TLS, pprof, and experimental flags are opt-in.

Zero values for integer limits means “unlimited” or “disabled.” A circuit breaker set to 0 maximum requests won’t trip. A rate limiter set to 0 requests per second won’t enforce any limit.

Complete control plane config example

Below is a representative control plane configuration covering the sections you’ll reach for first. It’s not the full file, that lives at configs/controlplane/config.yaml, but it shows the important knobs with inline comments:

grpcAddr: ":18080"           # xDS gRPC for data plane nodes
adminAddr: ":18081"          # Admin API
metricsAddr: ":18082"        # Prometheus /metrics
controllerName: "gateway.networking.k8s.io/nantian-gw"
namespace: "nantian-gw"

# Reconciler tuning
syncPeriod: 30s
reconcilerRunner:
  settleDelay: "300ms"
  retryBackoff: "1s"

# Leader election (multi-replica)
leaderElection:
  enabled: true
  leaseDuration: "15s"
  renewDeadline: "10s"

# gRPC keepalive
grpcRuntime:
  keepaliveTime: "30s"
  keepaliveTimeout: "10s"
  maxConnectionAge: "30m"

# Admin API protection
adminLimits:
  maxRequestBodyBytes: 2097152   # 2 MiB

# TLS (opt-in for production)
adminTLS:
  enabled: false
grpcTLS:
  enabled: false

# Logging
log:
  level: "info"
  format: "json"

# Feature flags
features:
  enableExperimentalGateway: false
  enableAiGateway: false

Config validation and dry-run

The gateway validates all configuration at startup. Malformed durations, missing required fields, or conflicting options cause a fatal error before the process accepts any connections.

You can validate a config file without starting the full gateway by using the --dry-run flag:

nantian-gw --config ./my-config.yaml --dry-run

This parses the YAML, fills in defaults, runs the validation suite, and exits. Exit code 0 means the config is valid. Any error prints a specific message pointing to the offending field.

Caution

Dry-run checks config syntax and semantics only. It does not verify that addresses are reachable, certificates are valid, or the Kubernetes API server is accessible. Those are runtime checks.

Add a dry-run step to your CI pipeline or pre-commit hook to catch config errors before they reach the cluster:

# GitHub Actions example
- name: Validate gateway config
  run: nantian-gw --config deploy/production/controlplane.yaml --dry-run

Environment-specific configs

Different environments need different config values. Here’s what changes between them:

Setting	Dev / Minikube	Staging	Production
TLS	Disabled everywhere	Self-signed or staging CA	Real certs, mTLS enabled
Log format	text	json	json
Log level	debug or info	info	info (or warn)
Leader election	Optional (single replica)	Enabled (2 replicas)	Enabled (2+ replicas)
pprof	enabled: true	enabled: false	enabled: false
Timeouts	Short (faster feedback)	Match production	Conservative
Admin auth	None	None or token	Bearer token required

Manage these differences through Helm values files. Keep a base values.yaml with shared defaults and layer environment overrides on top:

deploy/helm/
  values.yaml              # shared defaults
  values-dev.yaml          # dev overrides
  values-staging.yaml      # staging overrides
  values-production.yaml   # production overrides

Deploy with the appropriate values file:

helm upgrade --install nantian-gw ./deploy/helm \
  -f deploy/helm/values.yaml \
  -f deploy/helm/values-production.yaml

Config file location and precedence

The gateway reads one config file at startup. It does not merge multiple files. The resolution order, from highest to lowest priority:

1. --config flag — Explicit path. Always wins if set.
2. Helm ConfigMap mount — /etc/nantian/config.yaml, provided by the Helm chart.
3. Repository default — configs/controlplane/config.yaml in the working directory.

When deployed via Helm, the chart templates a ConfigMap from your values.yaml and mounts it at /etc/nantian/config.yaml. The process starts without --config, so it picks up the mount. To change config in a Helm deployment, edit values.yaml and upgrade: do not edit the ConfigMap directly, Helm will overwrite it on the next release.

During local development, the repo default is used automatically. Override it with --config:

go run ./cmd/nantian-gw --config /tmp/my-config.yaml

To verify which file was loaded, check the startup log line that includes the "path" field: