Control Plane Configuration

The control plane configuration file is located at gateway/configs/controlplane/config.yaml. It controls every aspect of the control plane process: server addresses, Kubernetes controller behavior, admin API settings, TLS, gRPC runtime parameters, and feature flags.

Server Addresses

The control plane listens on four distinct addresses:

Parameter	Type	Default	Description
grpcAddr	string	:18080	gRPC server address for xDS configuration streaming to data planes
adminAddr	string	:18081	HTTP admin API server used by the dashboard and internal tooling
metricsAddr	string	:18082	Prometheus metrics endpoint
healthProbeAddr	string	:18083	Kubernetes health and readiness probe endpoint

Each address follows Go’s net.Listen format. An empty host portion (e.g., :18080) binds to all network interfaces. Use 127.0.0.1:18081 to restrict the admin API to localhost.

Exposing the admin API

The admin API provides full read and write access to gateway resources. Never expose adminAddr to external networks without TLS and authentication. See the TLS configuration page for securing it.

Controller Configuration

These settings control how the control plane interacts with the Kubernetes API server and manages gateway resources.

Parameter	Type	Default	Description
controllerName	string	gateway.networking.k8s.io/nantian-gw	GatewayClass controller name this instance responds to
statusAddress	string	127.0.0.1	IP address used in Gateway status addresses field
statusAddresses	[]string	—	Additional addresses (hostnames or IPs) for Gateway status
namespace	string	nantian-gw	Namespace where the control plane runs
syncPeriod	duration	30s	Interval between full resource resynchronizations
syncSettleDelay	duration	200ms	Delay before processing a batch of changes to allow accumulation

Reconciler Runner

Controls the reconciliation loop that processes Kubernetes resource changes.

Parameter	Type	Default	Description
reconcilerRunner.settleDelay	duration	300ms	Delay before starting reconciliation after a change event
reconcilerRunner.retryBackoff	duration	1s	Delay between reconciliation retries on failure

Node Status

Controls how the control plane tracks and persists data plane node status.

Parameter	Type	Default	Description
nodeStatus.leasePrefix	string	aeg-node	Prefix for node lease objects in the Kubernetes API
nodeStatus.persistTimeout	duration	2s	Timeout for persisting node status to the API server
nodeStatus.persistDebounce	duration	250ms	Minimum interval between node status persistence operations

Node Drift

Parameter	Type	Default	Description
nodeDrift.warningThreshold	duration	15s	Duration after which a node with no heartbeat is considered drifted

Admin API Configuration

Readiness

Parameter	Type	Default	Description
adminReadiness.mode	string	snapshot	Readiness check mode: snapshot (ready after first snapshot built) or always

Limits

Parameter	Type	Default	Description
adminLimits.maxRequestBodyBytes	int	2097152 (2 MB)	Maximum admin API request body size
adminLimits.maxResponseBodyBytes	int	8388608 (8 MB)	Maximum admin API response body size

Runtime

HTTP server runtime settings for the admin API:

Parameter	Type	Default	Description
adminRuntime.readHeaderTimeout	duration	5s	Maximum time to read request headers
adminRuntime.readTimeout	duration	30s	Maximum time to read the full request
adminRuntime.writeTimeout	duration	30s	Maximum time to write the response
adminRuntime.idleTimeout	duration	2m	Maximum idle time before closing a connection

Dataplane Aggregation

The admin API can aggregate responses from connected data plane instances:

Parameter	Type	Default	Description
adminRuntime.dataplaneAggregation.serviceName	string	nantian-dataplane-admin	Kubernetes Service name for data plane admin endpoints
adminRuntime.dataplaneAggregation.namespace	string	nantian-gw	Namespace of the data plane admin Service
adminRuntime.dataplaneAggregation.portName	string	admin	Port name on the data plane admin Service
adminRuntime.dataplaneAggregation.timeout	duration	2s	Timeout for data plane aggregation requests
adminRuntime.dataplaneAggregation.bearerTokenFile	string	""	Path to bearer token file for authenticating to data planes

Authentication

