Configuration Reference

Both the controller and the agent read the same YAML file, and each ignores the sections that do not apply to it. The default path is /etc/fabric-manager/config.yaml, overridable with --config.

For Kubernetes deployments the chart renders this file into a ConfigMap, so prefer the chart values; this page describes the underlying file, which is what you edit for bare-metal and Docker runs.

Only controller.listen_address is required. Every other key has a default, and the whole otel, telemetry, and discovery sections can be omitted.

controller

Key	Default	Description
listen_address	required	host:port the controller’s gRPC server binds to. Agents dial this
heartbeat_interval_sec	10	How often each agent sends a heartbeat. Must be positive
heartbeat_timeout_sec	30	Mark a host offline after this long without a heartbeat. Must be positive and strictly greater than heartbeat_interval_sec
daemon_reconnect_timeout_sec	60	Grace period for an agent to reconnect before its topology is dropped
factory_system_descriptor_search_path	unset	Path searched for Factory System Descriptor textprotos. Required for anything FSD-related: QueryFactorySystemDescriptor, topo_source: FSD, validate_topo, and placement validation
physical_grouping_descriptor_path	unset	Path to a Physical Grouping Descriptor, which tells the mapper about hardware-specific tray layouts (e.g. BH galaxy rev C)
supported_topology_shapes	empty	Native topology shapes discoverable from FSD host instance paths; see below
http_listen_address	unset	host:port for the web UI and JSON API. Empty disables the HTTP server
web_ui_path	unset	Directory of static UI assets served at /. Empty serves the JSON API only
keepalive	see below	gRPC keepalive for the controller ↔ agent connection

controller.keepalive

Applied to both the controller’s gRPC server and each agent’s client channel; agents read this section from their own copy of the config.

Key	Default	Description
time_sec	20	Interval between keepalive HTTP/2 pings. Must be positive
timeout_sec	10	How long to wait for a ping ack before treating the connection as dead. Must be positive
permit_without_calls	true	Ping even with no active RPCs on the connection
max_connection_idle_sec	0	Server-only: close a connection idle this long. 0 disables. Must not be negative

This matters because agents send unary heartbeats over a single reused channel, so the connection is idle between calls. Without keepalive, a peer that vanishes without a TCP FIN/RST leaves a half-open connection that the transport poller can spin on.

Leave max_connection_idle_sec at 0, or comfortably above heartbeat_interval_sec, so healthy but briefly idle connections are not torn down.

otel

OpenTelemetry logs, traces, and metrics. Currently exported to stdout in OStream/OTLP-style format; pipe it to a Collector or scrape via kubectl logs.

Key	Default	Description
enabled	false	Install the Logger, Tracer, and Meter providers
service_name	tt-fabric-manager-controller	Reported service name. Must be non-empty when enabled
deployment_environment	unset	Reported deployment environment, e.g. production
metric_export_interval_sec	10	Metric export interval. Must be positive when enabled

Standard environment variables take precedence over these values: OTEL_SERVICE_NAME overrides service_name, and OTEL_SDK_DISABLED=true (or TRUE/1) forces OTEL off regardless of the YAML.

telemetry

Agent-side integration with the per-host tt-telemetry collector. When enabled, the agent opens a streaming subscription to the collector and rediscovers its topology when link state changes, so the controller tracks fabric health without waiting for re-registration.

Key	Default	Description
enabled	false	Connect to a local collector
address	127.0.0.1:50051	TCP endpoint of the collector’s gRPC listener. The preferred transport
socket_path	unset	Collector UNIX socket, dialled as unix://<path>. Used only when address is empty
metric_queries	tt_ethernet_link_up, tt_ethernet_cable_present	Substring matches against metric paths; one subscription per entry
rediscovery_min_interval_sec	5	Minimum spacing between telemetry-triggered rediscoveries. Bursts of link events are coalesced into at most one rediscovery per interval

When both address and socket_path are set, TCP wins. When enabled is true, at least one of them must be set or startup fails. The collector must be started with a matching --grpc-port/--grpc-bind.

The default queries are the boolean link-health metrics specifically so the agent gets one update per link state transition instead of subscribing to high-rate counters.

discovery

Retry policy for the agent’s initial device discovery, which can transiently find nothing if UMD runs while devices are still coming up.

Key	Default	Description
retry_max_attempts	3	Re-discoveries attempted after an empty startup scan. 0 disables retries; must not be negative
retry_interval_sec	20	Seconds between retries. Must be positive when retries are enabled

Retries stop as soon as a discovery finds devices.