Cluster networking
This article refers to Platform v3.3.0. The current Platform version is v3.3.0.
Overview
A Barbara cluster runs on two separate networks. The first is the physical network your Edge Nodes already sit on; the second is a virtual network that Docker Swarm creates inside the cluster for application containers. Each one is configured in a different part of the Add Cluster wizard, and confusing the two is the most frequent cause of a virtual IP that never fails over.
In this article, you will learn what each network carries, which wizard fields belong to which network, and how to check your configuration before you create the cluster.
How cluster networking works
The nodes' physical network
This is your real local network: the addresses your Edge Nodes hold on their network interfaces, for example 192.168.1.147 and 192.168.1.167. Barbara does not create this network, it uses the one you already have.
Three wizard values belong to it:
- Advertised address — the node's own fixed IP address, which Docker Swarm uses for cluster control traffic.
- Unicast IP — the address the node uses to exchange KeepAlived heartbeats with the other nodes. It normally matches the Advertised address.
- Virtual IP — the single address clients use to reach the cluster. KeepAlived moves it between healthy nodes.
All three must be real addresses on the same network segment, and every node must be able to reach the others on it. The Virtual IP must also be free: no other device on the network can already hold it.
The Swarm overlay network
This is a virtual network that lives inside the cluster. Docker Swarm encapsulates its traffic and uses it so that application containers can reach each other as if every node were on a single LAN, regardless of which node each container runs on.
It is configured in Step 1 of the wizard, under Advanced Settings → Swarm Overlay Networks:
- Subnet Size — the prefix length of each overlay subnet, a number between
0and32. Default 24. - Default address Pool — the address range the overlay subnets are carved out of, given as an IP and a Netmask. Default 10.0.0.0 / 255.0.0.0.
Your nodes never need to reach these addresses directly. The overlay serves the applications, so in most deployments you keep the default values.
The two networks side by side
| Physical network | Swarm overlay network | |
|---|---|---|
| What it is | Your existing local network | A virtual network inside the cluster |
| Example | 192.168.1.0/24 | 10.0.0.0/8 (default) |
| Carries | Swarm control traffic, KeepAlived heartbeats, the virtual IP | Traffic between application containers |
| Configured with | Real, fixed addresses of your network | Default values in most cases |
| Where in the wizard | Step 1 (Virtual IP) and Step 2 (Advertised address, Unicast IP) | Step 1 → Advanced Settings |
A three-node cluster on 192.168.1.0/24 looks like this:
Virtual IP 192.168.1.224 ← clients connect here; KeepAlived owns it
│
┌───────────────┼───────────────┐ physical network 192.168.1.0/24
│ │ │
192.168.1.147 192.168.1.167 192.168.1.162 ← Advertised address / Unicast IP
│ │ │
[container] [container] [container]
10.0.1.3 10.0.1.4 10.0.2.7 ← Swarm overlay (Default address Pool)
Keeping the two networks apart
The virtual IP and every Unicast IP belong to the physical network, never to the Default address Pool. The address pool is the internal range Swarm hands out to containers, and putting a virtual IP inside it produces an address no client on your network can route to.
If your nodes are on 192.168.1.0/24, the virtual IP and each node's Unicast IP must also be on 192.168.1.0/24.
Each node's Virtual IP Interface determines which network the virtual IP is announced on. On a node with more than one interface, the interface you select and the virtual IP must belong to the same network segment. Select the interface that carries the network your clients use.
Choosing the overlay range
Changing the Default address Pool is rarely necessary. Change it when the default 10.0.0.0/8 range overlaps a network you already use, because the overlap causes routing conflicts between container traffic and your own infrastructure. Pick a private range that no network reachable from your nodes occupies, and keep Subnet Size at 24 unless you need a different number of overlay subnets.
Common misconfigurations
The wizard accepts an address on the wrong network without complaining, and the cluster reports itself as healthy afterwards, so these mistakes surface only when the virtual IP is actually needed.
- The virtual IP is on a different network than the nodes. Nothing in the interface flags it, and no client can reach the address.
- A node has no Unicast IP. That node does not take part in KeepAlived elections, so the virtual IP never moves to it.
- The virtual IP is already in use. Two devices answering for the same address produce intermittent connection failures that are hard to trace.
- The Virtual IP Interface points at the wrong interface. On a node with several interfaces, the virtual IP is announced on a segment your clients do not reach.
A Cluster Status of Healthy does not mean the virtual IP works. That status reports node availability only. Nothing in Barbara validates the network of the virtual IP or the Unicast IP, so a misconfigured cluster looks healthy until a failover is needed.
To check an existing cluster, open it from the Clusters view and compare each node's Advertised address with the cluster's Virtual IP: the network portion has to match. If it does not, the virtual IP cannot fail over, whatever the status column says.
The two planes are independent
KeepAlived and Docker Swarm operate independently of each other, which is why the virtual IP survives a cluster that has lost quorum: the address stays up on whichever node holds it even though Swarm can no longer schedule anything. The exception is a KeepAlived health check configured to test something that depends on Swarm, which couples the two.
Summary
A cluster carries two kinds of traffic on two different networks: node-to-node coordination and the virtual IP travel over your existing physical network, while application containers talk over the Swarm overlay. Barbara exposes both in one wizard, so a single form covers the addresses you own and the internal range Swarm manages for you.
With the distinction clear, continue to Clusters to create a cluster and fill in each field.