cloud-init-dev team mailing list archive
-
cloud-init-dev team
-
Mailing list archive
-
Message #01854
Re: [Merge] ~raharper/cloud-init:network-config-doc into cloud-init:master
Ryan, this looks really good.
you did a lot of sleuthing!
there are some comments inline, i read mostly around the 'cloud-init' parts, i very lightly skimmed the v1 and v2 doc sections.
Diff comments:
> diff --git a/doc/rtd/topics/network-config-format-eni.rst b/doc/rtd/topics/network-config-format-eni.rst
> new file mode 100644
> index 0000000..e4bcbe7
> --- /dev/null
> +++ b/doc/rtd/topics/network-config-format-eni.rst
> @@ -0,0 +1,14 @@
> +.. _network_config_eni:
> +
> +Network Configuration ENI
> +-------------------------
> +
> +`Cloud-init`_ supports reading and writing network config in the ``ENI`` format
> +which is consumed by the ``ifupdown`` tool to parse and apply network configuration.
i'm not really sure of the value of this.
its kind of confusing in that _network_config_v1 and _network_config_v2 are
primarily *input* formats to cloud-init, where as ENI (and sysconfig) is
primarily an *output* format.
> +
> +Please reference existing `documentation`_ for the ``/etc/network/interfaces(5)``
> +format.
> +
> +.. _Cloud-init: https://launchpad.net/cloud-init
> +.. _documentation: http://manpages.ubuntu.com/manpages/trusty/en/man5/interfaces.5.html
> +.. vi: textwidth=78
> diff --git a/doc/rtd/topics/network-config-format-v2.rst b/doc/rtd/topics/network-config-format-v2.rst
> new file mode 100644
> index 0000000..c76e585
> --- /dev/null
> +++ b/doc/rtd/topics/network-config-format-v2.rst
> @@ -0,0 +1,498 @@
> +.. _network_config_v2:
> +
> +Networking Config Version 2
> +===========================
> +
> +Cloud-init's support for Version 2 network config is a subset of the
> +version 2 format defined for the `netplan`_ tool. Cloud-init supports
> +both reading and writing of Version 2; the latter support requires a
> +distro with `netplan`_ present.
> +
> +Cloud-init accepts a YAML input under the ``system_info`` config
> +namespace. The ``network`` key indicate that a user would like to specify a
> +custom networking configuration. Required elements of a network configuration
> +are ``version`` and one or more of possible device types. ::
> +
> + system_info:
i remember talking about this, but i'm not.
Definitely you can write this 'network:' config write into /etc/cloud/cloud.cfg (or .d/file.cfg).
i was playing with this the other day and put this together:
https://gist.github.com/smoser/45935e78bf1b21ee7696be083240aa0f
> + network:
> + version: 2
> + ethernets: []
> +
> +Supported device ``types`` values are as follows:
> +
> +- Ethernets (``ethernets``)
> +- Bonds (``bonds``)
> +- Bridges (``bridges``)
> +- VLANs (``vlans``)
> +
> +Each type block contains device definitions as a map where the keys (called
> +"configuration IDs"). Each entry under the ``types`` may include IP and/or
> +device configuration.
> +
> +Cloud-init does not current support ``wifis`` type that is present in native
> +`netplan`_.
> +
> +
> +Device configuration IDs
> +------------------------
> +
> +The key names below the per-device-type definition maps (like ``ethernets:``)
> +are called "ID"s. They must be unique throughout the entire set of
> +configuration files. Their primary purpose is to serve as anchor names for
> +composite devices, for example to enumerate the members of a bridge that is
> +currently being defined.
> +
> +There are two physically/structurally different classes of device definitions,
> +and the ID field has a different interpretation for each:
> +
> +Physical devices
> +
> +: (Examples: ethernet, wifi) These can dynamically come and go between
> + reboots and even during runtime (hotplugging). In the generic case, they
> + can be selected by ``match:`` rules on desired properties, such as name/name
> + pattern, MAC address, driver, or device paths. In general these will match
> + any number of devices (unless they refer to properties which are unique
> + such as the full path or MAC address), so without further knowledge about
> + the hardware these will always be considered as a group.
> +
> + It is valid to specify no match rules at all, in which case the ID field is
> + simply the interface name to be matched. This is mostly useful if you want
> + to keep simple cases simple, and it's how network device configuration has
> + been done for a long time.
> +
> + If there are ``match``: rules, then the ID field is a purely opaque name
> + which is only being used for references from definitions of compound
> + devices in the config.
> +
> +Virtual devices
> +
> +: (Examples: veth, bridge, bond) These are fully under the control of the
> + config file(s) and the network stack. I. e. these devices are being created
> + instead of matched. Thus ``match:`` and ``set-name:`` are not applicable for
> + these, and the ID field is the name of the created virtual device.
> +
> +Common properties for physical device types
> +-------------------------------------------
> +
> +**match**: *<(mapping)>*
> +
> +This selects a subset of available physical devices by various hardware
> +properties. The following configuration will then apply to all matching
> +devices, as soon as they appear. *All* specified properties must match.
> +The following properties for creating matches are supported:
> +
> +**name**: *<(scalar)>*
> +
> +Current interface name. Globs are supported, and the primary use case
> +for matching on names, as selecting one fixed name can be more easily
> +achieved with having no ``match:`` at all and just using the ID (see
> +above). Note that currently only networkd supports globbing,
> +NetworkManager does not.
> +
> +**macaddress**: *<(scalar)>*
> +
> +Device's MAC address in the form "XX:XX:XX:XX:XX:XX". Globs are not allowed.
> +
> +**driver**: *<(scalar)>*
> +
> +Kernel driver name, corresponding to the ``DRIVER`` udev property. Globs are
> +supported. Matching on driver is *only* supported with networkd.
> +
> +**Examples**::
> +
> + # all cards on second PCI bus
> + match:
> + name: enp2*
> +
> + # fixed MAC address
> + match:
> + macaddress: 11:22:33:AA:BB:FF
> +
> + # first card of driver ``ixgbe``
> + match:
> + driver: ixgbe
> + name: en*s0
> +
> +**set-name**: *<(scalar)>*
> +
> +When matching on unique properties such as path or MAC, or with additional
> +assumptions such as "there will only ever be one wifi device",
> +match rules can be written so that they only match one device. Then this
> +property can be used to give that device a more specific/desirable/nicer
> +name than the default from udev’s ifnames. Any additional device that
> +satisfies the match rules will then fail to get renamed and keep the
> +original kernel name (and dmesg will show an error).
> +
> +**wakeonlan**: *<(bool)>*
> +
> +Enable wake on LAN. Off by default.
> +
> +
> +Common properties for all device types
> +--------------------------------------
> +
> +**renderer**: *<(scalar)>*
> +
> +Use the given networking backend for this definition. Currently supported are
> +``networkd`` and ``NetworkManager``. This property can be specified globally
> +in ``networks:``, for a device type (in e. g. ``ethernets:``) or
> +for a particular device definition. Default is ``networkd``.
> +
> +.. note::
> +
> + Cloud-init only supports networkd backend if rendering version2 config
> + to the instance.
> +
> +**dhcp4**: *<(bool)>*
> +
> +Enable DHCP for IPv4. Off by default.
> +
> +**dhcp6**: *<(bool)>*
> +
> +Enable DHCP for IPv6. Off by default.
> +
> +**addresses**: *<(sequence of scalars)>*
> +
> +Add static addresses to the interface in addition to the ones received
> +through DHCP or RA. Each sequence entry is in CIDR notation, i. e. of the
> +form ``addr/prefixlen`` . ``addr`` is an IPv4 or IPv6 address as recognized
> +by ``inet_pton``(3) and ``prefixlen`` the number of bits of the subnet.
> +
> +Example: ``addresses: [192.168.14.2/24, 2001:1::1/64]``
> +
> +**gateway4**: or **gateway6**: *<(scalar)>*
> +
> +Set default gateway for IPv4/6, for manual address configuration. This
> +requires setting ``addresses`` too. Gateway IPs must be in a form
> +recognized by ``inet_pton(3)``
> +
> +Example for IPv4: ``gateway4: 172.16.0.1``
> +Example for IPv6: ``gateway6: 2001:4::1``
> +
> +**nameservers**: *<(mapping)>*
> +
> +Set DNS servers and search domains, for manual address configuration. There
> +are two supported fields: ``addresses:`` is a list of IPv4 or IPv6 addresses
> +similar to ``gateway*``, and ``search:`` is a list of search domains.
> +
> +Example: ::
> +
> + nameservers:
> + search: [lab, home]
> + addresses: [8.8.8.8, FEDC::1]
> +
> +**routes**: *<(sequence of mapping)>*
> +
> +Add device specific routes. Each mapping includes a ``to``, ``via`` key
> +with an IPv4 or IPv6 address as value. ``metric`` is an optional value.
> +
> +Example: ::
> +
> + routes:
> + - to: 0.0.0.0/0
> + via: 10.23.2.1
> + metric: 3
> +
> +Ethernets
> +~~~~~~~~~
> +Ethernet device definitions do not support any specific properties beyond the
> +common ones described above.
> +
> +Bonds
> +~~~~~
> +
> +**interfaces** *<(sequence of scalars)>*
> +
> +All devices matching this ID list will be added to the bond.
> +
> +Example: ::
> +
> + ethernets:
> + switchports:
> + match: {name: "enp2*"}
> + [...]
> + bonds:
> + bond0:
> + interfaces: [switchports]
> +
> +**parameters**: *<(mapping)>*
> +
> +Customization parameters for special bonding options. Time values are specified
> +in seconds unless otherwise specified.
> +
> +**mode**: *<(scalar)>*
> +
> +Set the bonding mode used for the interfaces. The default is
> +``balance-rr`` (round robin). Possible values are ``balance-rr``,
> +``active-backup``, ``balance-xor``, ``broadcast``, ``802.3ad``,
> +``balance-tlb``, and ``balance-alb``.
> +
> +**lacp-rate**: *<(scalar)>*
> +
> +Set the rate at which LACPDUs are transmitted. This is only useful
> +in 802.3ad mode. Possible values are ``slow`` (30 seconds, default),
> +and ``fast`` (every second).
> +
> +**mii-monitor-interval**: *<(scalar)>*
> +
> +Specifies the interval for MII monitoring (verifying if an interface
> +of the bond has carrier). The default is ``0``; which disables MII
> +monitoring.
> +
> +**min-links**: *<(scalar)>*
> +
> +The minimum number of links up in a bond to consider the bond
> +interface to be up.
> +
> +**transmit-hash-policy**: <*(scalar)>*
> +
> +Specifies the transmit hash policy for the selection of slaves. This
> +is only useful in balance-xor, 802.3ad and balance-tlb modes.
> +Possible values are ``layer2``, ``layer3+4``, ``layer2+3``,
> +``encap2+3``, and ``encap3+4``.
> +
> +**ad-select**: <*(scalar)>*
> +
> +Set the aggregation selection mode. Possible values are ``stable``,
> +``bandwidth``, and ``count``. This option is only used in 802.3ad mode.
> +
> +**all-slaves-active**: <*(bool)>*
> +
> +If the bond should drop duplicate frames received on inactive ports,
> +set this option to ``false``. If they should be delivered, set this
> +option to ``true``. The default value is false, and is the desirable
> +behavior in most situations.
> +
> +**arp-interval**: <*(scalar)>*
> +
> +Set the interval value for how frequently ARP link monitoring should
> +happen. The default value is ``0``, which disables ARP monitoring.
> +
> +**arp-ip-targets**: <*(sequence of scalars)>*
> +
> +IPs of other hosts on the link which should be sent ARP requests in
> +order to validate that a slave is up. This option is only used when
> +``arp-interval`` is set to a value other than ``0``. At least one IP
> +address must be given for ARP link monitoring to function. Only IPv4
> +addresses are supported. You can specify up to 16 IP addresses. The
> +default value is an empty list.
> +
> +**arp-validate**: <*(scalar)>*
> +
> +Configure how ARP replies are to be validated when using ARP link
> +monitoring. Possible values are ``none``, ``active``, ``backup``,
> +and ``all``.
> +
> +**arp-all-targets**: <*(scalar)>*
> +
> +Specify whether to use any ARP IP target being up as sufficient for
> +a slave to be considered up; or if all the targets must be up. This
> +is only used for ``active-backup`` mode when ``arp-validate`` is
> +enabled. Possible values are ``any`` and ``all``.
> +
> +**up-delay**: <*(scalar)>*
> +
> +Specify the delay before enabling a link once the link is physically
> +up. The default value is ``0``.
> +
> +**down-delay**: <*(scalar)>*
> +
> +Specify the delay before disabling a link once the link has been
> +lost. The default value is ``0``.
> +
> +**fail-over-mac-policy**: <*(scalar)>*
> +
> +Set whether to set all slaves to the same MAC address when adding
> +them to the bond, or how else the system should handle MAC addresses.
> +The possible values are ``none``, ``active``, and ``follow``.
> +
> +**gratuitious-arp**: <*(scalar)>*
> +
> +Specify how many ARP packets to send after failover. Once a link is
> +up on a new slave, a notification is sent and possibly repeated if
> +this value is set to a number greater than ``1``. The default value
> +is ``1`` and valid values are between ``1`` and ``255``. This only
> +affects ``active-backup`` mode.
> +
> +**packets-per-slave**: <*(scalar)>*
> +
> +In ``balance-rr`` mode, specifies the number of packets to transmit
> +on a slave before switching to the next. When this value is set to
> +``0``, slaves are chosen at random. Allowable values are between
> +``0`` and ``65535``. The default value is ``1``. This setting is
> +only used in ``balance-rr`` mode.
> +
> +**primary-reselect-policy**: <*(scalar)>*
> +
> +Set the reselection policy for the primary slave. On failure of the
> +active slave, the system will use this policy to decide how the new
> +active slave will be chosen and how recovery will be handled. The
> +possible values are ``always``, ``better``, and ``failure``.
> +
> +**learn-packet-interval**: <*(scalar)>*
> +
> +Specify the interval between sending learning packets to each slave.
> +The value range is between ``1`` and ``0x7fffffff``. The default
> +value is ``1``. This option only affects ``balance-tlb`` and
> +``balance-alb`` modes.
> +
> +
> +Bridges
> +~~~~~~~
> +
> +**interfaces**: <*(sequence of scalars)>*
> +
> +All devices matching this ID list will be added to the bridge.
> +
> +Example: ::
> +
> + ethernets:
> + switchports:
> + match: {name: "enp2*"}
> + [...]
> + bridges:
> + br0:
> + interfaces: [switchports]
> +
> +**parameters**: <*(mapping)>*
> +
> +Customization parameters for special bridging options. Time values are specified
> +in seconds unless otherwise specified.
> +
> +**ageing-time**: <*(scalar)>*
> +
> +Set the period of time to keep a MAC address in the forwarding
> +database after a packet is received.
> +
> +**priority**: <*(scalar)>*
> +
> +Set the priority value for the bridge. This value should be an
> +number between ``0`` and ``65535``. Lower values mean higher
> +priority. The bridge with the higher priority will be elected as
> +the root bridge.
> +
> +**forward-delay**: <*(scalar)>*
> +
> +Specify the period of time the bridge will remain in Listening and
> +Learning states before getting to the Forwarding state. This value
> +should be set in seconds for the systemd backend, and in milliseconds
> +for the NetworkManager backend.
> +
> +**hello-time**: <*(scalar)>*
> +
> +Specify the interval between two hello packets being sent out from
> +the root and designated bridges. Hello packets communicate
> +information about the network topology.
> +
> +**max-age**: <*(scalar)>*
> +
> +Set the maximum age of a hello packet. If the last hello packet is
> +older than that value, the bridge will attempt to become the root
> +bridge.
> +
> +**path-cost**: <*(scalar)>*
> +
> +Set the cost of a path on the bridge. Faster interfaces should have
> +a lower cost. This allows a finer control on the network topology
> +so that the fastest paths are available whenever possible.
> +
> +**stp**: <*(bool)>*
> +
> +Define whether the bridge should use Spanning Tree Protocol. The
> +default value is "true", which means that Spanning Tree should be
> +used.
> +
> +
> +VLANs
> +~~~~~
> +
> +**id**: <*(scalar)>*
> +
> +VLAN ID, a number between 0 and 4094.
> +
> +**link**: <*(scalar)>*
> +
> +ID of the underlying device definition on which this VLAN gets
> +created.
> +
> +Example: ::
> +
> + ethernets:
> + eno1: {...}
> + vlans:
> + en-intra:
> + id: 1
> + link: eno1
> + dhcp4: yes
> + en-vpn:
> + id: 2
> + link: eno1
> + address: ...
> +
> +
> +Examples
> +--------
> +Configure an ethernet device with networkd, identified by its name, and enable
> +DHCP: ::
> +
> + network:
> + version: 2
> + ethernets:
> + eno1:
> + dhcp4: true
> +
> +This is a complex example which shows most available features: ::
> +
> + network:
> + version: 2
> + ethernets:
> + # opaque ID for physical interfaces, only referred to by other stanzas
> + id0:
> + match:
> + macaddress: 00:11:22:33:44:55
> + wakeonlan: true
> + dhcp4: true
> + addresses:
> + - 192.168.14.2/24
> + - 2001:1::1/64
> + gateway4: 192.168.14.1
> + gateway6: 2001:1::2
> + nameservers:
> + search: [foo.local, bar.local]
> + addresses: [8.8.8.8]
> + lom:
> + match:
> + driver: ixgbe
> + # you are responsible for setting tight enough match rules
> + # that only match one device if you use set-name
> + set-name: lom1
> + dhcp6: true
> + switchports:
> + # all cards on second PCI bus; unconfigured by themselves, will be added
> + # to br0 below
> + match:
> + name: enp2*
> + mtu: 1280
> + bonds:
> + bond0:
> + interfaces: [id0, lom]
> + bridges:
> + # the key name is the name for virtual (created) interfaces; no match: and
> + # set-name: allowed
> + br0:
> + # IDs of the components; switchports expands into multiple interfaces
> + interfaces: [wlp1s0, switchports]
> + dhcp4: true
> + vlans:
> + en-intra:
> + id: 1
> + link: id0
> + dhcp4: yes
> + # static routes
> + routes:
> + - to: 0.0.0.0/0
> + via: 11.0.0.1
> + metric: 3
> +
> +.. _netplan: https://launchpad.net/netplan
> +.. vi: textwidth=78
> diff --git a/doc/rtd/topics/network-config.rst b/doc/rtd/topics/network-config.rst
> new file mode 100644
> index 0000000..c69b593
> --- /dev/null
> +++ b/doc/rtd/topics/network-config.rst
> @@ -0,0 +1,291 @@
> +*********************
> +Network Configuration
> +*********************
> +
> +- Default Behavior
> +- Disabling Network Configuration
> +- Fallback Networking
> +- Network Configuration Sources
> +- Network Configuration Outputs
> +- Network Output Policy
> +- Controlling and specifying network configuration
> +- Network Configuration Tools
> +- Examples
> +
> +Default Behavior
> +================
> +
> +`Cloud-init`_ 's network configuration behavior can be configured via
> +user-data. In the absense of user-data specifying network configuration,
network configuration is found in order of increasing precedence:
- datasource: network_data.json in OpenStack or network-config in NoCloud...
- system config ('network:' entry in /etc/cloud/cloud.cfg*)
- kernel command line (ip=) or network-config=<base64 blob>
User data cannot change the network config. This could probably be managed
in some way, but not generically . Ie, if the user-data had:
#include http://my.url/network-config
that isn't likely going to be supported.
> +`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 customizations.
> +
> +`Cloud-init`_ supports the following methods for disabling cloud-init.
> +
> +
> +**/var/lib/cloud/data/upgraded-network**
> +
> +If this file is present, cloud-init's network config is disabled
> +
> +**kernel command-line**
> +
> +
> +Cloud-init will check for a parameter ``network-config`` and the
> +value is expected to be Base64 encoded YAML string in the
> +``NETWORK_CONFIG_V1`` format. Specifially for disabling networking
> +the required string looks like: ::
> +
> + network-config={config: disabled}
> +
> +The actual string passed must be Base64 encoded: ::
> +
> + network-config=bmV0d29yay1jb25maWc9e2NvbmZpZzogZGlzYWJsZWR9Cg==
> +
> +**system_info config**
> +
> +In the combined cloud-init system_info configuration dictionary. ::
> +
> + system_info:
this can just be 'network: config: disabled'
> + network:
> + config: disabled
> +
> +If `Cloud-init`_ 's networking config has not been disabled, 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 a connection and then generate a network
> +configuration to issue a DHCP request on that interface.
> +
> +`Cloud-init`_ does not consider the following interface types as likely 'first'
> +network interfaces for fallback configuration; they are filtered out from
> +being selected.
> +
> +- **loopback**: ``lo``
> +- **Virtual Ethernet**: ``veth``
(except when inside a container), and i think maybe generically it does.
the key is that when searching for fallback config, no network confiuration
should have been done yet, so no bridge stuff should be there (or vlan or...)
> +- **Software Bridges**: ``bridge``
> +
> +`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 first check for an interface
> +named ``eth0``. If such an interface is not present, then `Cloud-init`_ picks
> +the first element in the list of interface name based on the output of
> +Python's sorted() method applied to the list.
> +
> +Finally after selecting the most likely interface, a configuration is
> +generated internally and applied to the system.
> +
> +
> +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 convert Datasource specific network configuration
> +from the datasource format into `Cloud-init`_ 's `NETWORK_CONFIG_V1` format.
the fact that it converts to V1 is internal information. the result is the same.
it renders that to the correct network configuration for the system.
> +
> +The following Datasources optionally provide network configuration:
> +
> +- ConfigDrive
> +
> + - :ref:`network_config_v1`
> + - :ref:`network_config_v2`
> + - :ref:`network_config_eni`
legacy
> +
> +- DigitalOcean
> +
> + - `DigitalOcean JSON metadata`_
> +
> +- NoCloud
> +
> + - :ref:`network_config_v1`
> + - :ref:`network_config_v2`
> + - :ref:`network_config_eni`
legacy
> +
> +- OpenNebula
> +
> + - :ref:`network_config_eni`
> +
> +- OpenStack
> +
> + - :ref:`network_config_eni`
legacy
> + - `OpenStack Metadata Service Network`_
> +
> +- SmartOS
> +
> + - `SmartOS JSON Metadata`_
> +
> +For more information on network configuration formats
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + network-config-format-eni.rst
> + network-config-format-v1.rst
> + network-config-format-v2.rst
> +
> +
> +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 Ubuntu and Debian.
> +
> +- Netplan
> +
> +Since Ubuntu 16.10 Yakkety, the ``netplan`` project has been an optional
> +network configuration tool which consumes :ref:`network_config_v2` input
> +and renders network configuration for supported backends such as
> +``systemd-networkd`` and ``NetworkManager``.
> +
> +- Sysconfig
> +
> +
> +Network Output Policy
> +=====================
> +Default network configuration for Fedora/RHEL/CentOS based distributions.
> +
> +The default policy for selecting a network ``renderer`` in `Cloud-init`_ is
> +
> +- 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']
> +
> +
> +Controlling and specifying network configuration
> +================================================
> +
> +
> +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 convertion V2 to sysconfig ::
> +
> + % tools/net-convert.py --network-data v2.yaml --kind yaml --output-kind sysconfig -d target
can we not document this output? i'm fine to show the *rendered* output files, but the 'Internal State' seems ... well, "Internal".
I'd just nix the output of the command, as it doesn't really add anything. if youw ant to show the input, you can
just show the input file.
> + Input YAML
> + ethernets:
> + eth7:
> + addresses:
> + - 192.168.1.5/255.255.255.0
> + gateway4: 192.168.1.254
> + eth9:
> + dhcp4: true
> + version: 2
> +
> +
> + Internal State
> + !!python/object:cloudinit.net.network_state.NetworkState
> + _network_state:
> + dns:
> + nameservers: []
> + search: []
> + interfaces:
> + eth7:
> + address: null
> + gateway: null
> + inet: inet
> + mac_address: null
> + mode: manual
> + mtu: null
> + name: eth7
> + subnets:
> + - address: 192.168.1.5/255.255.255.0
> + gateway: 192.168.1.254
> + type: static
> + type: physical
> + eth9:
> + address: null
> + gateway: null
> + inet: inet
> + mac_address: null
> + mode: manual
> + mtu: null
> + name: eth9
> + subnets:
> + - type: dhcp4
> + type: physical
> + routes: []
> + use_ipv6: false
> + _version: 2
> + use_ipv6: false
> +
> + % 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
> +
> +
> +Examples
> +========
> +
> +
> +
> +.. _Cloud-init: https://launchpad.net/cloud-init
> +.. _DigitalOcean JSON metadata: https://developers.digitalocean.com/documentation/metadata/#network-interfaces-index
> +.. _OpenStack Metadata Service Network: https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/metadata-service-network-info.html
> +.. _SmartOS JSON Metadata: https://eng.joyent.com/mdata/datadict.html
> +
> +.. vi: textwidth=78
--
https://code.launchpad.net/~raharper/cloud-init/+git/cloud-init/+merge/321397
Your team cloud init development team is requested to review the proposed merge of ~raharper/cloud-init:network-config-doc into cloud-init:master.
References
