Skip to main content
cluster_config is an enterprise capability. OSS builds ignore this section.
cluster_config enables multi-node Bifrost enterprise clustering with gossip-based membership and optional automatic node discovery. You can form a cluster in two ways:
  • Define static peers (host:port)
  • Enable discovery with one of: kubernetes, dns, udp, consul, etcd, mdns
At least one of peers or discovery.enabled: true must be configured when cluster_config.enabled is true.

​
Minimal Runnable Configs

{
  "cluster_config": {
    "enabled": true,
    "discovery": {
      "enabled": true,
      "type": "mdns",
      "service_name": "bifrost-cluster"
    }
  }
}
Use this for local testing. At startup, cluster init requires either:
  • non-empty peers, or
  • discovery.enabled: true
If neither is set, cluster initialization fails.

​
Static Peers

{
  "cluster_config": {
    "enabled": true,
    "region": "us-east-1",
    "peers": [
      "10.0.1.10:10101",
      "10.0.1.11:10101"
    ],
    "gossip": {
      "port": 10101,
      "config": {
        "timeout_seconds": 10,
        "success_threshold": 3,
        "failure_threshold": 3
      }
    }
  }
}

​
Discovery Example (etcd)

{
  "cluster_config": {
    "enabled": true,
    "region": "us-east-1",
    "gossip": {
      "port": 10101,
      "config": {
        "timeout_seconds": 10,
        "success_threshold": 3,
        "failure_threshold": 3
      }
    },
    "discovery": {
      "enabled": true,
      "type": "etcd",
      "service_name": "bifrost-cluster",
      "etcd_endpoints": [
        "http://etcd-1:2379",
        "http://etcd-2:2379"
      ],
      "dial_timeout": "10s"
    }
  }
}

​
Field Reference

​
cluster_config

FieldTypeDescription
enabledbooleanEnables cluster mode
regionstringRegion label for this node (defaults to "unknown" at runtime when omitted)
peersarray of stringsStatic peer addresses in host:port format
gossipobjectGossip/memberlist settings
discoveryobjectAutomatic node discovery settings

​
cluster_config.gossip

FieldTypeDescription
portintegerGossip port for this node
config.timeout_secondsintegerLiveness timeout
config.success_thresholdintegerSuccess count before healthy
config.failure_thresholdintegerFailure count before unhealthy

​
cluster_config.discovery

FieldTypeDescription
enabledbooleanEnables discovery process
typestringkubernetes, dns, udp, consul, etcd, mdns
service_namestringService identifier (required for consul, etcd, udp, typically mdns; optional for kubernetes and dns)
bind_portintegerPort appended to discovered hosts if missing
dial_timeoutstringGo duration string ("5s", "30s", "1m")
allowed_address_spacearray of stringsCIDR filters for discovered nodes
k8s_namespacestringKubernetes namespace for pod discovery
k8s_label_selectorstringKubernetes label selector
dns_namesarray of stringsDNS names to resolve
udp_broadcast_portintegerUDP broadcast port (required for udp)
consul_addressstringConsul address
etcd_endpointsarray of stringsetcd endpoint URLs
mdns_servicestringOptional mDNS service type override (e.g. "_bifrost-cluster._tcp")
For discovery.type: "mdns", service_name is sufficient for most setups. When mdns_service is omitted, Bifrost derives the mDNS service type as "_<service_name>._tcp". If you set mdns_service, it overrides the derived value and is used for both mDNS registration and browsing.
For discovery.type: "udp", configure both udp_broadcast_port and allowed_address_space.
For discovery-method deep dives and deployment patterns, see Enterprise Clustering.