Network configuration - cloud-init 25.1.2 documentation (original) (raw)

Default behaviour

Cloud-init searches for network configuration in order of increasing precedence; each item overriding the previous.

Cloud-init will write out the following files representing the network-config processed:

User-data cannot change an instance’s network configuration. In the absence of network configuration in any of the above sources, cloud-init will write out a network configuration that will issue a DHCP request on a “first” network interface.

Disabling network configuration

Users may disable cloud-init’s network configuration capability and rely on other methods, such as embedded configuration or other customisations.

cloud-init supports the following methods for disabling cloud-init.

Kernel command line

Cloud-init will check for the parameter network-config=disabled, which will automatically disable any network configuration.

Example disabling kernel command line entry:

Cloud config

In the combined cloud-init configuration dictionary, merged from/etc/cloud/cloud.cfg and /etc/cloud/cloud.cfg.d/*:

network: config: disabled

If cloud-init’s networking config has not been disabled, and no other network information is found, then it will proceed to generate a fallback networking configuration.

Disabling network activation

Some datasources may not be initialized until after the network has been brought up. In this case, cloud-init will attempt to bring up the interfaces specified by the datasource meta-data using a network activator discovered by cloudinit.net.activators.select_activator.

This behaviour can be disabled in the cloud-init configuration dictionary, merged from /etc/cloud/cloud.cfg and/etc/cloud/cloud.cfg.d/*:

disable_network_activation: true

Fallback network configuration

Cloud-init will attempt to determine which, of any attached network devices, is most likely to have a connection and then generate a network configuration to issue a DHCP request on that interface.

Cloud-init runs during early boot and does not expect composed network devices (such as Bridges) to be available. Cloud-init does not consider the following interface devices as likely “first” network interfaces for fallback configuration; they are filtered out from being selected.

Cloud-init will prefer network interfaces that indicate they are connected via the Linux carrier flag being set. If no interfaces are marked as connected, then all unfiltered interfaces are potential connections.

Of the potential interfaces, cloud-init will attempt to pick the “right” interface given the information it has available.

Finally, after selecting the “right” interface, a configuration is generated and applied to the system.

Note

PhotonOS disables fallback networking configuration by default, leaving network unrendered when no other network config is provided. If fallback config is still desired on PhotonOS, it can be enabled by providing disable_fallback_netcfg: false in/etc/cloud/cloud.cfg:sys_config settings.

Network configuration sources

Cloud-init accepts a number of different network configuration formats in support of different cloud substrates. The datasource for these clouds incloud-init will detect and consume datasource-specific network configuration formats for use when writing an instance’s network configuration.

The following datasources optionally provide network configuration:

For more information on network configuration formats:

Network configuration outputs

Cloud-init converts various forms of user-supplied or automatically generated configuration into an internal network configuration state. From this state, cloud-init delegates rendering of the configuration to distro-supported formats. The following renderers are supported incloud-init:

NetworkManager

NetworkManager is the standard Linux network configuration tool suite. It supports a wide range of networking setups. Configuration is typically stored in /etc/NetworkManager.

It is the default for a number of Linux distributions; notably Fedora, CentOS/RHEL, and their derivatives.

ENI

/etc/network/interfaces or ENI is supported by the ifupdownpackage found in Alpine Linux, Debian and Ubuntu.

Netplan

Introduced in Ubuntu 16.10 (Yakkety Yak), Netplan has been the default network configuration tool in Ubuntu since 17.10 (Artful Aardvark). Netplan consumes Networking config Version 2 input and renders network configuration for supported backends such as systemd-networkd and NetworkManager.

Sysconfig

Sysconfig format is used by RHEL, CentOS, Fedora and other derivatives.

NetBSD, OpenBSD, FreeBSD

Network renders supporting BSD releases, which typically write configuration to /etc/rc.conf. Unique to BSD renderers is that each renderer also calls something akin to FreeBSD.start_services which will invoke applicable network services to setup the network, making network activators unneeded for BSD flavors at the moment.

Network output policy

Note

These are upstream defaults and are known to be overridden by downstream distributions.

The default policy for selecting a network renderer (in order of preference) is as follows:

The default policy for selecting a network activator (in order of preference) is as follows:

When applying the policy, cloud-init checks if the current instance has the correct binaries and paths to support the renderer. The first renderer that can be used is selected. Users may override the network renderer policy by supplying an updated configuration in cloud-config.

system_info: network: renderers: ['netplan', 'network-manager', 'eni', 'sysconfig', 'freebsd', 'netbsd', 'openbsd'] activators: ['eni', 'netplan', 'network-manager', 'networkd']

Network configuration tools

Cloud-init contains a command used to test input/output conversion between formats. The tools/net-convert.py in the cloud-init source repository is helpful in examining expected output for a given input format. If running these commands from the cloud-init source directory, make sure to set the correct path PYTHON_PATH=.

CLI Interface:

$ cloud-init devel net-convert --help

Example output:

usage: /usr/bin/cloud-init devel net-convert [-h] -p PATH -k {eni,network_data.json,yaml,azure-imds,vmware-imc} -d PATH -D {alpine,arch,azurelinux,debian,ubuntu,freebsd,dragonfly,gentoo,cos,netbsd,openbsd,almalinux,amazon,centos,cloudlinux,eurolinux,fedora,mariner,miraclelinux,openmandriva,photon,rhel,rocky,virtuozzo,opensuse,sles,openEuler} [-m name,mac] [--debug] -O {eni,netplan,networkd,sysconfig,network-manager}

options: -h, --help show this help message and exit -p PATH, --network-data PATH The network configuration to read -k {eni,network_data.json,yaml,azure-imds,vmware-imc}, --kind {eni,network_data.json,yaml,azure-imds,vmware-imc} The format of the given network config -d PATH, --directory PATH directory to place output in -D {alpine,arch,azurelinux,debian,ubuntu,freebsd,dragonfly,gentoo,cos,netbsd,openbsd,almalinux,amazon,centos,cloudlinux,eurolinux,fedora,mariner,miraclelinux,openmandriva,photon,rhel,rocky,virtuozzo,opensuse,sles,openeuler}, --distro {alpine,arch,azurelinux,debian,ubuntu,freebsd,dragonfly,gentoo,cos,netbsd,openbsd,almalinux,amazon,centos,cloudlinux,eurolinux,fedora,mariner,miraclelinux,openmandriva,photon,rhel,rocky,virtuozzo,opensuse,sles,openEuler} -m name,mac, --mac name,mac interface name to mac mapping --debug enable debug logging to stderr. -O {eni,netplan,networkd,sysconfig,network-manager}, --output-kind {eni,netplan,networkd,sysconfig,network-manager} The network config format to emit

Example of converting V2 to sysconfig:

$ cloud-init devel net-convert --network-data v2.yaml --kind yaml
--output-kind sysconfig -d target $ cat target/etc/sysconfig/network-scripts/ifcfg-eth*

Example output:

Created by cloud-init automatically, do not edit.

BOOTPROTO=static DEVICE=eth7 IPADDR=192.168.1.5/255.255.255.0 ONBOOT=yes TYPE=Ethernet USERCTL=no

Created by cloud-init automatically, do not edit.

BOOTPROTO=dhcp DEVICE=eth9 ONBOOT=yes TYPE=Ethernet USERCTL=no