cloud-init-dev team mailing list archive

[Scott Moser <smoser@xxxxxxxxxx>]

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 dont think most common at all. Its legacy for sure, and never preferred.  Lets document that.

> +
> +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:

distros do not get access to the full config, they're only provided access
to the "system_info" portion.
I kind of think of 'system_info' as 'distribution configuration'.

network config, provided in /etc/cloud/cloud.cfg.d (or kernel command
line or from the datasource) specifies the desired networking
configuration that the system should end up with.   the system
configuration (system_info) may tell cloud-init which renderer(s) should
be used, or may just let cloudinit do the right thing.

Other places have access to the whole config, which gets merged/updated
with cloud-config provided via vendor-data or user-data.

> +    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,
> +`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:
> +    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``
> +- **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 following Datasources optionally provide network configuration:
> +
> +- ConfigDrive
> +
> +  - :ref:`network_config_v1`
> +  - :ref:`network_config_v2`
> +  - :ref:`network_config_eni`

:). yes, just mention that reading it is legacy.

> +
> +- DigitalOcean
> +
> +  - `DigitalOcean JSON metadata`_
> +
> +- NoCloud
> +
> +  - :ref:`network_config_v1`
> +  - :ref:`network_config_v2`
> +  - :ref:`network_config_eni`
> +
> +- OpenNebula
> +
> +  - :ref:`network_config_eni`
> +
> +- OpenStack
> +
> +  - :ref:`network_config_eni`
> +  - `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
> +  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.