> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cluster

> Configure enterprise cluster mode in config.json using peers or automatic discovery

<Warning>
  `cluster_config` is an enterprise capability. OSS builds ignore this section.
</Warning>

`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`

<Tip>
  At least one of `peers` or `discovery.enabled: true` must be configured when `cluster_config.enabled` is true.
</Tip>

***

## Minimal Runnable Configs

```json theme={null}
{
  "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

```json theme={null}
{
  "cluster_config": {
    "enabled": true,
    "region": "us-east-1",    
    "gossip": {
      "port": 10101,
      "config": {
        "timeout_seconds": 10,
        "success_threshold": 3,
        "failure_threshold": 3
      }
    }
  }
}
```

<Note>
  For version 1.4.x - you will need to expose 10102 TCP port and 10101 UDP port for cluster discovery.
</Note>

***

## Discovery Example (etcd)

```json theme={null}
{
  "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`

| Field       | Type             | Description                                                                  |
| ----------- | ---------------- | ---------------------------------------------------------------------------- |
| `enabled`   | boolean          | Enables cluster mode                                                         |
| `region`    | string           | Region label for this node (defaults to `"unknown"` at runtime when omitted) |
| `peers`     | array of strings | Static peer addresses in `host:port` format                                  |
| `gossip`    | object           | Gossip/memberlist settings                                                   |
| `discovery` | object           | Automatic node discovery settings                                            |

### `cluster_config.gossip`

| Field                      | Type    | Description                    |
| -------------------------- | ------- | ------------------------------ |
| `port`                     | integer | Gossip port for this node      |
| `config.timeout_seconds`   | integer | Liveness timeout               |
| `config.success_threshold` | integer | Success count before healthy   |
| `config.failure_threshold` | integer | Failure count before unhealthy |

### `cluster_config.discovery`

| Field                   | Type             | Description                                                                                                      |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `enabled`               | boolean          | Enables discovery process                                                                                        |
| `type`                  | string           | `kubernetes`, `dns`, `udp`, `consul`, `etcd`, `mdns`                                                             |
| `service_name`          | string           | Service identifier (required for `consul`, `etcd`, `udp`, typically `mdns`; optional for `kubernetes` and `dns`) |
| `bind_port`             | integer          | Port appended to discovered hosts if missing                                                                     |
| `dial_timeout`          | string           | Go duration string (`"5s"`, `"30s"`, `"1m"`)                                                                     |
| `allowed_address_space` | array of strings | CIDR filters for discovered nodes                                                                                |
| `k8s_namespace`         | string           | Kubernetes namespace for pod discovery                                                                           |
| `k8s_label_selector`    | string           | Kubernetes label selector                                                                                        |
| `dns_names`             | array of strings | DNS names to resolve                                                                                             |
| `udp_broadcast_port`    | integer          | UDP broadcast port (required for `udp`)                                                                          |
| `consul_address`        | string           | Consul address                                                                                                   |
| `etcd_endpoints`        | array of strings | etcd endpoint URLs                                                                                               |
| `mdns_service`          | string           | Optional mDNS service type override (e.g. `"_bifrost-cluster._tcp"`)                                             |

<Note>
  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.
</Note>

<Warning>
  For `discovery.type: "udp"`, configure both `udp_broadcast_port` and `allowed_address_space`.
</Warning>

***

For discovery-method deep dives and deployment patterns, see [Enterprise Clustering](/enterprise/clustering).