Network Configuration¶
- Default Behavior
- Disabling Network Configuration
- Fallback Networking
- Network Configuration Sources
- Network Configuration Outputs
- Network Output Policy
- Network Configuration Tools
- Examples
Default Behavior¶
Cloud-init ‘s searches for network configuration in order of increasing precedence; each item overriding the previous.
Datasource
For example, OpenStack may provide network config in the MetaData Service.
System Config
A network:
entry in /etc/cloud/cloud.cfg.d/*
configuration files.
Kernel Command Line
ip=
or network-config=<Base64 encoded YAML config string>
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.
Note
The network-config value is expected to be a Base64 encoded YAML string in
Networking Config Version 1 or Networking Config Version 2 format. Optionally it
can be compressed with gzip
prior to Base64 encoding.
Disabling Network Configuration¶
Users may disable Cloud-init ‘s network configuration capability and rely on other methods, such as embedded configuration or other customizations.
Cloud-init supports the following methods for disabling cloud-init.
Kernel Command Line
Cloud-init will check additionally check for the parameter
network-config=disabled
which will automatically disable any network
configuration.
Example disabling kernel command line entry:
network-config=disabled
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.
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.
- loopback:
name=lo
- Virtual Ethernet:
name=veth*
- Software Bridges:
type=bridge
- Software VLANs:
type=vlan
Cloud-init will prefer network interfaces that indicate they are connected
via the Linux carrier
flag being set. If no interfaces are marked
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 in Cloud-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 in cloud-init:
- ENI
/etc/network/interfaces or ENI
is supported by the ifupdown
package
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.
Network Output Policy¶
The default policy for selecting a network renderer
in order of preference
is as follows:
- ENI
- Sysconfig
- Netplan
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', 'eni', 'sysconfig', 'freebsd', 'netbsd', 'openbsd']
Network Configuration Tools¶
Cloud-init contains one tool used to test input/output conversion between
formats. The tools/net-convert.py
in the Cloud-init source repository
is helpful for examining expected output for a given input format.
CLI Interface :
% tools/net-convert.py --help
usage: net-convert.py [-h] --network-data PATH --kind
{eni,network_data.json,yaml} -d PATH [-m name,mac]
--output-kind {eni,netplan,sysconfig}
optional arguments:
-h, --help show this help message and exit
--network-data PATH, -p PATH
--kind {eni,network_data.json,yaml}, -k {eni,network_data.json,yaml}
-d PATH, --directory PATH
directory to place output in
-m name,mac, --mac name,mac
interface name to mac mapping
--output-kind {eni,netplan,sysconfig}, -ok {eni,netplan,sysconfig}
Example output converting V2 to sysconfig:
% tools/net-convert.py --network-data v2.yaml --kind yaml \
--output-kind sysconfig -d target
% cat target/etc/sysconfig/network-scripts/ifcfg-eth*
# Created by cloud-init on instance boot automatically, do not edit.
#
BOOTPROTO=static
DEVICE=eth7
IPADDR=192.168.1.5/255.255.255.0
NM_CONTROLLED=no
ONBOOT=yes
TYPE=Ethernet
USERCTL=no
# Created by cloud-init on instance boot automatically, do not edit.
#
BOOTPROTO=dhcp
DEVICE=eth9
NM_CONTROLLED=no
ONBOOT=yes
TYPE=Ethernet
USERCTL=no