Configuration

All flags, environment variables, ConfigMap settings, and tuning guidance for unbounded-net.

This document describes all configuration options for unbounded-net components. For a conceptual introduction, see Networking Concepts.

Runtime Configuration

Both the controller and node agent load runtime settings from a shared YAML file mounted from the unbounded-net-config ConfigMap.

• Default path: /etc/unbounded-net/config.yaml
• Override: --config-file=<path>
• Startup behavior: fail-fast if the config file is missing or invalid.
• CLI flags still work as explicit overrides when set.

Config Structure

common:
  azureTenantId: ""           # Only for Azure Portal links in the UI
  apiserverURL: ""            # Override API server URL (empty = in-cluster)
  logLevel: 2                 # klog verbosity (0-10), watched for live changes

controller:
  healthPort: 9999
  nodeAgentHealthPort: 9998
  informerResyncPeriod: 300s
  statusStaleThreshold: 40s
  registerAggregatedAPIServer: true
  managedKubeProxy:
    enabled: true
    image: ""
  leaderElection:
    enabled: true
    leaseDuration: 15s
    renewDeadline: 5s
    retryPeriod: 10s

node:
  cniConfDir: /host/etc/cni/net.d
  cniConfFile: 10-unbounded.conflist
  bridgeName: cbr0
  wireGuardDir: /host/etc/wireguard
  wireGuardPort: 51820
  mtu: 0
  healthPort: 9998
  tunnelDataplaneMapSize: 16384
  tunnelIPFamily: IPv4
  preferredPrivateEncap: GENEVE
  preferredPublicEncap: WireGuard
  genevePort: 6081
  geneveVni: 1
  vxlanPort: 4789

Controller Configuration

Managed kube-proxy

The controller creates a kube-proxy DaemonSet for each Site whose nodes are not covered by the provider-managed kube-proxy. Each DaemonSet uses the Site’s pod CIDR and runs only on nodes labeled for that Site and for unbounded-managed kube-proxy.

The image setting defaults to an empty string. When it is empty, the controller reuses the image from the kube-system/kube-proxy DaemonSet. If that DaemonSet does not exist, it uses registry.k8s.io/kube-proxy:<server version>.

Set controller.managedKubeProxy.image to override the image for all unbounded-managed kube-proxy DaemonSets, for example when pulling kube-proxy through a private registry. Set controller.managedKubeProxy.enabled to false to disable their creation.

Leader Election

Health and Monitoring

Logging

Node Agent Configuration

General

CNI Configuration

MTU Guidance

The node.mtu setting caps the automatically selected MTU on tunnel and bridge interfaces. Zero enables automatic selection. Encapsulation overhead:

The node agent resolves the route to each peer and subtracts the selected encapsulation overhead. For example, WireGuard over a 1500-byte route uses 1420.

Behavior:

• Each peer’s effective MTU is the lowest applicable configured cap, CRD tunnelMTU, and route MTU after encapsulation overhead.
• Sites and GatewayPools form a topology connected by SitePeerings, SiteGatewayPoolAssignments, and GatewayPoolPeerings. The lowest tunnelMTU in the local site’s connected topology is applied site-wide, including downstream multi-hop gateway paths.
• The CNI MTU is the lowest effective peer or connected-topology MTU.
• At startup and whenever the effective CNI MTU changes, the node agent updates the CNI bridge and both endpoints of existing pod veth pairs.
• Forwarded TCP SYN packets on every interface are MSS-clamped to the site-wide fabric MTU (MTU - 40 for IPv4 and MTU - 60 for IPv6).
• A value of 0 enables route-specific automatic MTU selection.

WireGuard

GENEVE

VXLAN

The narrow source port range (32 ports) limits distinct flows from VMs, helping avoid flow table limits on cloud platforms (e.g., Azure).

IPIP

Tunnel interface names

The three shared tunnel device names (geneve0, vxlan0, ipip0) and the per-port WireGuard interface prefix (default wg) are configurable via the flags above and via the matching YAML fields under node: (geneveInterfaceName, vxlanInterfaceName, ipipInterfaceName, wireGuardInterfacePrefix). Operators rarely need to change them.

Constraints, enforced at startup:

• Shared tunnel names: non-empty, at most 15 bytes (Linux IFNAMSIZ limit), pairwise distinct, must not equal unbounded0.
• WireGuard prefix: non-empty, at most 10 bytes (so prefix + 5-digit UDP port fits in IFNAMSIZ), no /, must not equal unbounded0.
• unbounded0 (the agent’s eBPF dummy device) is not configurable.

When the names are changed, the agent automatically removes previous-run devices it can confidently identify, scoped narrowly so other CNIs (e.g. Cilium) running flow-based GENEVE / VXLAN on different UDP ports are not touched. IPIP is not auto-cleaned: remove a renamed-away IPIP device manually with ip link del <old-name>.

Tunnel Dataplane

The node agent uses an eBPF dataplane: BPF LPM tries on the unbounded0 interface drive per-destination tunnel redirection.

Tunnel Protocol Selection

The tunnelProtocol field is available on all scope CRDs:

When Auto, links using external IPs use WireGuard; internal-only links use the preferred private encap (default GENEVE). The security-wins rule ensures WireGuard is used if any scope explicitly requests it.

See Routing Flows for the full protocol selection algorithm.

Status Push

Health Check (UDP Probes)

Health check sessions are automatically created for all routes with nexthops. Route metric adjustment on failure provides fast failover.

Firewall Requirements

Resource Requirements

Controller

resources:
  requests: { cpu: 10m, memory: 64Mi }
  limits:   { cpu: 100m, memory: 128Mi }

Node Agent

resources:
  requests: { cpu: 10m, memory: 32Mi }
  limits:   { cpu: 100m, memory: 64Mi }

Scaling

Environment Variables

Controller

Node Agent

Tuning Recommendations

High Availability

replicas: 2
args:
  - --leader-elect=true
  - --leader-elect-lease-duration=15s
  - --leader-elect-renew-deadline=5s

Large Clusters (1000+ nodes)

# Controller
args:
  - --informer-resync-period=600s

# Node agent
args:
  - --informer-resync-period=7200s

Next Steps

• Custom Resources – CRD specifications.
• Routing Flows – Packet-level routing details.
• Operations – Deployment, monitoring, and troubleshooting.