Parameter	Type	Default	Description
adminAuth.bearerToken	string	""	Static bearer token for admin API authentication
adminAuth.bearerTokenFile	string	""	Path to a file containing the bearer token
adminAuth.rateLimitRPS	int64	0	Requests per second rate limit for the admin API (0 = unlimited)

When both bearerToken and bearerTokenFile are empty, the admin API has no authentication. When configured, requests must include an Authorization: Bearer <token> header.

The rateLimitRPS field applies rate limiting to the admin API, protecting it from excessive requests. Set to 0 to disable rate limiting.

Translator Limits

Controls resource limits for the translator that converts Kubernetes resources into internal configuration:

Parameter	Type	Default	Description
translatorLimits.maxInputObjects	int	0	Maximum input objects to process (0 = unlimited)
translatorLimits.maxSnapshotObjects	int	0	Maximum objects in a configuration snapshot (0 = unlimited)
translatorLimits.maxSnapshotEndpoints	int	0	Maximum endpoints in a configuration snapshot (0 = unlimited)

Set these limits to prevent the control plane from consuming excessive memory when processing very large configurations. A value of 0 means no limit.

Logging

Parameter	Type	Default	Description
log.level	string	info	Minimum log level: debug, info, warn, error
log.format	string	json	Output format: json or text
log.addSource	bool	false	Include source file and line number in log entries

The debug level includes reconciliation details, snapshot diffs, and gRPC stream events. JSON format is recommended for production log aggregation.

Leader Election

The control plane uses Kubernetes leader election for high availability:

Parameter	Type	Default	Description
leaderElection.enabled	bool	true	Enable leader election (disable for single-replica deployments)
leaderElection.id	string	nantian-controlplane-leader	Identity for the leader election lock
leaderElection.leaseDuration	duration	15s	Duration a leader holds the lease before a new election
leaderElection.renewDeadline	duration	10s	Deadline for the leader to renew its lease
leaderElection.retryPeriod	duration	2s	Interval between lease acquisition attempts for non-leaders

Dashboard API

The control plane includes a built-in dashboard API for the web admin interface:

Parameter	Type	Default	Description
dashboardApi.enabled	bool	true	Enable the dashboard API endpoints
dashboardApi.basePath	string	/api/dashboard	URL path prefix for dashboard API endpoints
dashboardApi.dataplaneAdminUrl	string	http://nantian-dataplane-admin.nantian-gw.svc.cluster.local:19080	URL template for data plane admin API access
dashboardApi.requestTimeout	duration	5s	Timeout for dashboard API requests
dashboardApi.resourceMutationsEnabled	bool	true	Allow resource mutations through the dashboard API

Profiling

Parameter	Type	Default	Description
pprof.enabled	bool	false	Enable Go pprof profiling endpoints
pprof.addr	string	127.0.0.1:6060	Address for the pprof HTTP server
pprof.bearerToken	string	""	Bearer token for pprof endpoint authentication
pprof.bearerTokenFile	string	""	Path to a file containing the pprof bearer token

Enable pprof for debugging performance issues. The pprof server should be bound to localhost only. When a bearer token is configured, the pprof endpoint requires authentication.

TLS Configuration

Refer to the TLS / mTLS page for detailed TLS configuration.

Admin TLS

Parameter	Type	Default	Description
adminTLS.enabled	bool	false	Enable TLS on the admin HTTP server
adminTLS.certPath	string	""	Path to the server certificate (PEM)
adminTLS.keyPath	string	""	Path to the server private key (PEM)
adminTLS.clientCAPath	string	""	Path to the CA certificate for verifying client certificates (mTLS)
adminTLS.requireClientCert	bool	false	Require and verify client certificates (mTLS)

Admin TLS enforces ECDHE cipher suites (TLS 1.2 minimum) for forward secrecy. When clientCAPath is set, the server verifies client certificates. Set requireClientCert to true to reject connections without a valid client certificate.

gRPC TLS

Parameter	Type	Default	Description
grpcTLS.enabled	bool	false	Enable TLS on the gRPC server
grpcTLS.certPath	string	""	Path to the server certificate (PEM)
grpcTLS.keyPath	string	""	Path to the server private key (PEM)
grpcTLS.clientCAPath	string	""	Path to the CA certificate for verifying client certificates
grpcTLS.requireClientCert	bool	false	Require and verify client certificates (mTLS)

