doc: document network configuration defaults policy and formats.

Add documentation for cloud-init networking configuration formats, default
behavior, policy and other specific details about how network config is
consumed and utilized.

1 files changed, 254 insertions, 0 deletions

diff --git a/doc/rtd/topics/network-config.rst b/doc/rtd/topics/network-config.rst
new file mode 100644
index 00000000..109c86f5
--- /dev/null
+++ b/doc/rtd/topics/network-config.rst
@@ -0,0 +1,254 @@
+*********************
+Network Configuration
+*********************
+
+- Default Behavior
+- Disabling Network Configuration
+- Fallback Networking
+- Network Configuration Sources
+- Network Configuration Outputs
+- Network Output Policy
+- Network Configuration Tools
+- Examples
+
+.. _default_behavior:
+
+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=<YAML config string>``
+
+User-data cannot change an instance's network configuration.  In the absense
+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 customizations.
+
+`Cloud-init`_ supports the following methods for disabling cloud-init.
+
+
+**Kernel Command Line**
+
+`Cloud-init`_ will check for a parameter ``network-config`` and the
+value is expected to be YAML string in the :ref:`network_config_v1` format.
+The YAML string may optionally be ``Base64`` encoded, and optionally
+compressed with ``gzip``.
+
+Example disabling kernel command line entry: ::
+
+  network-config={config: disabled}
+
+
+**cloud config**
+
+In the combined cloud-init configuration dictionary. ::
+
+  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.
+
+
+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:
+
+- :ref:`datasource_config_drive`
+
+  - `OpenStack Metadata Service Network`_
+  - :ref:`network_config_eni`
+
+- :ref:`datasource_digital_ocean`
+
+  - `DigitalOcean JSON metadata`_
+
+- :ref:`datasource_nocloud`
+
+  - :ref:`network_config_v1`
+  - :ref:`network_config_v2`
+  - :ref:`network_config_eni`
+
+- :ref:`datasource_opennebula`
+
+  - :ref:`network_config_eni`
+
+- :ref:`datasource_openstack`
+
+  - :ref:`network_config_eni`
+  - `OpenStack Metadata Service Network`_
+
+- :ref:`datasource_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, codename 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**
+
+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']
+
+
+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 :
+
+.. code-block:: bash
+
+  % 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:
+
+.. code-block:: bash
+
+  % 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
+
+
+.. _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