Skip to main content
Talos Linux provides multiple network configuration document types that allow granular control over networking. Modern configurations use separate document types instead of the deprecated machine.network section.

​
HostnameConfig

The HostnameConfig document configures the machine hostname, either statically or with automatic generation.

​
Document Structure

kind: HostnameConfig
apiVersion: v1alpha1
metadata:
  name: hostname

​
Configuration Fields

​
hostname
string
Static hostname to set for the machine. This has the highest priority over other hostname sources (DHCP, cloud-init).Conflicts with: auto field
kind: HostnameConfig
apiVersion: v1alpha1
hostname: controlplane-1.example.org
​
auto
string
Method to automatically generate a hostname for the machine.Available values:
  • stable - Generates a stable hostname based on machine identity
  • off - Disables automatic hostname generation; Talos waits for an external source (DHCP, cloud-init)
Conflicts with: hostname fieldAutomatic hostnames have the lowest priority over any other hostname sources.
kind: HostnameConfig
apiVersion: v1alpha1
auto: stable

​
Examples

kind: HostnameConfig
apiVersion: v1alpha1
hostname: worker-33

​
NetworkDeviceConfig

The NetworkDeviceConfig document (formerly the deprecated machine.network.interfaces) configures network interfaces on Talos machines.
The device configuration shown in the v1alpha1 machine.network.interfaces section is deprecated. Use the standalone NetworkDeviceConfig document type instead.

​
Device Selection

​
interface
string
The interface name (e.g., enp0s3). Mutually exclusive with deviceSelector.
interface: enp0s3
​
deviceSelector
object
Select a network device using selectors with wildcard support. Mutually exclusive with interface.

​
Address Configuration

​
addresses
array
Static IP addresses to assign to the interface. Can be specified in CIDR notation or as standalone addresses.
addresses:
  - 10.5.0.10/16
  - 192.168.3.7
​
dhcp
boolean
Enable DHCP for the interface. Supports these DHCP options:
  • OptionClasslessStaticRoute
  • OptionDomainNameServer
  • OptionDNSDomainSearchList
  • OptionHostName
dhcp: true
​
dhcpOptions
object
DHCP-specific options (requires dhcp: true).

​
Routing

​
routes
array
Static routes associated with the interface. Appended to DHCP routes if DHCP is enabled.
routes:
  - network: 0.0.0.0/0
    gateway: 10.5.0.1
    metric: 1024
​
mtu
integer
Interface MTU size. Overrides any MTU settings from DHCP.
mtu: 9000

​
Advanced Features

​
bond
object
Bond-specific configuration for bonded interfaces.
bond:
  mode: balance-rr
  interfaces:
    - eth0
    - eth1
​
bridge
object
Bridge-specific configuration.
bridge:
  stp:
    enabled: true
  interfaces:
    - eth0
    - eth1
​
vlans
array
VLAN configuration for the interface.
vlans:
  - vlanId: 100
    addresses:
      - 10.100.0.10/24
​
wireguard
object
WireGuard VPN configuration.
​
vip
object
Virtual (shared) IP address configuration for high availability.
vip:
  ip: 10.5.0.100
​
ignore
boolean
Skip configuration of this interface.
ignore: true
​
dummy
boolean
Specify that this interface should be a virtual-only, dummy interface.
dummy: true

​
Complete Examples

kind: NetworkDeviceConfig
apiVersion: v1alpha1
interface: eth0
addresses:
  - 10.5.0.10/24
routes:
  - network: 0.0.0.0/0
    gateway: 10.5.0.1
mtu: 1500

​
ResolverConfig

The ResolverConfig document (replaces deprecated machine.network.nameservers) configures DNS resolution. 
kind: ResolverConfig
apiVersion: v1alpha1
nameServers:
  - 1.1.1.1
  - 8.8.8.8
searchDomains:
  - example.com

​
StaticHostConfig

The StaticHostConfig document (replaces deprecated machine.network.extraHostEntries) adds static entries to /etc/hosts. 
kind: StaticHostConfig
apiVersion: v1alpha1
hosts:
  - ip: 10.0.0.10
    aliases:
      - database.local
      - db

​
KubeSpanConfig

The KubeSpanConfig document configures the KubeSpan overlay network for Talos clusters. 
kind: KubeSpanConfig
apiVersion: v1alpha1
enabled: true

​
Migration from Deprecated Fields

The following table shows the mapping from deprecated v1alpha1 fields to new document types:
Deprecated FieldNew Document Type
machine.network.hostnameHostnameConfig
machine.network.interfacesNetworkDeviceConfig
machine.network.nameserversResolverConfig
machine.network.searchDomainsResolverConfig
machine.network.extraHostEntriesStaticHostConfig
machine.network.kubespanKubeSpanConfig

​
Best Practices

Prefer device selectors over hard-coded interface names for better portability across different hardware.
deviceSelector:
  driver: virtio
Configure MTU based on your network infrastructure. Use jumbo frames (9000) for high-performance networks when supported.
Use bonding or VIP configuration for high availability scenarios.
Use multi-document configuration to separate network concerns for better maintainability.

Build docs developers (and LLMs) love

Get started for freeTalk to us