gRPC Runtime

These settings control the gRPC server behavior for xDS communication:

Parameter	Type	Default	Description
grpcRuntime.keepaliveTime	duration	30s	Interval for sending keepalive pings to connected data planes
grpcRuntime.keepaliveTimeout	duration	10s	Timeout for keepalive ping responses
grpcRuntime.minPingInterval	duration	15s	Minimum interval between pings from data plane clients
grpcRuntime.maxConnectionIdle	duration	2m	Maximum idle time before closing a gRPC connection
grpcRuntime.maxConnectionAge	duration	30m	Maximum lifetime of a gRPC connection
grpcRuntime.maxConnectionAgeGrace	duration	30s	Grace period after max connection age before forceful closure
grpcRuntime.snapshotSendTimeout	duration	5s	Timeout for sending a configuration snapshot
grpcRuntime.snapshotAckTimeout	duration	30s	Timeout for receiving a snapshot acknowledgment
grpcRuntime.permitWithoutStream	bool	false	Allow data planes without an active xDS stream

Feature Flags

Parameter	Type	Default	Description
features.enableExperimentalGateway	bool	false	Enable experimental Gateway API features
features.enableAiGateway	bool	false	Enable the built-in AI gateway module

Complete Example

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

grpcAddr: ":18080"
adminAddr: ":18081"
metricsAddr: ":18082"
healthProbeAddr: ":18083"
controllerName: "gateway.networking.k8s.io/nantian-gw"
statusAddress: "127.0.0.1"
namespace: "nantian-gw"
syncPeriod: 30s
syncSettleDelay: 200ms

reconcilerRunner:
  settleDelay: "300ms"
  retryBackoff: "1s"

nodeStatus:
  leasePrefix: "aeg-node"
  persistTimeout: "2s"
  persistDebounce: "250ms"

nodeDrift:
  warningThreshold: "15s"

adminReadiness:
  mode: "snapshot"

adminLimits:
  maxRequestBodyBytes: 2097152
  maxResponseBodyBytes: 8388608

adminRuntime:
  readHeaderTimeout: "5s"
  readTimeout: "30s"
  writeTimeout: "30s"
  idleTimeout: "2m"
  dataplaneAggregation:
    serviceName: "nantian-dataplane-admin"
    namespace: "nantian-gw"
    portName: "admin"
    timeout: "2s"
    bearerTokenFile: ""

translatorLimits:
  maxInputObjects: 0
  maxSnapshotObjects: 0
  maxSnapshotEndpoints: 0

adminAuth:
  bearerToken: ""
  bearerTokenFile: ""
  rateLimitRPS: 0

dashboardApi:
  enabled: true
  basePath: "/api/dashboard"
  dataplaneAdminUrl: "http://nantian-dataplane-admin.nantian-gw.svc.cluster.local:19080"
  requestTimeout: "5s"
  resourceMutationsEnabled: true

pprof:
  enabled: false
  addr: "127.0.0.1:6060"
  bearerToken: ""
  bearerTokenFile: ""

log:
  level: "info"
  format: "json"
  addSource: false

leaderElection:
  enabled: true
  id: "nantian-controlplane-leader"
  leaseDuration: "15s"
  renewDeadline: "10s"
  retryPeriod: "2s"

adminTLS:
  enabled: false
  certPath: ""
  keyPath: ""
  clientCAPath: ""
  requireClientCert: false

grpcTLS:
  enabled: false
  certPath: ""
  keyPath: ""
  clientCAPath: ""
  requireClientCert: false

grpcRuntime:
  keepaliveTime: "30s"
  keepaliveTimeout: "10s"
  minPingInterval: "15s"
  maxConnectionIdle: "2m"
  maxConnectionAge: "30m"
  maxConnectionAgeGrace: "30s"
  snapshotSendTimeout: "5s"
  snapshotAckTimeout: "30s"
  permitWithoutStream: false

features:
  enableExperimentalGateway: false
  enableAiGateway: false

Next Steps

• Data Plane Configuration — data plane config reference
• TLS / mTLS — detailed TLS configuration guide
• Observability — logging, metrics, and tracing configuration