From 1d2dfc5d879dc905f440697c2b805c9485dda821 Mon Sep 17 00:00:00 2001
From: Chad Smith <chad.smith@canonical.com>
Date: Wed, 4 Mar 2020 13:53:19 -0700
Subject: net: support network-config:disabled on the kernel commandline (#232)

Allow disabling cloud-init's network configuration via a plain-text kernel cmdline

Cloud-init docs indicate that users can disable cloud-init networking via kernel
command line parameter 'network-config=<YAML>'.  This does not work unless
the <YAML> payload base64 encoded.  Document the base64 encoding
requirement and add a plain-text value for disabling cloud-init network config:

    network-config=disabled

Also:
 - Log an error and ignore any plain-text network-config payloads that are
   not specifically 'network-config=disabled'.
 - Log a warning if network-config kernel param is invalid yaml but do not
   raise an exception, allowing boot to continue and use fallback networking.

LP: #1862702
---
 doc/rtd/topics/network-config.rst | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

(limited to 'doc')

diff --git a/doc/rtd/topics/network-config.rst b/doc/rtd/topics/network-config.rst
index 1520ba9a..0144dfae 100644
--- a/doc/rtd/topics/network-config.rst
+++ b/doc/rtd/topics/network-config.rst
@@ -25,17 +25,23 @@ For example, OpenStack may provide network config in the MetaData Service.
 
 **System Config**
 
-A ``network:`` entry in /etc/cloud/cloud.cfg.d/* configuration files.
+A ``network:`` entry in ``/etc/cloud/cloud.cfg.d/*`` configuration files.
 
 **Kernel Command Line**
 
-``ip=`` or ``network-config=<YAML config string>``
+``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
+  :ref:`network_config_v1` or :ref:`network_config_v2` format. Optionally it
+  can be compressed with ``gzip`` prior to Base64 encoding.
+
 
 Disabling Network Configuration
 ===============================
@@ -48,19 +54,19 @@ on other methods, such as embedded configuration or other customizations.
 
 **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``.
+`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={config: disabled}
+  network-config=disabled
 
 
 **cloud config**
 
-In the combined cloud-init configuration dictionary. ::
+In the combined cloud-init configuration dictionary, merged from
+``/etc/cloud/cloud.cfg`` and ``/etc/cloud/cloud.cfg.d/*``::
 
   network:
     config: disabled
-- 
cgit v1.2.3