Skip to content

Commit ee8c12e

Browse files
kvapskvaps
authored
docs(install): add bonding (LACP) configuration how-to guide (#459)
## Summary - Add a how-to guide for configuring LACP (802.3ad) network bonding when deploying Cozystack with Talm - Covers interface discovery from `talm template` output, bond parameters, interface selection methods (busPath, name, MAC), VLAN on top of bond, and floating IP placement <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Documentation * Added comprehensive guide for configuring IEEE 802.3ad LACP network bonding in node configurations, including interface identification, bonding parameters, and virtual IP setup. * Enhanced documentation explaining that generated node configuration files contain discoverable network interfaces and disks, and can be customized before applying changes. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents 3af557e + 328119a commit ee8c12e

2 files changed

Lines changed: 212 additions & 0 deletions

File tree

‎content/en/docs/v1/install/how-to/bonding.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
title: "How to configure network bonding (LACP)"
3+
linkTitle: "Configure bonding (LACP)"
4+
description: "How to configure LACP (802.3ad) network bonding for link aggregation and redundancy"
5+
weight: 120
6+
---
7+
8+
Network bonding allows you to combine multiple physical network interfaces into a single logical interface.
9+
This provides increased bandwidth and link redundancy.
10+
11+
LACP (Link Aggregation Control Protocol, IEEE 802.3ad) is the most common bonding mode,
12+
which dynamically negotiates link aggregation with the network switch.
13+
14+
{{% alert color="warning" %}}
15+
LACP requires configuration on both the server and the network switch.
16+
Make sure your switch has a corresponding LACP port-channel configured for the server's ports.
17+
{{% /alert %}}
18+
19+
## Identify network interfaces
20+
21+
After running `talm template`, the generated node configuration file will contain
22+
a comment block with discovered network interfaces:
23+
24+
```yaml
25+
machine:
26+
network:
27+
# -- Discovered interfaces:
28+
# eno1:
29+
# hardwareAddr: aa:bb:cc:dd:ee:f0
30+
# busPath: 0000:02:00.0
31+
# driver: tg3
32+
# vendor: Broadcom Inc. and subsidiaries
33+
# product: NetXtreme BCM5719 Gigabit Ethernet PCIe
34+
# eno2:
35+
# hardwareAddr: aa:bb:cc:dd:ee:f1
36+
# busPath: 0000:02:00.1
37+
# driver: tg3
38+
# vendor: Broadcom Inc. and subsidiaries
39+
# product: NetXtreme BCM5719 Gigabit Ethernet PCIe
40+
# eth0:
41+
# hardwareAddr: aa:bb:cc:dd:ee:f2
42+
# busPath: 0000:04:00.0
43+
# driver: bnx2x
44+
# vendor: Broadcom Inc. and subsidiaries
45+
# product: NetXtreme II BCM57810 10 Gigabit Ethernet
46+
# eth1:
47+
# hardwareAddr: aa:bb:cc:dd:ee:f3
48+
# busPath: 0000:04:00.1
49+
# driver: bnx2x
50+
# vendor: Broadcom Inc. and subsidiaries
51+
# product: NetXtreme II BCM57810 10 Gigabit Ethernet
52+
```
53+
54+
Choose the interfaces you want to bond. Typically these are ports of the same speed
55+
connected to the same switch or switch stack. Note the `busPath` values — you will need them.
56+
57+
## Configure bonding
58+
59+
Edit the generated node configuration file (e.g. `nodes/node1.yaml`) and replace the default
60+
`machine.network.interfaces` section with a bond configuration:
61+
62+
```yaml
63+
machine:
64+
network:
65+
interfaces:
66+
- interface: bond0
67+
dhcp: false
68+
bond:
69+
mode: 802.3ad
70+
adSelect: bandwidth
71+
miimon: 100
72+
updelay: 200
73+
downdelay: 200
74+
minLinks: 1
75+
xmitHashPolicy: encap3+4
76+
deviceSelectors:
77+
- busPath: "0000:04:00.0"
78+
- busPath: "0000:04:00.1"
79+
addresses:
80+
- 192.168.100.11/24
81+
routes:
82+
- network: 0.0.0.0/0
83+
gateway: 192.168.100.1
84+
```
85+
86+
### Bond parameters explained
87+
88+
| Parameter | Value | Description |
89+
| --- | --- | --- |
90+
| `mode` | `802.3ad` | LACP — dynamic link aggregation with switch negotiation |
91+
| `adSelect` | `bandwidth` | Selects the active aggregator by highest total bandwidth |
92+
| `miimon` | `100` | Link monitoring interval in milliseconds |
93+
| `updelay` | `200` | Delay (ms) before a recovered link becomes active |
94+
| `downdelay` | `200` | Delay (ms) before a failed link is declared down |
95+
| `minLinks` | `1` | Minimum number of active links to keep the bond up |
96+
| `xmitHashPolicy` | `encap3+4` | Hash by IP and TCP/UDP port for load distribution across links |
97+
98+
### Selecting interfaces
99+
100+
The recommended way to select bond members is by PCI bus path using `deviceSelectors`.
101+
This is more reliable than interface names, which may change across reboots:
102+
103+
```yaml
104+
bond:
105+
deviceSelectors:
106+
- busPath: "0000:04:00.0"
107+
- busPath: "0000:04:00.1"
108+
```
109+
110+
Alternatively, you can select by interface name:
111+
112+
```yaml
113+
bond:
114+
interfaces:
115+
- eth0
116+
- eth1
117+
```
118+
119+
Or by hardware address:
120+
121+
```yaml
122+
bond:
123+
deviceSelectors:
124+
- hardwareAddr: "aa:bb:cc:dd:ee:f2"
125+
- hardwareAddr: "aa:bb:cc:dd:ee:f3"
126+
```
127+
128+
## VLAN on top of bond
129+
130+
You can create VLAN interfaces on top of the bond.
131+
This is useful for separating traffic (e.g. management, storage, tenant networks):
132+
133+
```yaml
134+
machine:
135+
network:
136+
interfaces:
137+
- interface: bond0
138+
dhcp: false
139+
bond:
140+
mode: 802.3ad
141+
adSelect: bandwidth
142+
miimon: 100
143+
updelay: 200
144+
downdelay: 200
145+
minLinks: 1
146+
xmitHashPolicy: encap3+4
147+
deviceSelectors:
148+
- busPath: "0000:04:00.0"
149+
- busPath: "0000:04:00.1"
150+
addresses:
151+
- 192.168.100.11/24
152+
routes:
153+
- network: 0.0.0.0/0
154+
gateway: 192.168.100.1
155+
vlans:
156+
- vlanId: 100
157+
addresses:
158+
- 10.0.0.11/24
159+
```
160+
161+
## Floating IP (VIP) with bonding
162+
163+
For control plane nodes, place the `vip` section on the interface (or VLAN)
164+
that is used for the cluster API endpoint:
165+
166+
```yaml
167+
machine:
168+
network:
169+
interfaces:
170+
- interface: bond0
171+
dhcp: false
172+
bond:
173+
mode: 802.3ad
174+
adSelect: bandwidth
175+
miimon: 100
176+
updelay: 200
177+
downdelay: 200
178+
minLinks: 1
179+
xmitHashPolicy: encap3+4
180+
deviceSelectors:
181+
- busPath: "0000:04:00.0"
182+
- busPath: "0000:04:00.1"
183+
addresses:
184+
- 192.168.100.11/24
185+
routes:
186+
- network: 0.0.0.0/0
187+
gateway: 192.168.100.1
188+
vip:
189+
ip: 192.168.100.10
190+
```
191+
192+
Make sure the floating IP matches the one configured in `values.yaml`.
193+
194+
## Apply configuration
195+
196+
After editing all node files, apply the configuration as usual:
197+
198+
```bash
199+
talm apply -f nodes/node1.yaml -i
200+
talm apply -f nodes/node2.yaml -i
201+
talm apply -f nodes/node3.yaml -i
202+
```
203+
204+
{{% alert color="info" %}}
205+
The `-i` (`--insecure`) flag is only needed for the first apply, when nodes are in maintenance mode.
206+
For already initialized nodes, omit the flag: `talm apply -f nodes/node1.yaml`.
207+
{{% /alert %}}

‎content/en/docs/v1/install/kubernetes/talm.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,11 @@ The `--insecure` (`-i`) parameter is required because Talm must retrieve configu
171171
from Talos nodes that are not initialized yet, awaiting in maintenance mode, and therefore unable to accept an authenticated connection.
172172
The nodes will be initialized only on the next step, with `talm apply`.
173173
174+
The generated files include a comment block with discovered network interfaces and disks.
175+
You can edit these files before applying to customize the network configuration.
176+
For example, if you need to configure network bonding (LACP), see
177+
[Configure bonding (LACP)]({{% ref "/docs/v1/install/how-to/bonding" %}}).
178+
174179
175180
## 4. Apply Configuration and Bootstrap a Cluster
176181

0 commit comments

Comments
 (0)