Network Configuration

Talos Linux uses multi-document network configuration for defining network interfaces, routes, DNS resolution, and other network settings. Network configuration is separate from the main machine configuration document.

The legacy machine.network field is deprecated. Use the multi-document configuration types instead: NetworkDeviceConfig, ResolverConfig, StaticHostConfig, and KubeSpanConfig.

Network Device Configuration

Network devices are configured using separate NetworkDeviceConfig documents:

---
version: v1alpha1
kind: NetworkDeviceConfig
name: eth0
addresses:
  - 192.168.1.100/24
routes:
  - network: 0.0.0.0/0
    gateway: 192.168.1.1

Device Selection

Devices can be selected by interface name or by device selector:

name

string

The interface name (e.g., eth0, enp0s3).

deviceSelector

object

Select device by hardware attributes instead of interface name.

kind: NetworkDeviceConfig
deviceSelector:
  busPath: /pci0000:00/0000:00:1f.6
  hardwareAddress: 00:50:56:*

IP Addresses

addresses

array

Static IP addresses to assign to the interface in CIDR notation.

addresses:
  - 192.168.1.100/24
  - 2001:db8::100/64

DHCP Configuration

dhcp

boolean

Enable DHCP for IPv4 address assignment.

dhcpOptions

object

DHCP client options.

kind: NetworkDeviceConfig
name: eth0
dhcp: true
dhcpOptions:
  routeMetric: 100
  ipv4: true
  ipv6: false

DHCP Options

dhcpOptions.routeMetric

number

Metric for DHCP routes.

dhcpOptions.ipv4

boolean

default:"true"

Enable DHCPv4.

dhcpOptions.ipv6

boolean

default:"false"

Enable DHCPv6.

dhcpOptions.duidv6

string

DHCPv6 unique identifier.

Routes

routes

array

Static routes for this interface.

routes:
  - network: 0.0.0.0/0
    gateway: 192.168.1.1
    metric: 100
  - network: 10.0.0.0/8
    gateway: 192.168.1.254

Route Options

routes[].network

string

required

Destination network in CIDR notation.

routes[].gateway

string

Gateway IP address.

routes[].source

string

Source IP address for the route.

routes[].metric

number

Route metric/priority.

VLANs

vlans

array

VLAN sub-interfaces.

kind: NetworkDeviceConfig
name: eth0
vlans:
  - vlanId: 100
    addresses:
      - 10.0.100.10/24
    routes:
      - network: 10.0.0.0/8
        gateway: 10.0.100.1

Bonding

Create bonded interfaces:

kind: NetworkDeviceConfig
name: bond0
bond:
  mode: 802.3ad
  interfaces:
    - eth0
    - eth1
  lacpRate: fast
  xmitHashPolicy: layer3+4
addresses:
  - 192.168.1.100/24

Bond Options

bond.mode

string

required

Bonding mode: balance-rr, active-backup, balance-xor, broadcast, 802.3ad, balance-tlb, balance-alb.

bond.interfaces

array

required

List of interfaces to bond.

bond.lacpRate

string

LACP rate: slow or fast.

bond.xmitHashPolicy

string

Transmit hash policy for load balancing.

Bridge

Create bridge interfaces:

kind: NetworkDeviceConfig
name: br0
bridge:
  stp:
    enabled: true
  interfaces:
    - eth0
    - eth1
addresses:
  - 192.168.1.100/24

bridge.interfaces

array

required

List of interfaces to add to the bridge.

bridge.stp.enabled

boolean

default:"false"

Enable Spanning Tree Protocol.

Wireguard

Configure WireGuard VPN:

kind: NetworkDeviceConfig
name: wg0
wireguard:
  privateKey: <base64-private-key>
  listenPort: 51820
  peers:
    - publicKey: <peer-public-key>
      endpoint: 192.168.1.200:51820
      allowedIPs:
        - 10.10.0.0/24
addresses:
  - 10.10.0.1/24

DNS Resolution

Configure DNS resolvers using the ResolverConfig document:

---
version: v1alpha1
kind: ResolverConfig
nameservers:
  - 1.1.1.1
  - 8.8.8.8
searchDomains:
  - example.com
  - cluster.local

nameservers

array

required

List of DNS server IP addresses.

searchDomains

array

DNS search domains.

Static Host Entries

Define static hostname to IP mappings:

---
version: v1alpha1
kind: StaticHostConfig
hosts:
  - hostname: control-plane-1
    ip: 192.168.1.10
  - hostname: control-plane-2  
    ip: 192.168.1.11

hosts

array

required

List of hostname to IP address mappings.

Hostname Configuration

Set the machine hostname:

---
version: v1alpha1
kind: HostnameConfig
hostname: node-1

hostname

string

required

The hostname for the machine.

Time Sync Configuration

Configure NTP servers:

---
version: v1alpha1
kind: TimeSyncConfig
servers:
  - time.cloudflare.com
  - pool.ntp.org
bootTimeout: 5m

servers

array

NTP server addresses. Can also specify PTP devices like /dev/ptp0.

bootTimeout

duration

default:"infinity"

Timeout for time sync during boot. Set to infinity to wait forever.

KubeSpan

KubeSpan provides encrypted peer-to-peer mesh network:

---
version: v1alpha1
kind: KubeSpanConfig
enabled: true
advertiseKubernetesNetworks: true
filters:
  endpoints:
    - 0.0.0.0/0
    - ::/0

enabled

boolean

required

Enable KubeSpan.

advertiseKubernetesNetworks

boolean

default:"false"

Advertise Kubernetes pod/service networks over KubeSpan.

filters.endpoints

array

Filter endpoints by CIDR.

Complete Example: Dual Stack with Bonding

---
version: v1alpha1
kind: NetworkDeviceConfig
name: bond0
bond:
  mode: 802.3ad
  interfaces:
    - eth0
    - eth1
  lacpRate: fast
  xmitHashPolicy: layer3+4
addresses:
  - 192.168.1.100/24
  - 2001:db8::100/64
routes:
  - network: 0.0.0.0/0
    gateway: 192.168.1.1
  - network: ::/0
    gateway: 2001:db8::1
mtu: 9000
---
version: v1alpha1
kind: NetworkDeviceConfig
name: bond0.100
vlanId: 100
addresses:
  - 10.0.100.10/24
---
version: v1alpha1
kind: ResolverConfig
nameservers:
  - 1.1.1.1
  - 2606:4700:4700::1111
searchDomains:
  - cluster.local
---
version: v1alpha1
kind: HostnameConfig
hostname: control-plane-1
---
version: v1alpha1
kind: TimeSyncConfig
servers:
  - time.cloudflare.com