Configuration reference

Coxswain is configured via environment variables. Every setting has a COXSWAIN_* env var that maps directly to the underlying flag.

Setting configuration

HelmRaw manifests / Kustomize

Pass values at install or upgrade time:

helm upgrade coxswain oci://ghcr.io/coxswain-labs/charts/coxswain \
  --namespace coxswain-system \
  --set proxy.http.port=80 \
  --set proxy.https.port=443 \
  --set controller.watchNamespace=my-namespace

Or via a values.yaml file:

helm upgrade coxswain oci://ghcr.io/coxswain-labs/charts/coxswain \
  --namespace coxswain-system \
  -f my-values.yaml

See the Helm install guide for the full values reference.

Set environment variables directly on the Deployment:

env:
  - name: COXSWAIN_PROXY_HTTP_PORT
    value: "80"
  - name: COXSWAIN_PROXY_HTTPS_PORT
    value: "443"
  - name: COXSWAIN_STATUS_ADDRESS
    value: "203.0.113.10"

Settings

Env var	Flag	Default	Description
COXSWAIN_ADMIN_PORT	--admin-port	8082	Port for admin, metrics, and diagnostics endpoints
COXSWAIN_CONTROLLER_LEASE_RENEW_INTERVAL	--controller-lease-renew-interval	5s	How often the leader renews its lease; must be ≤ 1/3 of the TTL
COXSWAIN_CONTROLLER_LEASE_TTL	--controller-lease-ttl	15s	How long a lease stays valid without renewal; must be ≥ 3× the renew interval
COXSWAIN_CONTROLLER_NAME	--controller-name	coxswain-labs.dev/gateway-controller	GatewayClass spec.controllerName to claim
COXSWAIN_CONTROLLER_WATCH_NAMESPACE	--controller-watch-namespace	(cluster-wide)	Restrict watch to a single namespace
COXSWAIN_HEALTH_PORT	--health-port	8081	Port for liveness and readiness health endpoints
COXSWAIN_INGRESS_DEFAULT_BACKEND	--ingress-default-backend	(none)	Cluster-wide fallback backend for Ingress rules that match no rule, expressed as <namespace>/<service>:<port>
COXSWAIN_LOG	--log	info	Log level; supports RUST_LOG directive syntax (e.g. info,coxswain=debug)
COXSWAIN_LOG_FORMAT	--log-format	json	json (production) or console (human-readable)
POD_NAME	--pod-name	coxswain-local	Pod name used as the leader-election holder identity
POD_NAMESPACE	--pod-namespace	coxswain-system	Pod namespace used to scope the leader-election Lease
COXSWAIN_PROXY_ACCEPT_PROXY_PROTOCOL	--proxy-accept-proxy-protocol	false	Require HAProxy PROXY v1/v2 on inbound connections; must be combined with --proxy-trusted-sources
COXSWAIN_PROXY_BIND_ADDRESS	--proxy-bind-address	0.0.0.0	IP address shared by all proxy, health, and admin listeners
COXSWAIN_PROXY_DEFAULT_BACKEND_REQUEST_TIMEOUT	--proxy-default-backend-request-timeout	(none)	Default upstream-only timeout when HTTPRouteRule.timeouts.backendRequest is not set
COXSWAIN_PROXY_DEFAULT_REQUEST_TIMEOUT	--proxy-default-request-timeout	(none)	Default total request timeout (client → proxy → upstream → client) when HTTPRouteRule.timeouts.request is not set
COXSWAIN_PROXY_HTTP_PORT	--proxy-http-port	(none)	Port for inbound HTTP traffic; unset to disable the HTTP listener
COXSWAIN_PROXY_HTTPS_PORT	--proxy-https-port	(none)	Port for inbound HTTPS traffic (SNI TLS); unset to disable
COXSWAIN_PROXY_SHUTDOWN_GRACE_PERIOD	--proxy-shutdown-grace-period	30s	Drain window after shutdown signal
COXSWAIN_PROXY_SHUTDOWN_TIMEOUT	--proxy-shutdown-timeout	5s	Hard deadline after the grace period; remaining connections are forcibly closed
COXSWAIN_PROXY_THREADS	--proxy-threads	2	Worker threads; set to CPU core count for maximum throughput
COXSWAIN_PROXY_TRUSTED_SOURCES	--proxy-trusted-sources	(none)	Comma-separated CIDRs allowed to send PROXY-protocol headers; only meaningful with --proxy-accept-proxy-protocol
COXSWAIN_STATUS_ADDRESS	--status-address	(none)	IP or hostname written to Ingress.status and Gateway.status.addresses; required for cert-manager HTTP-01 and external-dns

Ports summary

Port	Default	Env var	Endpoints
HTTP proxy	(none)	COXSWAIN_PROXY_HTTP_PORT	Inbound HTTP data plane
HTTPS proxy	(none)	COXSWAIN_PROXY_HTTPS_PORT	Inbound HTTPS data plane (SNI TLS)
Health	8081	COXSWAIN_HEALTH_PORT	/healthz, /readyz
Admin	8082	COXSWAIN_ADMIN_PORT	/metrics, /routes, /status

The proxy listeners are disabled unless their port is explicitly set. The Helm chart defaults proxy.http.port to 80 and proxy.https.port to 443.

Note

There is currently one bind address (COXSWAIN_PROXY_BIND_ADDRESS) shared by all listeners. Separate bind addresses for proxy vs. admin/health will be added in a future release.

Leader election

All replicas maintain a current routing table and serve traffic; only the leader writes status back to Ingress, Gateway, and HTTPRoute objects. The lease parameters must satisfy lease-ttl ≥ 3 × lease-renew-interval.

The defaults (15 s TTL, 5 s renew interval) allow the leader to miss two renewal cycles before the lease expires. Reduce them if you need faster failover at the cost of more Kubernetes API traffic.

Duration format

Duration values use humantime syntax: 300ms, 5s, 1m30s, 2h, 1.5s. Unit-less integers are not accepted — always include a unit.

POD_NAME and POD_NAMESPACE

These are required for correct leader-election identity and are typically injected via the Kubernetes Downward API. The Helm chart handles this automatically. For raw manifests, add to the Deployment:

env:
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
  - name: POD_NAMESPACE
    valueFrom:
      fieldRef:
        fieldPath: metadata.namespace